用途
Playwright Operations 面向使用 Playwright Test（@playwright/test）进行端到端测试的工程团队，提供从选择器、夹具、网络模拟到 CI 与不稳定测试排查的操作规范。资料说明 Python 版本（pytest-playwright）存在相同的浏览器 API，但采用 pytest 风格夹具，模式可直接迁移，运行器配置则不通用。
快速开始
提供的命令包括：
npm init playwright@latest
npx playwright test
npx playwright test --project=chromium --grep "@smoke"
npx playwright test --ui
npx playwright codegen https://app.local
npx playwright show-report
npx playwright show-trace trace.zip
选择器策略
资料给出选择器优先级：优先使用 getByRole（带 ARIA 角色，顺带验证无障碍）、getByLabel（表单字段）、getByPlaceholder（无标签输入）、getByText（非交互文本），其次为 getByTestId（语义无法消歧时的稳定钩子，可用 testIdAttribute 配置属性），最后才是 CSS/XPath。理由是这样定位更贴近用户感知、对标记变化更健壮，且 getByRole 在无障碍退化时会明确失败。
断言与等待
反对检查一次即结束的断言与 waitForTimeout，推荐 Web-First Assertions（如 expect(...).toBeVisible()、toHaveCount、toHaveURL、expect.soft）。动作（click、fill）会自动等待可操作性。异步非 DOM 条件可用 expect.poll 或 toPass。建议启用 @typescript-eslint/no-floating-promises 以防止漏写 await。
配置骨架
给出 defineConfig 示例，包含 testDir、fullyParallel、forbidOnly、retries、workers、reporter、use 中的 baseURL/trace/testIdAttribute，以及 projects（setup 项目与 chromium 项目、storageState、dependencies）和 webServer 配置。
夹具决策树
按需求选择：每测试对象用 test.extend() 测试级夹具；昂贵可共享资源用 worker 级（scope: 'worker'）；每测试都需的副作用用自动夹具（auto: true）；可调配置用 option；跨模块用 mergeTests；按文件/角色认证状态用 test.use({ storageState })。推荐 POM-as-fixture：页面对象通过夹具注入，页面对象只暴露定位器与动作，不封装断言、不保存元素句柄。
网络与 API
按需求选择：第三方 API 打桩用 page.route 配合 fulfill；调整真实响应用 route.fetch 后 fulfill；模拟失败用 abort 或返回 500；多端点真实形状用 HAR 录制回放（routeFromHAR，update: true 录制）；纯 API 测试用 request 夹具 / APIRequestContext；快速播种数据并通过 UI 断言采用混合方式（用 request 创建，用 page 验证）；WebSocket 用 page.routeWebSocket。原则是模拟不拥有的第三方依赖，真实运行自有后端。
认证
标准模式是在 setup 项目登录一次，通过 page.context().storageState 保存，并在 use 中复用。按场景可选：单一共享账号、按角色分文件（admin.json、user.json）配合 test.use、worker 级账号夹具（testInfo.parallelIndex）、API 登录（request.post + request.storageState）。注意事项：将 playwright/.auth/ 加入 .gitignore；storageState 只捕获 cookies 与 localStorage，不含 sessionStorage；保存前必须断言已登录信号。
并行、重试与隔离
workers 在 CI 中设为 1，本地为逻辑核心一半；fullyParallel 使分片按测试切分；分片用 --shard=1/4 并在之后合并 blob 报告；retries 配合 trace: 'on-first-retry'。serial 模式被视为坏味道。隔离要求每个测试使用全新 context/page，不读取其他测试写入的状态。不稳定诊断用 trace 查看器、UI 模式、PWDEBUG=1、--repeat-each=20 --workers=4。
不稳定测试分诊
可通过 JSON reporter 输出结果，再用 scripts/triage-flakes.py 排序：
npx playwright test --reporter=json > results.json
scripts/triage-flakes.py results.json
输出为排序后的 TSV（或 --json 信封，schema claude-mods.playwright-ops.flake-triage/v1）：先列仅在重试时通过的 flaky 测试（按重试次数再按时长排序），再列硬失败，包含 file:line、状态序列与总时长。退出码 10 表示发现 flaky/失败，退出码 0 表示全通过。--outcome all 包含通过测试，-n N 限制行数。
CI（GitHub Actions）
给出步骤示例：checkout、setup-node、npm ci、npx playwright install --with-deps chromium、npx playwright test、上传 playwright-report 工件。还讨论容器镜像与 install --with-deps 的取舍、浏览器缓存、分片报告（blob 上传后用 merge-reports 合并）、PR 中 fail-fast: false 与 --max-failures=10 等建议。
视觉测试
展示 toHaveScreenshot 的 maxDiffPixels、mask、fullPage 用法，首次运行生成基线并失败，用 --update-snapshots 更新；快照按浏览器与平台命名，建议在与 CI 相同的 Docker 镜像中生成基线；toHaveScreenshot 默认禁用动画；可用 expect.toHaveScreenshot 配置全局默认；toMatchSnapshot 用于非图像数据。
组件测试与 Cypress 比较
@playwright/experimental-ct-react（以及 vue/svelte）仍是实验性的，组件级测试更推荐 Vitest 浏览器模式或 Testing Library。资料给出 Playwright 与 Cypress 在浏览器支持、并行、多标签/多源/iframe、API 测试、组件测试、交互式体验等方面的对比，并建议组件测试成熟度或既有 Cypress 投入为主时选 Cypress，否则新 E2E 套件默认 Playwright。
调试与代码生成
列出 UI 模式、Inspector（PWDEBUG=1 或 page.pause()）、codegen、trace 查看器、--headed --debug、VS Code 扩展等工具与用途。codegen 输出应视为草稿并重构进 POM/夹具。另提到官方 Playwright MCP 服务器（@playwright/mcp）用于智能体驱动的浏览器自动化，与测试运行器不同，不应混淆。
参考资料
包括 references/fixtures-and-pom.md（夹具作用域/选项/合并、POM-as-fixture 架构与反模式）、references/network-and-api.md（route/fulfill/abort、HAR 回放、API 测试、混合播种、WebSocket）、references/ci-patterns.md（完整 GH Actions 工作流）、references/flake-hunting.md（系统性 flake 诊断）、scripts/triage-flakes.py、assets/playwright.config.template.ts（带注释的生产配置模板）。收费标准、平台支持范围与版本兼容性等资料未提供。