name: badminton-playwright-mobile-qa description: Use when writing or updating mobile-first Playwright coverage for the badminton H5 flow, including home CTA, upload readiness, candidate clip selection, processing progress, report rendering, history, compare, and error recovery.
Badminton Playwright Mobile QA
何时使用
当任务涉及前端主流程自动化验证时使用：
- 新增或修改 Playwright E2E
- 验证首页到上传、候选片段选择、处理中、报告页渲染
- 调整 mock API、fixture 数据、移动端交互选择器
先读什么
当前 Playwright 已经接入且是移动端优先，不需要从零搭建。先读：
frontend/playwright.config.tsfrontend/e2e/home-and-upload.spec.tsfrontend/e2e/processing.spec.tsfrontend/e2e/report-history-compare.spec.tsfrontend/e2e/error.spec.tsfrontend/e2e/support/mockApi.ts
真实约束：
- 默认项目是
mobile-chromium - 使用 iPhone 13 viewport
- 测试自启 Vite dev server
- mock 覆盖
/api与/artifacts
工作顺序/决策顺序
- 先确认要覆盖的是哪条真实用户路径，再决定补新 spec、补场景 builder，还是只更新 mock/fixture。
- 优先让测试围绕可见行为断言，再回头补稳定选择器；不要先盯 DOM 结构和 className。
- 如果 spec 文件开始重复 setup、fixture JSON 或多段相似路径，先抽共享 helper / scenario builder 再加场景。
- mock 数据要始终贴近真实 contracts；契约变化应先修共享形状，再修断言。
- 最终说明要能回答“测的是哪条用户路径”“为什么足够”这两个问题。
核心规则
- 先测真实用户路径，不测实现细节。
- selector 优先级：
getByRole- 可读名称
- 稳定
testid（只有在 role/name 不稳定时）
- 默认优先 mock API，保持稳定与可重复，不把真实 backend 当 E2E 前提。
- 测试要体现当前真实主流程：
- 首页 CTA
- 上传前就绪检查
- 上传并粗扫片段
- 用户确认候选片段
- 处理中步骤反馈
- 报告页/历史/对比页渲染
taskId深链进入/analyses/:taskId/processing、/analyses/:taskId/report、/analyses/:taskId/comparison
- 当共享契约变化时，要同步更新：
frontend/e2e/support/mockApi.ts- fixtures
- 断言文案或状态
- 复用优先：优先扩展已有 mock API、fixture builder、共享 helper 和通用断言，不要在 spec 中平行复制 setup。
- 模块拆分优先：shared mock、scenario builder、data factory、页面级断言应按职责拆开，不要让单个 spec 同时背负所有数据准备与所有流程。
- 文件体量控制：
- 单个 spec 文件通常接近 250 行就要考虑按场景拆分
- fixture builder、mock helper 超过约 200 行应按页面或流程拆分
- 不要把 CSS 结构、类名、内部 state 当断言主目标，也不要把大段内联 JSON 当默认写法。
截图 / 壳层回归补充规则
- 页面重排后，除了流程断言，还要验证顶部栏、底部 Tab、主 CTA 是否在滚动时保持稳定。
- 对移动端产品壳层，优先断言“主滚动发生在
main，而不是window”。 - 当页面进入空态、错误态或结果页时，也要检查是否仍然保留了错误的长文档流布局。
- 如果任务明确要求产品化或截图 review，至少覆盖首页、上传准备、选片页、处理中、报告、历史、对比、错误其中的关键页面。
- 当首屏观感是风险点时，补截图或视觉快照，而不是只断言链接和文案存在。
何时联动其他 skills
mobile-ui-interaction-design：需要把 Playwright 验证进一步用于截图 review、视觉层级复核和 UI polish 时badminton-h5-product-ui：页面产品化后需要补测试badminton-analysis-flow：上传、选片、处理状态变化shared-contracts-and-adapters：mock 数据需要跟共享契约同步repo-delivery-baseline：需要决定是否补跑整个前端测试路径
何时读取 examples/
确认要覆盖的用户路径后再读对应 example：
examples/homepage-to-upload.spec-example.md：首页到上传准备路径变化时读examples/candidate-clip-selection.spec-example.md：候选片段选择或推荐逻辑变化时读examples/report-page-rendering.spec-example.md：报告页渲染与核心卡片断言变化时读examples/fixed-shell-scroll-assertions.md：需要验证固定导航、独立滚动和 CTA 可见性时读
任务完成后的输出要求
最终交付说明至少要写清：
- 新增或修改了哪些 Playwright 场景
- 覆盖的是哪条真实用户路径
- 是否更新了 mock API 或 fixtures
- 如果只做了局部验证，要明确哪些主流程还没覆盖