SeleniumBase Case Plans 测试用例管理实战：以 Calculator 计算器测试 test_6_times_7_plus_12_equals

SeleniumBase Case Plans 测试用例管理实战：以 Calculator 计算器测试 test_6_times_7_plus_12_equals_54 为例

【免费下载链接】SeleniumBaseAPIs for browser automation, testing, and bypassing bot-detection. Includes CDP Mode: A stealthy configuration for chromium that passes every bot detection test.项目地址: https://gitcode.com/GitHub_Trending/se/SeleniumBase

导读

SeleniumBase 是面向浏览器自动化、测试与反机器人检测的 Python 框架，而Case Plans（测试用例计划）是其中一套基于 Markdown 表格的测试用例管理方案。本文以仓库中的实例文档 examples/case_plans/test_calculator.CalculatorTests.test_6_times_7_plus_12_equals_54.md 为骨架，结合 examples/test_calculator.py、Case Plans 生成器源码以及 Behave 步骤定义，完整拆解"从 Case Plan 到可运行测试"的全过程。读完本文，你将掌握 Case Plans 的文件格式、生成与汇总命令、Markdown 表格书写规范，以及 Calculator 示例测试的每一行代码与底层实现原理。

一、Case Plan 文件长什么样：读懂关联文档

关联文档examples/case_plans/test_calculator.CalculatorTests.test_6_times_7_plus_12_equals_54.md是 SeleniumBase 仓库中最典型的"已定制化"Case Plan 示例，全文如下：

``test_calculator.py::CalculatorTests::test_6_times_7_plus_12_equals_54`` --- | # | Step Description | Expected Result | | - | ---------------- | --------------- | | 1 | Open https://seleniumbase.io/apps/calculator. <br /> Perform the following calculation: ``6 × 7 + 12`` | The output is ``54`` after pressing ``=`` |

该文件的结构非常清晰，由三个部分组成：

第一行（测试定位符）：以两个反引号包裹的test_calculator.py::CalculatorTests::test_6_times_7_plus_12_equals_54，格式为文件名.py::类名::方法名。这正是 pytest 收集测试的标准 ID 格式，是 Case Plan 与具体测试代码一一对应的"身份证"。
第二行（分隔线）：---，用于将测试定位符与下方的 Markdown 表格区分开。
Markdown 测试表格：表头为#（步骤序号）、Step Description（步骤描述）、Expected Result（预期结果）。本用例只含一步：打开计算器页面并执行6 × 7 + 12，按下=后输出应为54。

该 Case Plan 的核心语义是：以人类可读的自然语言描述一个测试步骤及其验收标准，而真正的自动化验证则由测试代码完成。当渲染在 GitHub 等支持 Markdown 的代码托管平台上时，这份表格会直接显示为规整的测试计划，无需打开任何 GUI 工具即可被团队成员审阅。

二、与 Case Plan 对应的真实测试代码

Case Plan 描述的测试在仓库中真实存在，其实现位于 examples/test_calculator.py：

"""Test the SeleniumBase Calculator App""" from seleniumbase import BaseCase BaseCase.main(__name__, __file__) class CalculatorTests(BaseCase): def test_6_times_7_plus_12_equals_54(self): self.goto("seleniumbase.io/apps/calculator") self.click('button[id="6"]') self.click("button#multiply") self.click('button[id="7"]') self.click("button#add") self.click('button[id="1"]') self.click('button[id="2"]') self.click("button#equal") self.assert_exact_text("54", "input#output")

对照 Case Plan 逐行解读：

2.1 选择器风格说明

测试代码中混用了两种选择器写法，这在 SeleniumBase 中都是合法且等价的：

'button[id="6"]'：标准 CSS 属性选择器，定位 id 为6的 button 元素；
"button#multiply"：CSS ID 简写，等价于button[id="multiply"]。

self.click()是 SeleniumBaseBaseCase提供的高级点击方法，内部已封装了等待元素可见、滚动到元素、处理遮挡等常见问题，因此这里的每一步点击都无需手写显式等待。

2.2`assert_exact_text`的精确断言语义

最后一行断言使用的方法在 seleniumbase/fixtures/base_case.py#L10964 中有明确定义：

"Similar toassert_text(), but the text must be exact, rather than exist as a subset of the full text. (Extra whitespace at the beginning or the end doesn't count.)"

即：assert_exact_text(text, selector)要求元素文本与期望值完全一致（首尾空白被忽略），而assert_text只要求期望文本是元素文本的子串。从源码实现看，它的默认超时时间为settings.SMALL_TIMEOUT，内部依次处理了 Shadow DOM 选择器（__is_shadow_selector）、CDP 模式（__is_cdp_swap_needed时转发给self.cdp.assert_exact_text）以及 Demo 模式高亮等分支。因此对计算器输出框input#output断言"54"，可以确保运算结果恰好是 54 而不是546或包含其他字符的文本。

2.3 运行该测试

在仓库根目录执行：

pytest examples/test_calculator.py -q

如需只运行本 Case Plan 对应的这一个方法，可用 pytest 的-k过滤：

pytest examples/test_calculator.py -k test_6_times_7_plus_12_equals_54 -q

运行前提是已安装 SeleniumBase 及其依赖（详见 help_docs/install.md），并且机器上存在可用的浏览器驱动（SeleniumBase 会自动下载所需驱动）。

三、Case Plans 机制：Markdown 表格驱动的测试用例管理

单个 Case Plan 文件只是载体，支撑它的是一整套以 help_docs/case_plans.md 为说明文档、以 seleniumbase/console_scripts/sb_caseplans.py 为实现的测试用例管理系统。其核心设计思想是：用 Markdown 表格编写测试计划，直接在 GitHub 等支持 Markdown 的代码托管平台中展示，并以case_summary.md汇总所有用例。

3.1 三个状态等级

系统为每个 Case Plan 定义了三种状态（见sb_caseplans.py中view_summary_of_existing_case_plans的判定逻辑）：

🔵已定制化（customized tables）：表格中包含真实测试步骤，而非占位符——判定条件是文件中不包含| 1 | Perform Action 1 | Verify Action 1 |这一默认占位行；
⭕使用样板代码（boilerplate code）：仍保留默认生成的占位步骤，尚未填写真实内容；
🚧缺少表格（missing a table）：文件内容过少，不满足"竖线数 ≥ 9 且短横线数 ≥ 3"的最小 Markdown 表格判定条件。

本文关联文档所属的test_calculatorCase Plan 即属于 🔵 已定制化状态，这从仓库根目录 examples/case_summary.md 的汇总表也可以印证：12 个 Case Plan 全部为 🔵 已定制化表格。

3.2 如何生成 Case Plan 样板文件

Case Plans 提供 GUI 生成器，通过控制台命令启动：

sbase caseplans

该命令在sb_caseplans.py的main()中实现：内部通过pytest --collect-only -q --rootdir="./"收集当前目录下所有测试（源码位于 seleniumbase/console_scripts/sb_caseplans.py），再用 tkinter 弹出选择界面。你可以通过附加参数限制收集范围，规则与 pytest 的用例发现规则一致：

sbase caseplans # 收集当前目录全部测试 sbase caseplans -k agent # 仅收集名称匹配 "agent" 的测试 sbase caseplans -m marker2 # 仅收集标记为 marker2 的测试 sbase caseplans test_suite.py # 仅收集指定测试文件 sbase caseplans offline_examples/ # 仅收集指定目录下的测试

在 GUI 中选中缺少 Case Plan 的测试后，点击Generate boilerplate Case Plans for selected tests missing them，系统会为每个测试生成样板文件。生成逻辑（generate_case_plan_boilerplates）要点如下：

文件名由测试 ID 转换而来：get_test_id()将test_calculator.py::CalculatorTests::test_...中的.py::与::替换为.，再拼接.md后缀，得到test_calculator.CalculatorTests.test_6_times_7_plus_12_equals_54.md；
文件存放位置与测试文件所在目录相关：测试在根目录时放在case_plans/文件夹；测试在子目录时放在<子目录>/case_plans/文件夹；
样板内容即帮助文档中展示的占位表格：

``proxy_test.py::ProxyTests::test_proxy`` --- | # | Step Description | Expected Result | | - | ---------------- | --------------- | | 1 | Perform Action 1 | Verify Action 1 | | 2 | Perform Action 2 | Verify Action 2 |

生成后需要像本文关联文档那样，把占位步骤改写为真实的步骤描述与预期结果，才能完成从 ⭕ 到 🔵 的升级。

3.3 生成汇总文件 case_summary.md

点击 GUI 中的Generate Summary of existing Case Plans按钮（对应源码中的view_summary_of_existing_case_plans），系统会扫描所有已存在的 Case Plan，生成一个汇总文件case_summary.md，存放于启动 GUI 的当前目录（注意：这与单个样板文件生成到case_plans/文件夹的位置不同）。汇总文件包含状态统计表与可折叠的用例明细（<details>/<summary>），仓库中的实例如 examples/case_summary.md 所示。

四、Markdown 表格书写规范

Case Plans 之所以能在代码托管平台正常渲染，依赖的是严格的 Markdown 表格语法。帮助文档 help_docs/case_plans.md 特别强调了以下要点：

管道符、短横线与空格的位置必须正确：表头行、分隔行（| - | ---------------- | --------------- |）与数据行的列数必须一致，分隔行中的短横线数量不限，但每列至少一个-；
单元格内换行使用<br />：例如关联文档中的 `Open https://seleniumbase.io/apps/calculator.
Perform the following calculation: ``6 × 7 + 12```，这在 GitHub 渲染时会显示为同一单元格内的两行文本；
空单元格用| |表示：两个管道符之间放一个空格，表示该单元格为空；
测试 ID 用双反引号包裹：形如``test_calculator.py::CalculatorTests::test_...``，保证在表格之外也能以等宽字体清晰展示。

遵循以上规范，即可保证 Case Plan 文件在 GitHub、GitLab 等平台正确渲染为可读性极佳的测试计划表。

五、同类测试的多种实现方式：Behave BDD 视角

test_calculator这一计算器场景在仓库中并非只有 pytest 一种实现。以 examples/behave_bdd/features/steps/calculator.py 为例，Behave BDD 风格下每个计算器按键都被封装为 step 定义：

@step("Open the Calculator App") def go_to_calculator(context): context.sb.goto("https://seleniumbase.io/apps/calculator") @step("Press ×") def press_multiply(context): context.sb.click("button#multiply") @step("Press +") def press_add(context): context.sb.click("button#add") @step("Press =") def press_equal(context): context.sb.click("button#equal") @step('Verify output is "{output}"') def verify_output(context, output): sb = context.sb sb.assert_exact_text(output, "#output")

对应的 feature 文件（如 examples/behave_bdd/features/calculator.feature）可以直接用自然语言书写行为：

Scenario: ... Given Open the Calculator App When Evaluate [6×7+12] Then Verify output is "54"

可以看到，无论是 pytest 方法式还是 Behave BDD 式，底层调用的断言方法完全相同（都是assert_exact_text），验证的也是同一个期望结果54。这恰好说明 Case Plan 表格描述的是与实现方式无关的测试意图——同样的计划可以由 pytest、Behave 甚至 CDP Mode 脚本（参考 examples/cdp_mode/raw_cdp.py 等示例）来落地。

六、从 Case Plan 到质量闭环：小结

回顾整条链路，SeleniumBase 的 Case Plans 提供了一套轻量而完整的测试用例管理实践：

编写计划：用sbase caseplans的 GUI 为既有测试一键生成样板 Case Plan，或直接手写测试ID + --- + Markdown 表格三件套；
定制步骤：把样板占位行改写为真实的步骤描述与预期结果（如本文关联文档6 × 7 + 12 = 54），完成 🔵 状态升级；
汇总展示：用Generate Summary of existing Case Plans生成case_summary.md，在代码托管平台直接呈现全部用例的状态看板；
落地执行：Case Plan 中的每个步骤都有对应的可运行测试代码（examples/test_calculator.py），验收标准最终由assert_exact_text等断言方法在真实浏览器中自动验证。

这种"人可读的计划 + 机器可执行的代码"双轨结构，让测试文档不再是与代码脱节的静态表格，而是与仓库中真实测试一一对应的活文档。若想进一步了解 Case Plans 的完整说明与更多示例，可查阅 help_docs/case_plans.md 及 examples/case_plans 目录下的其余 7 份 Case Plan 文件。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析