Pytest-Bdd-Playwright 系列教程（14）：Docstring 参数

前言
一、什么是docstring?
二、基本语法
三、主要特点
四、实际例子
五、注意事项
六、使用建议
总结

前言

在自动化测试的过程中，我们经常需要处理复杂的测试数据或需要输入多行文本。Pytest-Bdd
提供了一种解决方案------Docstring 参数，它能够有效地解决这些问题；

Docstring 参数允许在 Gherkin 语法的步骤中嵌入多行文本，这在多种测试场景下都非常有用，包括但不限于复杂业务规则的描述、长文本输入的测试、详细测试步骤的记录、复杂预期结果与API 响应内容的验证以及文本内容的比对等。

一、什么是docstring?

在 Python 中，Docstring 是指位于函数、模块或类定义开头的字符串，通常用于描述其用途和参数等信息。而在 Pytest-BDD 中，Docstring 被赋予了新的含义，它是指在 Gherkin 步骤中定义的多行文本，这些文本使用三重引号 (""") 来包围。这种特性使得测试编写者能够在测试步骤中直接嵌入大量文本数据，而无需通过外部文件加载或硬编码的方式。

二、基本语法

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

gherkin 复制代码

When 这是一个简单的docstring:
      """
      这是一个测试文本
      包含两行内容
      """

上述示例中，When 关键字后面的步骤定义了一个 Docstring，其中包含了两行文本。这些文本将作为一个整体传递给相应的步骤函数。

三、主要特点

单个字符串传递：无论 Docstring 包含多少行文本，它都会作为一个单个的字符串传递给步骤函数；
多行支持：多行文本之间通过换行符 \n 分隔；
自动处理缩进：Pytest-BDD 会自动移除 Docstring 内部的前导缩进，确保文本格式的一致性；
专属性质：只有在定义了 Docstring 的步骤中，才能使用 Docstring 参数。

四、实际例子

gherkin 复制代码

# features/docstring_demo.feature
Feature: 文档字符串演示

  Scenario: 带有docstring的场景
    Given 准备测试docstring
    When 这是一个简单的docstring:
      """
      这是一个测试文本
      包含两行内容
      """

python 复制代码

# 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包含两行内容"

运行命令：

bash 复制代码

pytest ./tests/test_docstring_demo.py

运行结果如下：

五、注意事项

如果步骤没有定义docstring但在函数中使用了docstring参数，会抛出错误。
docstring的缩进会被自动处理，例如：

gherkin 复制代码

Then 步骤
"""
    即使有缩进
    也会被去除
"""

实际得到的字符串会是："即使有缩进\n也会被去除"

六、使用建议

长文本数据：当需要传递较长的测试数据时，使用 Docstring 可以使代码更加简洁和易读；
多行文本内容：适合用于测试多行文本内容，如日志文件、配置文件等；
复杂输出结果：可以用于验证复杂的输出结果，特别是当输出结果包含多行文本或结构化数据时；
API 响应验证：在测试 API 接口时，使用 Docstring 可以方便地定义和验证复杂的 JSON 响应。

总结

通过合理使用 Docstring 参数，我们可以更好地组织和管理 BDD 测试用例，使测试代码更加清晰和专业。在实际项目中，建议根据具体需求灵活运用这一功能，以提升自动化测试的效率和可维护性。