qa-project-bootstrap

一名新 QA 工程师看了 README 后就被要求“自己摸索”，可能要花两周时间在反复试错中养成坏习惯；而未经审查、继承下来的测试套件则可能藏着不稳定测试和覆盖率缺口，直到它们在生产环境中暴露出来。本技能可缩短提交首个测试的时间，并产出三项具体成果：一份 30 天成长计划、一份涵盖五个维度的测试架构审查，以及一份框架指南文档。每个部分都服务于同一项指标——快速将一个真实测试合并到 main，并确保它在 CI 中通过。

**开始之前：**检查项目根目录中是否存在 .agents/qa-project-context.md。如果存在，它就能回答大多数发现阶段的问题，并提供入职所需的技术背景。如果不存在，创建该文件就是第一项任务。

快速导航

本技能适用于三种不同需求。确认你的需求，跳转到相应部分，其余部分可略过。

情况	跳转到	输出
将新人引入现有团队	前 30 天检查清单 → 导师指导模式	一份包含负责人和日期的 30 天成长计划
接手一个没有入职文档的现有测试套件	测试架构审查（根据 team_maturity 确定范围）	一份 1-2 页的发现报告，涵盖五个维度
需要一份供所有测试编写者使用的参考文档	框架指南模板	一份针对项目定制的 walkthrough.md

完整的入职流程通常需要这三项；快速健康检查只需要架构审查。

---

发现阶段问题

入职对象是谁？

1. **新 QA 工程师，还是参与编写测试的开发者？**QA 工程师需要了解测试策略和代码库；参与编写测试的开发者需要熟悉框架模式和约定。两者的成长路径有很大差异。

2. **对测试框架的熟悉程度如何？**是第一次使用 Playwright/Cypress/pytest？有经验，但刚接触这个代码库？还是经验丰富，只需要了解约定？这决定了框架指南需要包含多少内容。

3. **是独立负责 QA，还是加入现有 QA 团队？**独立负责 QA 的人员需要从头建立约定。加入团队则意味着要了解现有模式，并按照既有规范开展工作。

项目状态

4. **是否已有测试框架？**如果有：框架状况如何？如果没有：第一步是选择框架（参见 test-strategy 技能）。

5. **项目是否有 .agents/qa-project-context.md？**如果没有，创建该文件应列为高优先级入职任务——这会促使新人记录学到的内容，让整个团队受益。

6. **是否有本地环境设置文档？**新人能否在第一天内运行完整技术栈并执行测试？如果环境设置耗时超过 2 小时，就应先改进流程，再进行入职。

访问权限和工具

7. **是否已设置所有必需的账户和权限？**包括代码仓库访问权限、CI 仪表板、预发布环境、测试数据账户、缺陷跟踪工具和沟通渠道。第一天缺少访问权限会浪费时间，也会让人感到沮丧。

---

核心原则

1. 将首个测试合并所需的时间作为成功指标

衡量入职是否成功，最重要的指标就是新人多快能将一个真实测试合并到主分支。不是教程练习，不是只在本地运行的实验——而是一个能在 CI 中运行、验证真实产品行为的测试。目标：在前两周内完成。

2. 循序渐进地增加复杂度

从简单开始，逐步提高难度。第一个测试：冒烟测试或页面加载验证。第二个测试：表单交互。第三个测试：多步骤用户流程。到第三周，新人应开始为冲刺需求编写测试。第一天就让人处理涉及多个服务的复杂流程，会引发焦虑并养成坏习惯。

3. 记录团队隐性知识

每当新人提出一个文档中没有解答的问题，就意味着团队隐性知识正在流失。入职流程应将这些答案整理成永久文档——最好记录在 .agents/qa-project-context.md、框架演练文档或代码注释中。新人是编写这类文档的最佳人选，因为他们最清楚缺少了哪些内容。

4. 先结对，再独立完成

最初的 3 个测试应结对编写——由新人操作，经验丰富的团队成员引导。结对能传递隐性知识（不仅是怎么做，还包括为什么这样做），也比单独阅读文档更快地建立信心。

5. 让正确的做法成为最简单的做法

如果正确的测试编写方式比错误的方式更难，人们就会用错误的方式编写测试。确保测试工具、固定装置、页面对象和数据工厂能让推荐模式成为最省力的选择。如果新人为了遵循规范而不得不与框架较劲，就改进框架。

根据团队成熟度调整（在 .agents/qa-project-context.md 中设置 team_maturity）：

• startup — 聚焦第 1–10 天：让一个测试框架运行起来，并覆盖一条关键路径。在建立可用基线之前，暂缓流程形式。
• growing — 完整的 30 天计划：选择框架、集成 CI、建立覆盖率基线、记录团队规范。
• established — 30 天计划，外加：审查现有测试套件中的反模式、提出工具升级建议、建立指标基线、安排定期质量评审。

---

前 30 天检查清单

第 1 周：环境、访问权限与熟悉情况

第 1–2 天：设置

• 已克隆仓库，并能在本地构建
• 已配置所有环境变量（.env.local、测试凭据）
• 应用已在本地运行（前端 + 后端 + 数据库）
• 测试套件可在本地运行并通过（或已记录已知失败项）
• IDE 已配置推荐扩展（测试运行器插件、代码检查器、格式化工具）
• 已获得访问权限：CI 仪表板、预发布环境、缺陷跟踪器、团队频道

第 3–4 天：熟悉情况

• 阅读 .agents/qa-project-context.md（如果不存在，则创建该文件）
• 与一位团队成员一起了解测试目录结构
• 了解测试金字塔：单元测试、集成测试和 E2E 测试分别有多少
• 查看 CI 流水线：PR 时运行什么、每晚运行什么、什么会阻止合并
• 找出最重要的 5 条用户关键流程（这些将是最初的测试目标）
• 以观察者身份参加一次 Three Amigos 会议或冲刺规划会议
• 使用团队的 AI 助手： 确认团队使用哪些编码 Agent（Claude Code、Codex、Cursor、Gemini CLI 等）、它们的上下文存放在哪里（.agents/qa-project-context.md、CLAUDE.md、AGENTS.md）、哪些提示词/技能符合团队惯例，以及团队明确不会委派给 AI 的任务。将一份简短的“我们使用的 AI 助手、它们擅长什么、绝不能让它们做什么”文档作为第 4 天的交付成果。如果团队通过 Agent 自动化 Playwright，请注意，Agent 驱动的 Playwright 现在有自己的 @playwright/cli（守护进程架构、playwright-cli 命令、节省令牌）——它不同于框架演练文档中介绍的 npx playwright test 运行器。

第 5 天：完成第一个小目标

• 以调试/有头模式运行单个测试，并理解它的作用
• 修改现有测试中的一个断言，确认测试会按预期失败，然后还原
• 阅读 3 个现有测试，并标注每个部分的作用（设置、操作、断言）

第 2 周：首次实战测试

• 找出一个简单、低风险的测试用例（页面加载、元素可见性、基本导航）
• 使用现有页面对象和 fixture 编写测试（与团队成员结对）
• 在本地运行测试，确保稳定通过（连续运行 3 次）
• 提交 PR，接收反馈并迭代
• 测试在 CI 中通过
• 合并首个测试

第 3 周：参与冲刺

• 在指导下接手一个冲刺故事的 QA 工作
• 编写测试，覆盖该故事的验收标准
• 找出至少一个验收标准未涵盖的边缘情况
• 积极参与 Three Amigos 或故事细化（提出问题）
• 使用 shift-left-testing 中的 PR 审查清单，审查一个现有 PR 的测试质量

第 4 周：独立里程碑

• 不结对，独立编写并合并一个多步骤 E2E 测试
• 参与缺陷分类，并清楚说明测试覆盖缺口
• 将新的经验教训贡献到 .agents/qa-project-context.md
• 在冲刺评审或团队站会上汇报测试结果和发现
• 自我评估：哪些测试模式已熟练掌握？哪些还需要更多练习？

---

测试架构审计

加入现有项目时，应在编写新测试前评估测试套件的健康状况。这项审计需要 2-4 小时，可清晰了解当前状况。

根据 team_maturity 确定审计范围（取自 .agents/qa-project-context.md）——采用一刀切的审计方式会浪费初创团队的时间，也无法充分满足成熟团队的需求：

• startup — 跳过完整审计。确认有一条路径已覆盖，且一个框架能够运行；把节省下来的时间用于合并首个测试。
• growing — 对五个维度各审计一次，以建立基线；暂缓定期审查。
• established — 完成五个维度的全面审计，并按计划定期进行质量审查（例如每月一次），持续跟踪审计结果文档。

评估内容

评估以下五个维度，每个维度都附有一份可填写的工作表：

• 覆盖率与分布 — 各层的测试数量、测试金字塔形态、代码覆盖率及其趋势。
• 可靠性 — 不稳定测试比例、最不稳定的测试、隔离测试的数量和隔离时长。
• CI 健康状况 — 完整测试套件和各阶段的耗时、并行度、通过率、重试率。
• 技术债务 — 跳过的测试、waitForTimeout/force: true 的使用、硬编码数据、没有断言的测试、已弃用的 API、过时的 AI 生成测试、过时的功能标志。
• 约定 — 页面对象、fixture、工厂、命名、共享工具、标签。

请参阅 references/audit-worksheets.md，其中提供了涵盖全部五个维度的复制并填写式工作表。

审计输出

撰写一份简短文档（1-2 页）总结发现，并按以下类别归纳：

• 优势： 现有测试套件做得好的方面（应予以保留并借鉴）
• 缺口： 缺少测试覆盖的领域、测试不足的关键路径
• 风险： 不稳定的测试、过时的隔离项、覆盖率下降
• 快速见效项： 可在 1-2 个冲刺内完成的改进（修复不稳定测试、补充缺失的正向路径覆盖）
• 战略性工作： 需要持续投入的改进（重构测试架构、增加集成测试层）

---

框架指南模板

为你的项目创建此文档。它是所有编写测试人员的主要参考资料。文档分为六个部分：

1. 架构概览 — 框架、语言、配置位置和带注释的目录树。
2. 如何运行测试 — 全部运行命令（所有测试、单个文件、grep、带浏览器界面、调试、UI 模式、按浏览器运行、报告）。
3. 如何编写新测试（分步指南） — 六步流程：定位、复用、编写、运行、PR，以及 Arrange-Act-Assert 测试模板。
4. 如何调试失败 — 本地与 CI 的故障排查指南，以及常见失败模式解读。
5. 常见模式和约定 — 项目特定示例，包括身份验证 fixture、数据工厂、断言具体程度和选择器优先级。
6. 在哪里寻求帮助 — 针对模式、失败、产品行为和文档问题的路由表。

完整模板（包含所有代码块、目录树和可复制并调整的命令列表）请参阅 references/framework-walkthrough.md。

---

代码库导航指南

安排一次 60-90 分钟的介绍，带新人了解以下内容。

测试目录结构导览

带新人查看实际目录树，并说明：

• 为什么测试按功能而非类型组织
• 各产品领域的页面对象在哪里
• 共享实用工具在哪里，以及它们的作用
• 测试数据和 fixture 的定义位置
• CI 配置所在位置

共享实用工具清单

实用工具	位置	用途	示例
身份验证 fixture	fixtures/auth.fixture.ts	提供已通过身份验证的会话	{ adminPage, userPage }
数据工厂	helpers/factories.ts	通过 API 创建测试数据	createTestUser({ role: 'editor' })
API 客户端	helpers/api-client.ts	用于准备/清理的直接 API 调用	apiClient.delete('/users/' + id)
无障碍辅助工具	helpers/a11y.ts	axe-core 封装	checkAccessibility(page, testInfo)
断言	helpers/assertions.ts	自定义匹配器	toHaveToast('Saved')

页面对象导览

展示现有页面对象并说明：

• 基础页面类及其约定（抽象的 path、waitForReady）
• 组件对象如何与页面对象组合
• 命名约定（文件名与路由一致：/checkout 对应 checkout.page.ts）
• 如何添加新页面对象（复制并修改最简单的现有页面对象）

CI 流水线导览

打开 CI 配置并逐项说明：

• 流水线由什么触发（推送、PR、定时任务）
• 运行哪些阶段，以及执行顺序
• 测试产物的存放位置（报告、追踪记录、屏幕截图）
• 如何在 CI 中查找并解读失败的测试
• 如何重新运行失败的作业

---

指导模式

搭档完成前 3 个测试

经验丰富的团队成员与新人一起完成前 3 个测试：

1. 测试 1：领航员/驾驶员。 经验丰富的成员讲解方法并做出关键决策。新人负责输入代码，并在每一步询问“为什么？”。目标：了解工作流程。
2. 测试 2：共同驾驶。 双方平等参与。新人做出更多决策，经验丰富的成员补充遗漏。目标：建立信心。
3. 测试 3：观察员。 新人全程主导。经验丰富的成员观察，只有在被询问或方法可能导致问题时才提供反馈。目标：独立完成。

前 2 周评审所有 PR

前两周，新人的每个 PR 都应获得全面且有帮助的评审。不要只回复“LGTM”——应针对以下方面提供具体反馈：

• 模式遵循情况（是否正确使用页面对象？）
• 选择器策略（是否使用稳定的定位器？）
• 断言质量（断言是否足够具体？）
• 测试隔离（是否存在共享状态风险？）
• 命名（测试名称是否描述了行为？）

两周后，恢复标准评审深度。

测试伙伴制度

为新团队成员指定一位测试伙伴，让他们有问题时可以随时开口询问。测试伙伴：

• 在第一周每天主动联系，询问“你有什么地方卡住了吗？”
• 无需预约即可回答临时问题
• 通过解释“为什么”来审查所有 PR
• 向新人介绍团队规范和不成文的规则

逐步增加职责

Week 1-2:  Write tests for existing, well-understood features (smoke, basic flows)
Week 3-4:  Write tests for current sprint stories (with pairing available)
Week 5-6:  Write tests independently, review others' PRs
Week 7-8:  Contribute to test architecture (new fixtures, utilities, page objects)
Month 3+:  Lead test planning for a feature area, mentor the next new person

---

反模式

放任新人自生自灭

给新人仓库访问权限，指给他们 README，然后期待他们自己摸索。这会导致数周时间白白浪费，新人通过反复试错养成坏习惯，还可能早早离职。结构化入职培训配合结对协作，在第一个冲刺周期内就能收回成本。

只做教程式入职培训

花两周时间学习框架教程和练习小项目，之后才接触真实代码库。教程能教语法，却教不了项目惯例、领域知识或团队工作流。尽量缩短教程时间（最多 1-2 小时），尽快转向真实测试。

没有文档，全靠口耳相传

如果每个问题的答案都是“去问 Sarah”，团队就只有一个关键成员，入职培训也完全取决于 Sarah 是否有空。在 .agents/qa-project-context.md 和框架指南中记录规范。如果某件事重要到值得口头解释，那就值得写下来。

完美主义导致停滞

期待新人的第一个测试就完美无缺。第一个测试只要可用并遵循基本规范即可。每次 PR 审查都会提升代码质量。因为风格上的小问题或高级模式而阻止第一个 PR，会打击信心，也会延迟新人取得首次成果。

忽视入职体验

不向接受入职培训的人征求反馈。他们亲身经历了整个过程，最清楚哪些内容缺失、令人困惑或浪费时间。在第 2 周和第 4 周结束时，各安排一次 15 分钟的反馈交流。根据他们的反馈改进流程，为下一位新人做好准备。

不求甚解地复制粘贴

新人复制一个现有测试，替换定位器和 URL，就认为完成了。测试虽然能运行，但他们并不理解背后的原因。结对协作和代码审查应聚焦于每种模式背后的“为什么”。如果有人无法解释某个 fixture 为什么要这样组织，那么在上下文不同时，他们就会误用它。

---

验证

在宣布入职培训完成前，确认交付成果经得起检验。先做成本最低的检查。

1. 第一个合并的测试稳定可靠，而非碰巧通过。 多次运行以排除不稳定因素，然后确认 CI 通过。
   • npx playwright test <new-test> --repeat-each=3 退出码为 0（在本地连续通过 3 次）
   • PR 的 CI 检查中，同一测试通过
2. 审计文档内容完整，而非只有空架子。 打开发现文档，确认已填写全部五个维度（覆盖率/分布、可靠性、CI 健康状况、技术债务、规范），并将发现归类为优势 / 差距 / 风险 / 快速见效项 / 战略工作。如果初创团队决定不做审计（参见 team_maturity），则应记录该决定。
3. 上下文文件格式正确且内容完整。 .agents/qa-project-context.md 已创建，并包含框架、关键路径、团队结构和风险领域，而非只有高层级的占位内容。

完成标准

• 至少有一个可运行的测试已合并到仓库中，在 CI 中通过，并且在本地连续运行 3 次均稳定（--repeat-each=3 以 0 退出）——这证明本地和流水线设置端到端可用。
• 测试架构审计文档已创建，五个维度均已填写，且发现的问题已分类（优势、差距、风险、快速见效项、战略性工作）；或者，对于处于启动阶段的 team_maturity，文档记录了明确的决定：暂不涵盖该项。
• 第一周第 1/2 天的每项设置任务都记录了负责人和目标日期；阻塞项已登记为可跟踪的工单。
• .agents/qa-project-context.md 已创建并填写框架、关键路径、团队结构和风险领域（不是占位文件）。
• 已选定测试框架并记录选择理由（评估过其他方案，并写明决定）；或者在沿用现有框架时标记为 N/A。

参考文件（位于 references/ 中）

• framework-walkthrough.md — 完整的框架指南模板：架构概览、运行命令、新增测试的分步说明和模板、调试手册、约定以及求助指引。
• audit-worksheets.md — 可复制并填写的测试架构审计工作表（覆盖率、可靠性、CI 健康状况、技术债务、约定）。

相关技能

• qa-project-context -- 项目上下文文件是入职引导的基础。若文件不存在，请创建；并在入职引导过程中更新。
• playwright-automation -- 针对 Playwright 项目的框架专属模式、页面对象模型、fixture 和 CI 集成。
• shift-left-testing -- 帮助新人了解团队的左移实践：Three Amigos、PR 评审、完成定义。
• test-strategy -- 了解整体测试策略，有助于新人理解测试为何以这种方式组织。
• test-reliability -- 了解不稳定测试模式和隔离管理，有助于新人避免创建不可靠的测试。