automate-manual-test-cases

自动化手动测试用例

从手动测试用例生成可用于生产环境的自动化测试脚本，并复用项目现有的框架、模式和组件。

检查清单

按顺序完成所有步骤：

1. 分析项目架构 => 检测框架（1.1）、分析约定（1.2）、查找可复用组件（1.3）。
2. 理解手动测试 => 规范化输入（2.1）、处理含糊步骤（2.2）、检测不一致之处（2.3）。
3. 编写测试代码 => 使用现有 POM/模式实现（3.1-3.2）、添加断言（3.3）、输出代码（3.4）。
4. 验证并修复 => 执行测试（4.1），失败时修复：定位器 → 时序 → 断言 → 流程（4.2），最多尝试 3 次。
5. 完成收尾 => 保存测试（5.1）、管理测试数据和夹具（5.2）、运行相关测试并输出摘要（5.3）。

进度

• 步骤：1/5（分析项目架构）
• 上一步：（无）
• 下一步 ➡️ 步骤 2：理解手动测试。

完成每个步骤后更新此区块（参见 CLAUDE.md）。

步骤 1：分析项目架构

1.1 检测自动化框架

• 如果用户指定了框架（例如，“使用 CodeceptJS”）=> 信任该选择。

• 否则检查项目：

  • package.json 依赖项和脚本。
  • 配置文件（playwright.config.js、codecept.conf.js、cypress.json 等）。

• 如果无法检测到框架，请提供带编号的选项并询问：

  ❓ Which framework should I use?
  1. Playwright
  2. CodeceptJS
  3. Cypress
  4. Other (specify)
  

检测完成后，应用相应的参考指南：

• CodeceptJS 最佳实践
• Playwright 最佳实践

1.2 分析项目约定

• 测试结构和命名：文件夹（tests/、e2e/）和文件模式（*.spec.js 等）。
• 执行方式：package.json 脚本和测试命令。
• 配置：基础 URL、环境变量、全局设置。
• 断言风格：现有测试使用的库和模式。

1.3 查找可复用组件

扫描以下内容：

• 页面对象：现有定位器和方法（src/pages、pages/、page-objects/ 等）。
• 夹具/钩子：设置和清理模式。
• 测试数据：常量、CSV、JSON（test-data、src/testData 等）。
• 实用工具/辅助函数（utils/、helpers/ 等）。

分析时排除：

• 依赖文件夹（node_modules/）。
• 构建产物（dist/、build/、out/）。
• 隐藏/系统文件夹（.git/、.cache/）。
• 已弃用代码：deprecated/、legacy/、old/、backup/、__backup__/、archive/、temp/、标记为 outdated 的文件，以及较旧的版本文件夹（v1/、v2/，当存在较新版本时）。
• 不要自动排除用途不明确的文件夹。
• 用户指定的排除项始终优先于自动检测的排除项。

步骤 2：理解手动测试

输入可以是纯文本、Markdown 步骤，或源文件中的注释块（//、/* */）。

2.1 规范化输入结构

将输入转换为：

• summary（或场景标题）。
• preconditions（可选）。
• steps（必需）——按顺序排列的操作及其预期结果。

对于基于注释的输入：

• 将注释标记（//、*、-）视为结构提示。
• 将项目符号转换为有序步骤。
• 将 _Expected:_ 或 Expected Results 区块关联到前一步骤。
• 将多行预期结果合并为单个逻辑预期结果。

示例：

* Navigate to page  
  _Expected:_ Page opens
* Click once on the ${Custom statuses} block
  _Expected_: List includes "manual" option.

不得删除或改写原始手动测试注释。

• 在文件中原样保留这些注释。
• 在注释下方或旁边生成自动化代码。
• 使用标记分隔：// === AUTO-GENERATED TEST (based on steps above) ===

2.2 处理含糊步骤

对每个步骤进行分类：

• 清晰 => 继续。

• 部分清晰 => 做出合理假设，在输出中用 ⚠️ 标记（例如，“⚠️ 假设‘提交’按钮会提交表单”），然后继续。

• 不清晰且会阻碍流程 => 询问用户；如果有多个选项，请使用带编号的选项：

  ❓ Do you want to:
  1. Use existing LoginPage
  2. Create new LoginPage
  3. Skip login step
  

根据前面的步骤和常见 UI 模式（点击、输入、导航）推断。 不要因某一个不清晰的步骤而中断整个流程——继续处理其余步骤。

2.3 检测不一致之处

如果步骤操作、预期结果和已知 UI 模式相互冲突：

• 尽力进行合理判断并继续。
• 在输出中用 ⚠️ 标记。

步骤 3：编写测试代码

3.1 选择实现策略

• 存在可复用组件（Page Objects、辅助工具、fixtures）=> 复用它们；遵循项目模式和命名规范。
• 存在部分结构 => 扩展现有组件；与当前设计保持一致。
• 不存在结构 => 使用简单易读的定位器，尽量减少实现，不要引入不必要的抽象。

优先级：与项目保持一致，其次是可读性，最后是可维护性。

不要忽略现有 Page Objects，也不要重复定义选择器或逻辑。

3.2 遵循框架模式

• 一个测试，一个流程——每个测试只验证一个场景。
• 分离关注点：测试 => 断言和流程控制；Page Objects => UI 交互；utils => 可复用逻辑。
• 扩展，而非修改——向现有组件中添加内容，不要更改稳定代码。
• 使用 fixtures 进行设置、身份验证和共享状态管理。

请参阅 POM 最佳实践。

3.3 生成断言

• 根据手动步骤中的预期结果编写断言。
• 验证 UI 状态（可见性、文本、属性）、数据正确性和导航结果。
• 避免使用薄弱断言（仅检查页面是否加载），也不要过度断言无关细节。

3.4 输出测试代码

• 生成完整、可运行且能集成到现有框架中的代码。
• 遵循项目的格式和风格约定。
• 将代码放在适当的测试文件中，或建议一个存放位置。

步骤 4：验证并修复

4.1 执行测试

只运行生成的测试，不要运行完整测试套件：

• Playwright：npx playwright test path/to/spec.ts
• CodeceptJS：npx codeceptjs run path/to/test.js

如果通过 => 转到步骤 5。如果失败 => 修复（4.2）。

4.2 修复失败的测试

按以下优先顺序逐一修复问题：

1. 定位器——优先使用稳定的选择器（data-testid、aria-label），避免使用深层嵌套的 XPath。
2. 时序——使用框架原生等待，避免长时间固定等待。
3. 断言——匹配应用的实际行为，而非假设。
4. 流程——检查导航、前置条件和缺失步骤。

流程：找出一个失败原因 => 应用一项修复 => 重新运行 => 重复。 如果遇到问题无法继续，请保留最后一个可用版本以便回滚。

最多尝试修复 3 次。如果仍然失败，请停止并报告问题。

当根本原因不明确时，使用 debug-fix-failed-flaky-autotests skill 进行结构化的逐步诊断。

如果有 MCP/调试工具可用：

• 检查 DOM（document.querySelector(...).outerHTML）。
• 逐步执行。
• 收集日志、截图或跟踪记录。

4.3 稳定性标准

测试满足以下条件时，即为稳定：

• 连续通过 1-2 次。
• 不包含固定等待。
• 使用具有韧性的定位器。

步骤 5：收尾

5.1 保存最终测试代码

• 将可用的测试保存到项目中的适当位置。
• 遵循命名规范，并与现有测试保持一致。

5.2 测试数据和 fixtures

• 如果项目有集中管理的测试数据，请使用（JSON/CSV/constants）。
• 复用身份验证/设置 fixtures；不要在测试中重复设置逻辑。

请参阅 测试数据管理。

5.3 最终运行和总结

• 执行 1-2 个相关测试以确认集成情况（仅运行相关测试，不要运行完整测试套件）。

• 退出条件：测试连续通过 2 次。

• 展示规格到代码的映射：

  手动步骤	自动化操作
  导航至设置	basePage.clickOnNavigationMenuButton("Settings")

• 使用 最终总结模板输出最终总结。

示例：基于评论的请求

Use automate-manual-test-cases skill for CodeceptJS framework to write automation
script "tests/plan-for-guest.test.ts" based on manual steps below in this file as
comments (leaving comments in the file for further analysis). Set a specific "smoke"
tag for this test.
Use as reference for extra proper examples:
* `tests/payment-methods.test.ts` - Canonical test file with team approved format.
* `src/pages/paymentMethods.page.ts` - Good described payment page object.
Avoid mistakes from legacy code examples:
* `src/pages/paymentOutdated.page.ts` - Outdated example with old patterns.

Finally, verify that the generated test is passed on - `BASE_URL = 'https://test.com/'`
and provide final review for user.