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:
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>
|
||||
@@ -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
|
||||
@@ -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.
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"mcpServers": {
|
||||
"playwright-test": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"playwright",
|
||||
"run-test-mcp-server"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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 剩余死选择器清理(需与视觉基线写授权分开审批)。
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,3 @@
|
||||
# Specs
|
||||
|
||||
This is a directory for test plans.
|
||||
@@ -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
|
||||
```
|
||||
Reference in new issue
Block a user