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