前言

• 在自动化测试的过程中，我们经常需要处理复杂的测试数据或需要输入多行文本。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 准备测试docstring
    When 这是一个简单的docstring:
      """
      这是一个测试文本
      包含两行内容
      """

# tests/test_docstring_demo.py
from functools import partial
from pytest_bdd import given, when, parsers, scenario

scenario = 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 测试用例，使测试代码更加清晰和专业。在实际项目中，建议根据具体需求灵活运用这一功能，以提升自动化测试的效率和可维护性。