Day 29 - Framework Design and Team Standards

今日目标

从“会写脚本”升级到“能维护框架”。
建立团队级规范。

学习时间安排（60–120 分钟）

时间	模块	做什么
0-20 分钟	核心概念与词汇	读概念表，重点理解规范要约束的行为。
20-45 分钟	学习材料阅读	读最佳实践文档，对照自己项目的目录和规范。
45-75 分钟	实操练习	写《Playwright 自动化测试规范 v1.0》。
75-105 分钟	示例代码改写	按规范整改自己项目里的不合规代码。
105-120 分钟	复盘与作业	完成 PR review checklist，完成今日问题。

核心概念与词汇

English	中文	场景用法
framework	测试框架	Use it when you describe the structure, conventions, and utilities around raw tests.
naming convention	命名规范	Use it when you standardize file, test, and variable names.
locator convention	定位器规范	Use it when you standardize which locator APIs the team may use.
code review checklist	代码审查清单	Use it when PRs must pass a fixed set of test-quality checks.
flaky test policy	不稳定测试处理流程	Use it when the team decides to fix, quarantine, or delete flaky tests.
tag convention	标签规范	Use it when @smoke/@regression tags drive CI test selection.
CI run strategy	CI 运行策略	Use it when you document which tests run when.
failure triage flow	失败排查流程	Use it when failures route to owners with evidence attached.
maintainability	可维护性	Use it when you judge whether new teammates can change tests safely.
return on investment	自动化收益	Use it when you measure bugs caught and time saved against maintenance cost.

学习材料

必读：[Best practices](https://playwright.dev/docs/best-practices)
必读：[POM](https://playwright.dev/docs/pom) 和 [Fixtures](https://playwright.dev/docs/test-fixtures)（复习 Day 13/14）
选读：[Test annotations](https://playwright.dev/docs/test-annotations)（tag 规范的基础）

重点理解

推荐项目结构：

e2e/
  tests/
    smoke/
    regression/
    api/
  pages/
  fixtures/
  utils/
  test-data/
  config/
  reports/
  README.md

团队规范：

命名规范。
Locator 规范。
POM 规范。
测试数据规范。
Tag 规范。
CI 运行策略。
失败排查流程。
Code review checklist。
Flaky test 处理流程。

实操步骤

写一份《Playwright 自动化测试规范 v1.0》。

必须包含：

测试用例命名。
文件目录。
locator 优先级。
断言规则。
等待规则。
数据管理。
CI 策略。
review checklist。

示例代码

## Locator 规范（节选）

1. 优先级：getByRole > getByLabel > getByPlaceholder > getByText > getByTestId > CSS/XPath
2. 禁止超过 2 层的 CSS/XPath 选择器
3. 列表操作遵循「先容器、后 filter、再操作」
4. nth 仅允许在顺序是业务规则时使用，并注明理由

## 断言规范（节选）

1. 每条测试至少 1 个业务断言
2. 禁止手动 textContent 比较
3. 断言用户可见结果，不断言 class 名

常见坑

规范写了没人执行，review 也不看，文档成为摆设。
规范过细（规定到变量命名风格），新人遵守成本高，反而被绕过。
只约束怎么写，不约束“失败怎么办”，flaky 堆积无人处理。
框架过度设计：为了抽象而抽象，核心路径还没稳定就上微框架。
用“重构框架”代替“修复 flaky”，框架越来越复杂，测试还是红。

今日产出

一份团队规范文档。
一份 PR review checklist。

今日问题

自动化测试项目为什么需要规范？
什么样的测试代码最难维护？
Code review 应该重点看什么？
flaky test 应该删除、跳过还是修复？
如何衡量自动化测试带来的价值？

复盘要点

规范的目的是减少决策成本，不是展示写作能力：能执行的 5 条胜过纸面的 50 条。
review 是规范的执行器：checklist 里没有的项，规范就只是文档。
你维护的不是“测试代码”，而是团队对质量的共同理解。

AI 时代扩展：AI 辅助 Playwright 测试

新增概念

English	中文
standards enforcement	规范执行
automated code review	自动化代码审查
flaky quarantine	不稳定用例隔离

适用场景

让 AI 起草团队规范初稿，或按你的规范审查测试代码、给出不合规清单。也可以用 AI 把规范转成 CI 上的 lint 规则建议。

可复用表达 / 提示词

请根据以下要求起草《Playwright 自动化测试规范》：覆盖命名、locator、断言、等待、数据、CI 六个方面，每条规范附一个违规示例。
请按这份规范审查我的测试代码，输出不合规项清单，按严重程度排序。

追问加练

AI 起草的规范里，哪些条目无法自动化检查？
flaky 用例隔离（quarantine）的流程怎么设计？
规范由 AI 起草后，团队评审重点应该看什么？

今日作业

完成《Playwright 自动化测试规范 v1.0》全部 8 项内容。
完成 PR review checklist，至少 10 条。
用 AI 按规范审查你的项目，整改不合规项。

自检清单

我的规范文档覆盖 8 个必须项。
每条规范都有违规示例或反例。
我的 review checklist 可以在 PR 中直接使用。
我的项目代码符合自己写的规范。
明天最终项目时，我能把这些规范应用到 starter 项目。