前言

• 在自動化測試的過程中，我們經常需要處理復雜的測試數據或需要輸入多行文本。Pytest-Bdd
  提供了一種解決方案——Docstring 參數，它能夠有效地解決這些問題；
• Docstring 參數允許在 Gherkin 語法的步驟中嵌入多行文本，這在多種測試場景下都非常有用，包括但不限于復雜業務規則的描述、長文本輸入的測試、詳細測試步驟的記錄、復雜預期結果與API 響應內容的驗證以及文本內容的比對等。

一、什么是docstring?

在 Python 中，Docstring 是指位于函數、模塊或類定義開頭的字符串，通常用于描述其用途和參數等信息。而在 Pytest-BDD 中，Docstring 被賦予了新的含義，它是指在 Gherkin 步驟中定義的多行文本，這些文本使用三重引號 (“”") 來包圍。這種特性使得測試編寫者能夠在測試步驟中直接嵌入大量文本數據，而無需通過外部文件加載或硬編碼的方式。

二、基本語法

在 Pytest-BDD 中使用 Docstring 的基本語法如下所示：

When 這是一個簡單的docstring:"""這是一個測試文本包含兩行內容"""

上述示例中，When 關鍵字后面的步驟定義了一個 Docstring，其中包含了兩行文本。這些文本將作為一個整體傳遞給相應的步驟函數。

三、主要特點

• 單個字符串傳遞：無論 Docstring 包含多少行文本，它都會作為一個單個的字符串傳遞給步驟函數；
• 多行支持：多行文本之間通過換行符 \n 分隔；
• 自動處理縮進：Pytest-BDD 會自動移除 Docstring 內部的前導縮進，確保文本格式的一致性；
• 專屬性質：只有在定義了 Docstring 的步驟中，才能使用 Docstring 參數。

四、實際例子

# features/docstring_demo.feature
Feature: 文檔字符串演示Scenario: 帶有docstring的場景Given 準備測試docstringWhen 這是一個簡單的docstring:"""這是一個測試文本包含兩行內容"""

# tests/test_docstring_demo.py
from functools import partial
from pytest_bdd import given, when, parsers, scenarioscenario = partial(scenario, 'docstring_demo.feature')@scenario('帶有docstring的場景')
def test_docstring_demo():pass@given('準備測試docstring')
def _():pass@when(parsers.parse('這是一個簡單的docstring:\n{docstring}'))
def step_with_docstring(docstring):# docstring參數將包含完整的文檔字符串內容assert docstring == "這是一個測試文本\n包含兩行內容"

運行命令：

pytest ./tests/test_docstring_demo.py

運行結果如下：

五、注意事項

• 如果步驟沒有定義docstring但在函數中使用了docstring參數，會拋出錯誤。
• docstring的縮進會被自動處理，例如：

Then 步驟
"""即使有縮進也會被去除
"""

實際得到的字符串會是：“即使有縮進\n也會被去除”

六、使用建議

• 長文本數據：當需要傳遞較長的測試數據時，使用 Docstring 可以使代碼更加簡潔和易讀；
• 多行文本內容：適合用于測試多行文本內容，如日志文件、配置文件等；
• 復雜輸出結果：可以用于驗證復雜的輸出結果，特別是當輸出結果包含多行文本或結構化數據時；
• API 響應驗證：在測試 API 接口時，使用 Docstring 可以方便地定義和驗證復雜的 JSON 響應。

總結

通過合理使用 Docstring 參數，我們可以更好地組織和管理 BDD 測試用例，使測試代碼更加清晰和專業。在實際項目中，建議根據具體需求靈活運用這一功能，以提升自動化測試的效率和可維護性。