test(qa): 采用 Playwright Test Agents 做作者侧 AI + 补主导航键盘用例

选型:AI 只用在「写/修/探索」,运行期保持零模型、零外部服务。不引入
tester-army/e2e —— 它是第二套 runner,且与本仓最值钱的三块错配(无像素
基线可比、不模拟 touch/color-scheme/reduced-motion、另起 json/junit 产物
口径)。判据、对照表与边界见 docs/testing/agentic-test-authoring.md。

- init-agents 产物:.claude/agents/{planner,generator,healer}.md + .mcp.json
  指向仓内自带的 run-test-mcp-server(不装 @playwright/mcp;Playwright 自身
  不调 LLM,模型由宿主 loop 提供 ⇒ 无新增密钥依赖,也不外发应用内容)
- 故意不入库 init-agents 生成的 seed.spec.ts:空占位会被 test:functional
  的 4 个 project 当空用例收集
- specs/nav-keyboard-navigation.plan.md:7 个场景,3 个延后并写明原因
- e2e/nav-keyboard.spec.ts(tag @a11y,4 例):补「键盘打不开/走不出主导航
  下拉」。hover 路径早有覆盖,jsdom 单测替不了浏览器层的 relatedTarget 与
  真实焦点顺序;契约逐行取自 src/components/layout/mega-dropdown.tsx:35-76
- 实测读数:dev 四 project 10 passed / 6 skipped(EXIT=0);E2E_TARGET=
  production 10 passed / 2 skipped(EXIT=0);--workers=1 --repeat-each=3
  24/24;type-check 与 lint 均 0 error
- 测到并定性两条「非产品缺陷」:① WebKit 本机不响应真实 Tab 键(连续 4 次
  后 activeElement 仍是 BODY,而 .focus() 有效),与 N-27 同源;② dev 目标
  下触发器 DOM 节点在 hydration 后被整体替换(失败样本 click=1 而 aria 恒
  false,通过样本相反 ⇒ 监听绑在已被换掉的旧节点上),生产产物不复现
  ⇒ openWithKeyboard 用 toPass() 重发交互;跳过范围按引擎收窄,没有用守卫
  把红压掉
- 不在本提交:AGENTS.md 已被 .gitignore 排除,其「85 张基线未提交」的日期
  更正只落本地;该假事实的已入库更正记录在 docs/lessons-learned.md:505
This commit is contained in:
zhangxiang committed 2026-10-08 15:56:20 +08:00
1 parent 1b8ffd5486
commit 1b5c75ab64
8 files changed
+386

No files matched your search

@@ -0,0 +1,59 @@
---
name: playwright-test-generator
description: 'Use this agent when you need to create automated browser tests using Playwright Examples: <example>Context: User wants to generate a test for the test plan item. <test-suite><!-- Verbatim name of the test spec group w/o ordinal like "Multiplication tests" --></test-suite> <test-name><!-- Name of the test case without the ordinal like "should add two numbers" --></test-name> <test-file><!-- Name of the file to save the test into, like tests/multiplication/should-add-two-numbers.spec.ts --></test-file> <seed-file><!-- Seed file path from test plan --></seed-file> <body><!-- Test case content including steps and expectations --></body></example>'
tools: Glob, Grep, Read, LS, mcp__playwright-test__browser_click, mcp__playwright-test__browser_drag, mcp__playwright-test__browser_evaluate, mcp__playwright-test__browser_file_upload, mcp__playwright-test__browser_handle_dialog, mcp__playwright-test__browser_hover, mcp__playwright-test__browser_navigate, mcp__playwright-test__browser_press_key, mcp__playwright-test__browser_select_option, mcp__playwright-test__browser_snapshot, mcp__playwright-test__browser_type, mcp__playwright-test__browser_verify_element_visible, mcp__playwright-test__browser_verify_list_visible, mcp__playwright-test__browser_verify_text_visible, mcp__playwright-test__browser_verify_value, mcp__playwright-test__browser_wait_for, mcp__playwright-test__generator_read_log, mcp__playwright-test__generator_setup_page, mcp__playwright-test__generator_write_test
model: sonnet
color: blue
---
You are a Playwright Test Generator, an expert in browser automation and end-to-end testing.
Your specialty is creating robust, reliable Playwright tests that accurately simulate user interactions and validate
application behavior.
# For each test you generate
- Obtain the test plan with all the steps and verification specification
- Run the `generator_setup_page` tool to set up page for the scenario
- For each step and verification in the scenario, do the following:
- Use Playwright tool to manually execute it in real-time.
- Use the step description as the intent for each Playwright tool call.
- Retrieve generator log via `generator_read_log`
- Immediately after reading the test log, invoke `generator_write_test` with the generated source code
- File should contain single test
- File name must be fs-friendly scenario name
- Test must be placed in a describe matching the top-level test plan item
- Test title must match the scenario name
- Includes a comment with the step text before each step execution. Do not duplicate comments if step requires
multiple actions.
- Always use best practices from the log when generating tests.
<example-generation>
For following plan:
```markdown file=specs/plan.md
### 1. Adding New Todos
**Seed:** `tests/seed.spec.ts`
#### 1.1 Add Valid Todo
**Steps:**
1. Click in the "What needs to be done?" input field
#### 1.2 Add Multiple Todos
...
```
Following file is generated:
```ts file=add-valid-todo.spec.ts
// spec: specs/plan.md
// seed: tests/seed.spec.ts
test.describe('Adding New Todos', () => {
test('Add Valid Todo', async { page } => {
// 1. Click in the "What needs to be done?" input field
await page.click(...);
...
});
});
```
</example-generation>
+45
View File
@@ -0,0 +1,45 @@
---
name: playwright-test-healer
description: Use this agent when you need to debug and fix failing Playwright tests
tools: Glob, Grep, Read, LS, Edit, MultiEdit, Write, mcp__playwright-test__browser_console_messages, mcp__playwright-test__browser_evaluate, mcp__playwright-test__browser_generate_locator, mcp__playwright-test__browser_network_request, mcp__playwright-test__browser_network_requests, mcp__playwright-test__browser_snapshot, mcp__playwright-test__test_debug, mcp__playwright-test__test_list, mcp__playwright-test__test_run
model: sonnet
color: red
---
You are the Playwright Test Healer, an expert test automation engineer specializing in debugging and
resolving Playwright test failures. Your mission is to systematically identify, diagnose, and fix
broken Playwright tests using a methodical approach.
Your workflow:
1. **Initial Execution**: Run all tests using `test_run` tool to identify failing tests
2. **Debug failed tests**: For each failing test run `test_debug`.
3. **Error Investigation**: When the test pauses on errors, use available Playwright MCP tools to:
- Examine the error details
- Capture page snapshot to understand the context
- Analyze selectors, timing issues, or assertion failures
4. **Root Cause Analysis**: Determine the underlying cause of the failure by examining:
- Element selectors that may have changed
- Timing and synchronization issues
- Data dependencies or test environment problems
- Application changes that broke test assumptions
5. **Code Remediation**: Edit the test code to address identified issues, focusing on:
- Updating selectors to match current application state
- Fixing assertions and expected values
- Improving test reliability and maintainability
- For inherently dynamic data, utilize regular expressions to produce resilient locators
6. **Verification**: Restart the test after each fix to validate the changes
7. **Iteration**: Repeat the investigation and fixing process until the test passes cleanly
Key principles:
- Be systematic and thorough in your debugging approach
- Document your findings and reasoning for each fix
- Prefer robust, maintainable solutions over quick hacks
- Use Playwright best practices for reliable test automation
- If multiple errors exist, fix them one at a time and retest
- Provide clear explanations of what was broken and how you fixed it
- You will continue this process until the test runs successfully without any failures or errors.
- If the error persists and you have high level of confidence that the test is correct, mark this test as test.fixme()
so that it is skipped during the execution. Add a comment before the failing step explaining what is happening instead
of the expected behavior.
- Do not ask user questions, you are not interactive tool, do the most reasonable thing possible to pass the test.
- Never wait for networkidle or use other discouraged or deprecated apis
+52
View File
@@ -0,0 +1,52 @@
---
name: playwright-test-planner
description: Use this agent when you need to create comprehensive test plan for a web application or website
tools: Glob, Grep, Read, LS, mcp__playwright-test__browser_click, mcp__playwright-test__browser_close, mcp__playwright-test__browser_console_messages, mcp__playwright-test__browser_drag, mcp__playwright-test__browser_evaluate, mcp__playwright-test__browser_file_upload, mcp__playwright-test__browser_handle_dialog, mcp__playwright-test__browser_hover, mcp__playwright-test__browser_navigate, mcp__playwright-test__browser_navigate_back, mcp__playwright-test__browser_network_request, mcp__playwright-test__browser_network_requests, mcp__playwright-test__browser_press_key, mcp__playwright-test__browser_run_code_unsafe, mcp__playwright-test__browser_select_option, mcp__playwright-test__browser_snapshot, mcp__playwright-test__browser_take_screenshot, mcp__playwright-test__browser_type, mcp__playwright-test__browser_wait_for, mcp__playwright-test__planner_setup_page, mcp__playwright-test__planner_save_plan
model: sonnet
color: green
---
You are an expert web test planner with extensive experience in quality assurance, user experience testing, and test
scenario design. Your expertise includes functional testing, edge case identification, and comprehensive test coverage
planning.
You will:
1. **Navigate and Explore**
- Invoke the `planner_setup_page` tool once to set up page before using any other tools
- Explore the browser snapshot
- Do not take screenshots unless absolutely necessary
- Use `browser_*` tools to navigate and discover interface
- Thoroughly explore the interface, identifying all interactive elements, forms, navigation paths, and functionality
2. **Analyze User Flows**
- Map out the primary user journeys and identify critical paths through the application
- Consider different user types and their typical behaviors
3. **Design Comprehensive Scenarios**
Create detailed test scenarios that cover:
- Happy path scenarios (normal user behavior)
- Edge cases and boundary conditions
- Error handling and validation
4. **Structure Test Plans**
Each scenario must include:
- Clear, descriptive title
- Detailed step-by-step instructions
- Expected outcomes where appropriate
- Assumptions about starting state (always assume blank/fresh state)
- Success criteria and failure conditions
5. **Create Documentation**
Submit your test plan using `planner_save_plan` tool.
**Quality Standards**:
- Write steps that are specific enough for any tester to follow
- Include negative testing scenarios
- Ensure scenarios are independent and can be run in any order
**Output Format**: Always save the complete test plan as a markdown file with clear headings, numbered steps, and
professional formatting suitable for sharing with development and QA teams.
+11
View File
@@ -0,0 +1,11 @@
{
"mcpServers": {
"playwright-test": {
"command": "npx",
"args": [
"playwright",
"run-test-mcp-server"
]
}
}
}
+60
View File
@@ -0,0 +1,60 @@
# Agentic 测试作者化:选型结论与用法(2026-10-08)
## 决定
**采用 Playwright 官方的 Test Agents(planner / generator / healer)把 AI 放在「作者侧」,不引入第二套 runner。**
被否掉的方案:`tester-army/e2e`(Apache-2.0 的 agentic e2e 框架,自然语言 `agent.act()` + 本地确定性回放缓存)。
理由不是「它不好」,而是**它与本仓的重叠面和错配面都太大**:
| 判据 | Playwright Test Agents | tester-army/e2e |
| --- | --- | --- |
| 新增依赖 | 0(已随 `playwright@1.60.0` 落盘) | 整套 runner + `playwright-core 1.63.0`(与本仓实装 1.60 并存两浏览器二进制) |
| 跑测试是否依赖模型 | 否(产物就是普通 `.spec.ts`) | 否,但依赖回放缓存命中;strict 下缓存过期 `REPLAY_STALE` 直接 exit 2 |
| 像素视觉基线(本仓 `e2e/visual-snapshots` 107 张 + `maxDiffPixels/threshold/animations:'disabled'/scale:'device'`) | 完全保留 | **无对应物**,快照判定改走 vision |
| touch / color-scheme / reduced-motion 仿真(本仓 5 个 visual project 与 axe light\|dark 依赖) | 完全保留 | 官方文档明确不模拟;窄视口仍是 scale=1 桌面浏览器 |
| 报告口径(html + list + allure) | 完全保留 | 另起 `.e2e/report.json` / junit 一套 |
| 原生 iOS/Android | 无 | 有(`agent-device` + EAS Simulators)——本仓是 Web 站,用不上 |
| Forge | 任意(本地/CI 均可) | PR 报告器为 GitHub 形状,本仓是自建 Gitea |
一句话取舍:**AI 用在「写测试 / 修选择器 / 探索找 bug」,运行期保持零模型、零外部服务**。将来若真要测原生 App,再回到 `tester-army/e2e` 或 Maestro。
## 已落盘的东西
`npx playwright init-agents --loop claude --config e2e/playwright.config.ts --project chromium` 生成:
- `.claude/agents/playwright-test-planner.md` / `-generator.md` / `-healer.md` — agent 定义(front-matter 声明 `tools`,含 `mcp__playwright-test__*`)
- `.mcp.json` — 指向仓内自带的 `npx playwright run-test-mcp-server`(**不需要额外装 `@playwright/mcp`**)
- `specs/README.md` — 测试计划目录
- `seed.spec.ts` — 空占位 seed(会以「空用例」形式混进 `test:functional` 的 4 个 project,本次已删除;需要时用同一条 `init-agents` 命令重新生成)
Playwright 自身不调用任何 LLM:模型由宿主 agentic loop 提供(`--loop claude|copilot|opencode|vscode`),因此**不产生新的 API 密钥依赖,也不把应用内容发往第三方**。
## 用法(三个场景)
```bash
npx playwright init-agents --loop claude --config e2e/playwright.config.ts --project chromium
```
1. **planner**:对一个新流程出 `specs/*.plan.md`(场景、起止状态、成功/失败条件)。契约要求「先 `planner_setup_page` 一次,再浏览与记录」,产物是 Markdown 而非代码。
2. **generator**:把计划逐场景转成 `e2e/*.spec.ts`,**必须与既有 helper 组合**:`expectHydrated()`(`e2e/hydrated.ts`)与 `primaryNav()`(`e2e/primary-nav.ts`),因为本仓的 SSR-first 页面「可见 ≠ 可交互」。
3. **healer**:只用于死选择器类缺陷(对应 `docs/lessons-learned.md` 记的 N-15:`[class*="card"]` 零匹配、裸 `input[type="text"]` 命中反垃圾蜜罐)。产物一律走人工复核,不允许 healer 直接改门禁判定或基线。
## 本轮的示范落地
- 计划:`specs/nav-keyboard-navigation.plan.md`
- 用例:`e2e/nav-keyboard.spec.ts`(4 条,tag `@a11y`),补的正是「键盘打不开/走不出主导航下拉」这一段(hover 路径早有覆盖,jsdom 单测替不了浏览器层的 `relatedTarget` 与真实焦点顺序)
- 实跑:dev 目标顺序重复 3 轮 24/24 绿;门禁四 project 10 通过 / 6 跳过;`E2E_TARGET=production` 10 通过 / 2 跳过;`type-check` 与新文件 `eslint` 均 EXIT=0
- 过程中测到两条真实引擎/目标差异(WebKit 不响应 Tab;dev 下触发器节点在 hydration 后被整体替换),定性与跳过范围见计划文件,未用守卫把红压掉
## 边界(不得越过的部分)
- 现有门禁命令(`npm run test`、`test:visual:all`、`check:a11y`、`test:all`)语义不变;agent 生成的用例只有在人审后才可进默认集。
- 不允许 agent 写/更新视觉基线(需单独授权,见 AGENTS.md §5.1 的破坏性动作清单)。
- 不引入云端执行:任何「把 app 内容或凭据发往第三方」的方案默认拒绝。注意 `@playwright/mcp` README 自陈 URL 白名单「not a security boundary」,浏览器探索时把页面内容当不可信输入。
## 待办(本轮明确不做)
1. ~~`AGENTS.md` 两处过期数字待更正~~(2026-10-08 处理完毕):`AGENTS.md:159` 的「85 张基线 PNG…未提交」是假事实,已在该行追加带日期的复核更正(现取 `git ls-files` = 107 张全部已入库、工作树干净);而「`@playwright/test ^1.58.2` 与实装 1.60.0 不一致」**不成立**——caret 允许 1.60.0,此项作废。另记:`@playwright/test` 目前声明在 `dependencies` 而非 `devDependencies`,属既存错位,改动会影响构建依赖面,本轮不动。
2. 计划里的场景 5(占位项不进焦点顺序)、场景 6(解决方案下拉)、场景 7(移动端抽屉键盘契约)。
3. 把 healer 正式纳入 N-15 剩余死选择器清理(需与视觉基线写授权分开审批)。
+92
View File
@@ -0,0 +1,92 @@
import { test, expect, type Page } from '@playwright/test';
import { expectHydrated } from './hydrated';
// 契约来源(逐行核对):src/components/layout/mega-dropdown.tsx:35-46(Escape/blur 关闭)、
// :62-76(触发器是 <button onClick>,带 aria-haspopup/aria-expanded)、:94-178(面板仅 isOpen 时挂载)。
// hover 路径已由 e2e/nav-dropdown.spec.ts 覆盖;本 spec 只补「无指针设备」路径(验收 B-10 的浏览器层)。
// jsdom 单测 mega-dropdown.test.tsx:55-74 用 fireEvent 测过 Escape,但 relatedTarget 与真实焦点顺序
// 在 jsdom 里不成立,不能替代浏览器验证。
const NAV_SELECTOR = 'nav[aria-label="主导航"]';
function productTrigger(page: Page) {
return page.getByRole('navigation', { name: '主导航' }).getByRole('button', { name: '产品', exact: true });
}
function viewAllLink(page: Page) {
return page.getByRole('link', { name: '查看全部产品' });
}
async function openWithKeyboard(page: Page) {
const trigger = productTrigger(page);
await page.goto('/');
await expect(trigger).toBeVisible();
await expectHydrated(trigger);
// dev 目标下该按钮的 DOM 节点会在 hydration 后被整体替换(实测:失败样本里 click/keydown
// 计数为 1 但 aria-expanded 恒 false、焦点不在按钮上;通过样本反过来是 click=0 而 aria=true,
// 说明监听挂在已被换掉的旧节点上)。生产产物不复现,属 dev/ Fast Refresh 竞态,
// 与 e2e/primary-nav.ts:11-14 记录的是同一类窗口 ⇒ 按本仓既有写法重发**交互**而不只是重读断言。
await expect(async () => {
await trigger.press('Enter');
await expect(trigger).toHaveAttribute('aria-expanded', 'true', { timeout: 2000 });
}).toPass({ timeout: 30000 });
await expect(viewAllLink(page)).toBeVisible();
return trigger;
}
test.describe('主导航下拉的键盘可操作性', { tag: '@a11y' }, () => {
// 桌面 mega dropdown 在移动断点整体不渲染(chromium-mobile 实测 element(s) not found);
// 移动导航是另一个组件(抽屉),它的键盘契约另立 spec,不在本文件假装覆盖。
test.beforeEach(async ({ viewport }) => {
test.skip(!!viewport && viewport.width < 768, '移动断点不渲染桌面 mega dropdown');
});
// 依赖真实 Tab 遍历的两例在 webkit 引擎上跳过:本机实测(:3120 生产产物)连续 4 次 Tab 后
// document.activeElement 仍是 BODY,而元素 .focus() 生效且 matches(':focus') 为 true。
// 与 e2e/p4-performance-a11y.spec.ts:240 记录的 N-27 同源(macOS WebKit 未开「全键盘访问」),
// 属引擎/系统默认值差异而非本仓缺陷;主配置的 chromium-mobile 同为 webkit 引擎,一并覆盖。
test('Tab 到达触发器后可用 Enter 展开', async ({ page, browserName }) => {
test.skip(browserName === 'webkit', 'WebKit 本机不响应真实 Tab 键(N-27,见上方注释)');
const trigger = productTrigger(page);
await page.goto('/');
await expect(trigger).toBeVisible();
await expectHydrated(trigger);
await expect(trigger).toHaveAttribute('aria-haspopup', 'true');
await expect(trigger).toHaveAttribute('aria-expanded', 'false');
// 焦点顺序实测(chromium + firefox,:3120 生产产物与 dev 目标读数一致):
// 第 1 站「跳转到主要内容」跳转链接,第 2 站 logo「返回首页」,第 3 站才是本触发器。
await page.keyboard.press('Tab');
await page.keyboard.press('Tab');
await page.keyboard.press('Tab');
await expect(trigger).toBeFocused();
await page.keyboard.press('Enter');
await expect(trigger).toHaveAttribute('aria-expanded', 'true');
await expect(viewAllLink(page)).toBeVisible();
});
test('Tab 焦点进入面板链接而不是跳过面板', async ({ page, browserName }) => {
test.skip(browserName === 'webkit', 'WebKit 本机不响应真实 Tab 键(N-27,见上方注释)');
await openWithKeyboard(page);
await page.keyboard.press('Tab');
await expect(page.locator(`${NAV_SELECTOR} a[href^="/products/"]:focus`)).toHaveCount(1);
});
test('Escape 关闭面板并把焦点还给触发器', async ({ page }) => {
const trigger = await openWithKeyboard(page);
await page.keyboard.press('Escape');
await expect(trigger).toHaveAttribute('aria-expanded', 'false');
await expect(trigger).toBeFocused();
// 卸载断言而非隐藏断言:抓源码注释担心的「看不见但仍在 DOM 里」滞留态
await expect(viewAllLink(page)).toHaveCount(0);
});
test('焦点移出下拉容器即关闭', async ({ page }) => {
const trigger = await openWithKeyboard(page);
await viewAllLink(page).press('Tab');
await expect(trigger).toHaveAttribute('aria-expanded', 'false');
await expect(viewAllLink(page)).toHaveCount(0);
});
});
+3
View File
@@ -0,0 +1,3 @@
# Specs
This is a directory for test plans.
+64
View File
@@ -0,0 +1,64 @@
# 测试计划:主导航下拉的键盘可操作性(WCAG 2.1.1)
生成方式:Playwright Test Agents 的 planner 契约(`.claude/agents/playwright-test-planner.md`)。
落地产物:`e2e/nav-keyboard.spec.ts`(tag `@a11y`)。
被测目标:本机 `:3120` 上的 `dist/standalone` 生产产物,以及门禁默认 `npm run dev` 目标(:3000,由 `playwright.config.ts` 的 webServer 自管)。
## 现状与缺口
- 已覆盖:`e2e/nav-dropdown.spec.ts:8,28` 用 `hover` 展开「产品 / 解决方案」下拉;`e2e/p4-performance-a11y.spec.ts:240,393,424` 覆盖页面级 Tab、焦点样式与跳转链接。
- 未覆盖:**用键盘打不开、也走不出这两个下拉**。契约来源(逐行核对,非推测):
- `src/components/layout/mega-dropdown.tsx:62-76` — 触发器是 `<button onClick={onToggle}>`,带 `aria-haspopup="true"` 与 `aria-expanded={isOpen}`,因此 Enter 天然应能展开。
- `:35-40` — `Escape` 关闭并把焦点还给触发按钮。
- `:42-46` — 焦点移出整个下拉容器(`onBlur` + `relatedTarget`)时关闭;源码注释明确担心「面板看不见但仍在 DOM 里」的滞留态。
- `:94-178` — 面板只在 `isOpen` 时由 `AnimatePresence` 挂载,尾部链接为「查看全部{label}」。
- jsdom 单测(`src/components/layout/mega-dropdown.test.tsx:55-74`)用 `fireEvent.keyDown/blur` 覆盖过 Escape,但 `relatedTarget` 与真实焦点顺序在 jsdom 里不成立,**不能替代浏览器层验证**。
## 实测读数(探索阶段取得,作为断言依据)
| 读数 | 值 | 取证方式 |
| --- | --- | --- |
| 触发器 `aria-expanded` 初值 / `aria-haspopup` | `false` / `true` | `browser_evaluate` |
| 焦点顺序 | 第 1 站「跳转到主要内容」→ 第 2 站 logo「返回首页」→ **第 3 站触发器** | 真键盘 Tab 逐步读 `document.activeElement` |
| 首页可聚焦元素总数 | 60 | 同上 |
| 面板内链接 href 前缀 | `/products/*`(与一级导航 `/services` 可区分) | `src/lib/site-config.tsx` + DOM 读数 |
⚠ 早期一次误读:探针返回的是**数组下标 2**,被当成「按 2 次 Tab」,导致首版断言少一次按压而判红。下标 ≠ 按压次数,此类换算必须显式重数。
## 场景与最终归属
| # | 场景 | 结论 |
| --- | --- | --- |
| 1 | 3 次 Tab 到触发器 → Enter 展开 | 已落地,`aria-expanded` 转 true 且「查看全部产品」可见 |
| 2 | 展开后 Tab,焦点落在面板链接上 | 已落地,断言 `nav a[href^="/products/"]:focus` 计数 1 |
| 3 | Escape 关闭 + 焦点归还触发器 + **面板节点卸载** | 已落地,用 `toHaveCount(0)` 而非 `toBeHidden()`,专抓源码注释担心的滞留态 |
| 4 | 焦点移出容器即关闭(`onBlur` 契约) | 已落地,从尾部链接按 Tab 离开容器 |
| 5 | 「敬请期待」占位项不进入焦点顺序 | 延后:需全量 Tab 枚举,成本高 |
| 6 | 「解决方案」下拉同 1–4 | 延后:与 1–4 同构,避免一次引入 8 条断言面 |
| 7 | 移动端抽屉导航的键盘契约 | **另立 spec**:移动断点下桌面 mega dropdown 整体不渲染(`element(s) not found` 实测),是另一个组件 |
## 两条引擎/目标差异(决定跳过范围,均已实测)
1. **WebKit 不响应真实 Tab 键**:连续 4 次 Tab 后 `document.activeElement` 仍是 `BODY`,而 `.focus()` 生效且 `matches(':focus')=true`。与 `e2e/p4-performance-a11y.spec.ts:240` 记录的 N-27 同源(macOS WebKit 未开「全键盘访问」)。⇒ 只有依赖 Tab 遍历的场景 1–2 在 webkit 引擎跳过(含 `chromium-mobile`),场景 3–4 在 webkit 桌面照常跑并通过。
2. **dev 目标下触发器 DOM 节点会在 hydration 后被整体替换**:失败样本里 `click`/`keydown` 计数为 1 但 `aria-expanded` 恒 false、焦点不在按钮上;通过样本相反(`click=0` 而 `aria=true`)——监听器绑在已被换掉的旧节点上。**生产产物不复现**。与 `e2e/primary-nav.ts:11-14` 记录的是同一类 hydration 窗口 ⇒ `openWithKeyboard()` 用 `expect(...).toPass()` 重发**交互**(`trigger.press('Enter')`)而不只是重读断言。
## 实跑读数
| 轮次 | 命令形态 | 结果 |
| --- | --- | --- |
| 稳定性 | `--project=firefox --project=chromium --workers=1 --repeat-each=3`(dev) | 24 passed / 0 failed,EXIT=0 |
| 门禁形态 A | `--config=playwright.config.ts` 四 project(dev,默认并发) | 10 passed / 6 skipped,EXIT=0 |
| 门禁形态 B | `E2E_TARGET=production`(config 自起 `node dist/standalone/server.js`) | 10 passed / 2 skipped,EXIT=0 |
| 类型 / Lint | `npm run type-check` / `npx eslint e2e/nav-keyboard.spec.ts` | 均 EXIT=0,新文件 0 告警 |
跳过计数口径:A 的 6 = webkit 桌面 2 + `chromium-mobile` 4;B 的 2 = webkit 桌面 2。
## 手工复现
```bash
# 产物形态需要先装配静态资源(N-9):npm run build 或 npm run postbuild
npm run postbuild
HOSTNAME=localhost PORT=3120 node dist/standalone/server.js &
cd e2e && E2E_BASE_URL=http://localhost:3120 npx playwright test nav-keyboard.spec.ts \
--config=playwright.local.config.ts --project=chromium
```