pw-test-audit

审核最近的 Playwright 测试改动是否符合项目规则。你在一个全新的 Agent 会话中运行，请以独立、客观的视角进行审核。不要假设上一个 Agent 的选择是正确的。

即使有人要求自主处理，也绝不能跳过此技能中的 AskUserQuestion 步骤。

说明

1. 确认最近的改动

查找未提交的改动——这就是整个审核范围：

git status --short
git diff HEAD

如果 diff 为空（没有未提交的改动），请立即停止并告知用户：

未检测到未提交的改动——没有新的测试代码可供审核。此技能只审核最近新增的内容。如果你已提交改动，请将其重新呈现（例如 git reset --soft HEAD~1），然后重新运行此技能。

不要改为查看之前的提交，不要审核已提交的历史，也不要另选审核范围。干净地退出。

如果存在 diff，但其中不包含 Playwright 相关文件（即项目 E2E 测试目录下没有规范文件、页面对象、fixtures 或辅助文件），请告知用户 diff 中没有需要审核的 Playwright 改动，然后退出。

否则，审核范围仅限于你看到的 diff 片段——不要审核未改动的测试、未触及的页面对象或无关文件。

2. 了解项目背景

完整阅读项目的 Playwright 规则。查找项目文档中指定的规则位置（通常是 .claude/rules/，但也可能不同——请确认实际文件名）：

• Playwright 脚本编写规则——定位器、断言、等待、命名、代码风格、操作、表单交互
• Playwright 架构规则——POM 约定、fixtures、身份验证设置、目录结构

如果项目没有 Playwright 规则文件，请参考现有测试套件中可推断出的惯例（阅读 2–3 个有代表性的规范文件以及测试工具目录中的内容），并在报告中说明本次审核依据的是推断得出的惯例，而非有文档记录的规则。

判断受影响的测试是否使用 Page Object Model：

• 使用 POM——存在页面对象目录，且其中至少有一个页面类，并且有改动的规范文件导入了自定义测试 fixture（通常是 pom），而不是直接从 @playwright/test 导入 test
• 未使用 POM——使用原生 Playwright，仅使用 page fixture

这决定了适用哪些审核规则。未使用 POM 时，应完全跳过 POM 规则——这是预期且有效的配置。不要将未使用 POM 标记为违规。

3. 阅读改动涉及的应用源码

对于 diff 中的每个定位器或交互操作，阅读用于渲染相应元素的前端源码。项目可能使用任何框架（React、Vue、Angular、Svelte、纯 HTML 等），也可能采用任何目录结构——请找出 UI 组件所在的位置，然后阅读渲染测试所交互路由和组件的文件。

目标：根据实际渲染的 HTML 以及项目脚本编写规则中定义的定位器优先级，判断每个定位器是否正确、唯一且语义最明确。

4. 审核改动

根据以下清单逐行检查所有改动。对每个违规项标注 file:line。引用项目规则文件中的具体规则——不要自行编造规则。下方各类别是 Playwright 规则集中常见的通用模式；请将其对应到项目实际规则文件中的等效规则。如果项目规则与下方条目冲突，以项目规则为准。

定位器

• 遵循以下优先级：getByRole > getByLabel > getByText > getByPlaceholder > getByTestId > CSS（仅用于稳定的结构标签，绝不用于样式类）
• 不使用 CSS 类名选择器作为定位器
• 源代码中确实存在 data-testid；如果是新添加的，其值应遵循项目的命名约定（例如，若项目要求，则以元素名词结尾）
• 使用操作方法（click、fill、check、selectOption）的定位器必须且只匹配一个元素——通过阅读源代码进行验证
• 重复的 UI 模式（卡片、行、列表项）应限定在其容器内——不要使用 .first()，也不要使用可能产生误匹配的未限定操作定位器
• 跨页面导航时，从源页面捕获一个值（例如标题文本），并在目标页面断言该值，而不是只断言目标页面上存在任意同类型元素
• 只要足够，优先使用构造选项 name / hasText，而非 .filter()；.filter() 仅用于第二级筛选
• 定位器文本必须与源代码完全一致，包括测试视口下可见的响应式变体
• 语义范围限定：对特定区域所属值的断言应限定在该区域内，而不是在整个页面范围内断言

断言

• 优先使用定位器（自动重试）断言，而非通用的 expect(value).toBe(...) 模式
• 不使用 expect.soft(...)
• 负向断言前，应先等待 DOM 发生变更（响应、waitFor({ state: 'hidden' }) 等），再断言目标不存在
• 对唯一定位器优先使用 toHaveText / toContainText，而非 getByText(...).toBeVisible()

等待

• 不使用 page.waitForTimeout(...)
• 操作或自动等待的定位器断言前，不进行冗余的 waitFor() 或 waitForURL
• 显式等待仅用于非自动等待的方法（all、count、textContent、inputValue、allTextContents）之前
• 初稿中不设置自定义超时——断言中不使用 { timeout: ... }，也不使用 test.setTimeout(...)。自定义超时仅允许作为调试修复手段，不得预先设置

测试结构

• 测试名称描述用户行为，而非实现细节
• 测试入口遵循项目约定（例如，始终从首页开始，或遵循其他有文档说明的模式）
• 每个测试验证一个逻辑上的用户流程
• test.describe 的位置和 beforeEach 的用法应符合文件现有约定

代码风格

• 每行一条语句——不使用纵向堆叠的定位器链、换行包裹的 expect(...) 或测试签名
• 仅在符合项目规则时使用定位器常量（通常是重复使用 3 次以上，或不透明且使用 2 次以上）；否则直接内联
• 不使用仅用于构建下一个常量的中间常量
• 不要使用变体名称（*AfterUpdate、*AfterRevert）重复声明同一定位器——定位器是惰性的，会重新解析
• allTextContents / textContent 的结果变量应以 Values / Texts 结尾——Links、Headings 等元素类型名称保留给存放定位器的变量
• 对同一元素重复点击时，使用 click({ clickCount: N })，而不是写成多行

POM 规则（仅在使用 POM 时适用）

• 构造函数仅接受 Page，不包含定位器属性，也不在类上预先构造定位器
• 所有定位器均在使用它们的方法中内联声明
• 不编写只执行单个简单操作的方法；方法应涵盖有意义的多步骤用户任务
• 方法不得跨越两个页面；每次导航都应在不同页面对象的方法边界处进行
• 操作方法不负责断言测试目标；目标断言应放在专用的 expect* 前缀验证方法中，并通过参数化实现复用
• 操作方法在必要时包含轻量级稳定性断言（在非自动等待代码前设置开始守卫；导航后使用 expect(page).toHaveURL(...) 确认结束状态，或在页面内变更后使用 toBeVisible / toHaveText）
• 方法名称：使用 camelCase、描述性动词短语，不使用缩写或首字母缩略词；验证方法以 expect 开头
• 不要仅因硬编码值不同而创建重复方法，应将现有方法参数化
• 任何新增页面类都必须在项目的 PageManager（或等效类）中注册，使用急切构造和 camelCase 属性名称
• Spec 应从项目的自定义 fixtures 模块导入 test 和 expect，而非直接从 @playwright/test 导入
• 优先复用：对于相近匹配的现有方法，应参数化而不是重复创建；新增方法前，应检查相关类是否已有对应功能

架构

• Spec 文件应放在与 actor / role / scenario 对应的正确目录中，并遵循项目现有的测试布局
• 除非变更有意针对认证设置文件，否则不得改动这些文件
• 无状态工具应放在项目的 helpers 目录中，不应内联到页面方法或 spec 中

5. 编写审计报告

使用 Markdown 表格直接向用户输出一份结构化报告，每种严重程度使用一个表格。所有表格中的问题都应连续编号（1、2、3……），以便用户在选择要处理的问题时通过 ID 引用。

## Audit summary
<one-sentence verdict: passes cleanly / minor issues / multiple violations>

## Findings — Must-fix

| #  | Location              | Issue                                    | Fix                                          |
|----|-----------------------|------------------------------------------|----------------------------------------------|
| 1  | `<file>:<line>`       | <rule violated + one-line evidence>      | <one-line suggested fix>                     |

## Findings — Should-fix

| #  | Location              | Issue                                    | Fix                                          |
|----|-----------------------|------------------------------------------|----------------------------------------------|
| 2  | `<file>:<line>`       | <rule violated + one-line evidence>      | <one-line suggested fix>                     |

## Suggestions

| #  | Location              | Improvement                              | Suggested change                             |
|----|-----------------------|------------------------------------------|----------------------------------------------|
| 3  | `<file>:<line>`       | <stylistic / readability nudge>          | <one-line suggested change>                  |

## What looks good
- <brief callouts of well-applied conventions so positive choices are reinforced>

格式规则：

• 不显示没有条目的章节。
• 每个单元格的内容须为单行。如果规则引用和证据都不可或缺，应在 Issue 列中合并为 <规则>：<证据>，不要换到第二行。
• 单元格中的代码标识符、文件路径和选择器使用反引号括起（例如 `.ion-trash-a`、`getByTestId`、`article-page.ts:14`）。
• Location 列中省略目录前缀，以保持表格简洁；只显示文件名和行号（例如 article-page.ts:14，而非完整路径）。读者可根据上下文判断；完整路径仅在周边说明中出现。
• 在 Issue 列中引用项目规则文件中的具体规则。
• “What looks good” 部分保留为项目符号列表——这是表扬内容，不是可执行事项。

严重程度指南：

• Must-fix — 直接违反已记录的规则
• Should-fix — 规则中指出应优先采用的模式，但当前代码仍可运行
• Suggestions — 规则未明确规定的风格或可读性建议

6. 提供下一步操作

使用 AskUserQuestion：

• 问题："审查已完成。你想怎么做？"
• 标题："下一步"
• 选项 1：标签 "应用必须修复项"，描述 "仅编辑测试以解决必须修复的问题"
• 选项 2：标签 "全部应用"，描述 "编辑测试以解决必须修复和建议修复的问题"
• 选项 3：标签 "讨论"，描述 "在进行任何更改前，先讨论具体问题"

用户也可以选择 "其他"，按编号指定自定义范围（例如 "应用 1、3、5"），因为表格为每个问题都分配了固定 ID。请准确遵循这些编号。

如果用户选择 应用必须修复项 或 全部应用（或指定具体问题编号）：编辑 spec（如果使用 POM，也编辑页面对象）以解决选定的问题，然后仅重新运行受影响的测试：

npx playwright test -g "<exact test title>" --retries 0

如果修复后测试失败，请使用由追踪记录驱动的循环进行调试（通过 npx playwright trace open 打开追踪记录，检查操作和快照，应用修复，然后重新运行），直到测试通过。

如果用户选择 讨论：回答他们的问题，并且只有在用户明确要求时才编辑代码。

操作原则

• 以全新视角审查 —— 你不是编写这段代码的 Agent。根据应用源代码重新推导每个定位器。质疑每项选择。之前的 Agent 有什么意图并不重要；重要的只有规则和源代码。
• 仅审查近期未提交的更改 —— 未提交的差异就是全部审查范围。绝不回退到先前的提交，绝不审查未改动的文件，也绝不建议重写差异范围之外的测试。
• 引用规则，而非观点 —— 每个必须修复的问题都必须对应项目规则文件中记录的一条规则。仅基于观点的反馈应归入建议。
• 根据源代码验证定位器 —— 在阅读渲染该定位器的组件之前，不要判定定位器有误。看似不可靠的定位器可能是该 DOM 唯一可靠的选择。
• 不要猜测测试意图 —— 如果某个问题取决于测试本应实现的目标，应先提问，不要自行假设。
• 仅在使用 POM 时审查 POM —— 如果未使用 POM，则完全跳过 POM 部分。直接编写 Playwright spec 是有效的项目设置，并不构成违规。
• 不限定框架 —— 项目可以使用任何前端框架或目录布局。根据项目文件了解其约定；不要假设特定技术栈。