Playwright 使用指南：场景、能力边界与工程实践

AI 参与说明（Agent：Codex）：本文由 Codex 基于 Playwright、Vitest、jsdom、Testing Library、Storybook 与 W3C WAI 官方资料辅助整理。产品能力、API 与限制以所列一手资料为准；“能力地图”“四维选型模型”及推荐的 CI 分层是本文为工程选型所作的归纳，不代表这些项目共同发布的正式分类。

版本与核验范围：资料核验于 2026-08-26，npm Registry 当日显示 @playwright/test 稳定版为 1.62.1；横向比较按 Vitest 4.1.11、jsdom 30.0.1 与 Storybook 10.5.10 的当前官方文档整理。文中的自包含 Smoke Test 可以不依赖业务应用运行；涉及 /api/test-data/*、Authentication、Story Gallery 与 CI 的片段属于工程模板，需要按目标项目调整 Endpoint、Script、Secret 与 Accessible Name。

结论#

Playwright 的核心定位不是“浏览器版 Unit Test”，而是由两层能力组成的 Web Automation 与 End-to-End Testing 工具链：

1. Playwright Library 提供统一的 Browser Automation API，用来启动和控制 Chromium、Firefox、WebKit，管理 BrowserContext、Page、Network 与 Browser Event。
2. Playwright Test 在 Library 之上提供 Test Runner、Web-first Assertions、Test Isolation、Fixtures、Projects、Parallelism、Retries、Sharding、Reporter、Trace Viewer 与 CI Workflow。

官方也建议大多数 End-to-End Testing 场景直接采用 @playwright/test；只有编写非测试 Browser Automation、Crawler 或完全自定义的 Runner 时，才通常直接使用 playwright Library。Playwright Installation Playwright Library

Playwright 的核心 Browser Automation 还提供 Python、Java 与 .NET Binding，但各语言的 Testing Ecosystem 不同：JavaScript / TypeScript 使用 Playwright Test，Python 官方推荐 Pytest Plugin，Java 通常结合 JUnit / TestNG，.NET 则提供 MSTest、NUnit 与 xUnit 等 Base Class。本文的 Runner、Config、Fixture、Reporter 与 Test Agents 均特指 JavaScript / TypeScript 的 @playwright/test，不能原样套用到其他语言。Playwright Supported Languages

Playwright 最适合回答这一类问题：

在指定 Browser、Viewport、Locale、Authentication State、Backend State 与 Network Condition 下，用户能否通过真实 Browser Interaction 完成一段可观察的 Application Flow，并在失败时留下可复查现场？

它尤其适合 Login、Routing、Search、Checkout、Upload、Download、Popup、Multi-page、WebSocket、Role Permission、Responsive Layout、Cross-browser Regression 与部署后的 Smoke Test。它也能测试 API 和独立 Component，但这些不是所有项目都应优先放到 Playwright 的理由。

Playwright 不能单独证明以下结论：

• Pure Function、State Reducer 与大量边界值已经得到最低成本覆盖。
• Frontend 与独立 Backend 的 Consumer / Provider Contract 仍然兼容。
• UI 设计本身美观、清晰或符合未经编码的 Design Intent。
• 页面完全符合 WCAG，或真实 Screen Reader 用户体验没有问题。
• Emulated Mobile Profile 等同于真实 iPhone / Android Device 及其 Mobile Safari / Chrome 环境。
• 系统已经通过 Load、Performance、Security 或 Native App Testing。

因此，Playwright 通常是前端 Test Portfolio 中“真实 Application Flow 与失败证据”这一层，而不是替代 Vitest、Type Checking、Contract Testing、Visual Review 和人工 Accessibility Evaluation 的单一工具。

先用四个维度理解 Playwright#

把 Playwright 与 Vitest、jsdom、Testing Library 或 Storybook 直接放在一条“谁更强”的轴上，容易得出错误结论。它们分别可能承担 Test Runner、Runtime、Driver、Query Utility、State Catalog 或 Oracle。选型前应先区分四个维度。

同一个 Test 可以组合多个维度。例如，“在 WebKit 的 390 × 844 Viewport 中点击 Checkout 后，Confirmation Heading 可见且 Receipt Screenshot 与 Baseline 一致”表示：

• SUT Scope 是 Checkout User Journey。
• Runtime 是 WebKit 和指定 Viewport。
• Driver 是 Locator.click()。
• Oracle 同时包含 Role Assertion 与 Pixel Comparison。

Test 通过只说明这个有限组合成立。它不能自动外推到其他 Browser、数据、角色、Network Condition、Viewport 或人工 Design Judgment。

Test Runner、Automation Driver 与 Browser 不是一回事#

使用 @playwright/test 时，Test Code 主要在 Node.js Worker 中运行；Page 和 BrowserContext 对象从 Node.js 驱动 Browser，页面中的 Application Code 则在真实 Browser 中运行。page.evaluate() 才会把 Function 放到 Page Context 执行。

这与 Vitest Browser Mode 的心智模型不同：Vitest Test Code 本身在 Browser 中运行，Playwright 可以只是 Browser Provider。即使 Provider 使用 Playwright，Vitest Browser Test 也不会因此变成 Playwright Test，vitest/browser 的 page 也不是 @playwright/test 的 Page。

Playwright 产品族与 Agent 入口#

“使用 Playwright”还可能指五种不同的 Product Surface。它们共用 Browser Automation 基础，但输出、隔离和工程职责并不相同。

@playwright/cli 面向需要控制 Context Size 的 Coding Agent：Concise Command 和 Installable Skill 可以避免把大型 Tool Schema 与完整 Accessibility Tree 反复放进 Model Context。Playwright MCP 则更适合需要 Persistent State、Structured Accessibility Snapshot 与多轮页面推理的 Specialized Agent Loop。Playwright Coding Agents CLI Playwright MCP

这两个 Agent Surface 都能 Navigation、Click、Fill、Tabs、Network Mock、Storage State 与 Screenshot，但它们不会自动知道“正确结果是什么”。Agent 说“页面看起来正常”只是 Observation；只有写入 Playwright Test 的明确 Assertion、Snapshot Baseline 或人工批准规则，并在 CI 复跑，才构成可追踪的 Acceptance Evidence。

还要注意 Isolation 差异：Playwright Test 默认每个 Test 使用 Fresh BrowserContext；CLI 的 Session 可以在多次 Command 间保留 State，MCP 默认也可以使用 Persistent Profile。让 Agent 探索页面时这种持续状态很方便，但不能把探索 Session 的成功直接当作独立 Test 可重复的证明。启用 MCP 的 browser_run_code_unsafe 后，执行任意 Playwright JavaScript 等同于在 Server Process 中执行代码，只应向受信任 Client 开放。

场景决策表#

Playwright 能力全景#

1. Test Runner 与 Browser Automation#

Playwright Test 把 Browser Automation 和测试工程能力放在同一个 Package 中：Test Discovery、Lifecycle、Assertion、Isolation、Parallelism、Retry、Reporter、Trace 与 Project Matrix 都由 Runner 管理。Playwright Library 则只负责 Browser Automation，需要调用者自行管理 Assertion、Runner、Context Cleanup 和 Report。Playwright Library

2. Locator、Actionability 与 Auto-waiting#

Locator 是 Playwright 稳定性的中心。它不是一次性保存的 Element Handle，而是描述“如何在当前页面找到目标”；每次 Action 都会重新解析目标。官方优先推荐面向用户语义的 getByRole、getByLabel、getByText，必要时再使用显式 Test ID。Testing Library 也把 getByRole 和 Accessible Name 放在 Query Priority 的首位，两者在“从用户可感知语义定位元素”这一原则上相近。Playwright Locators Testing Library Queries

调用 locator.click() 时，Playwright 会在 Timeout 内等待 Locator 严格解析为一个元素，并检查目标是否 Visible、Stable、Receives Events、Enabled；不满足就失败。不同 Action 使用不同的 Actionability Check。Web-first Assertions 也会 Retry，直到 Condition 成立或超时。Playwright Auto-waiting

await page.getByLabel("Email").fill("reader@example.com");
await page.getByRole("button", { name: "Place order" }).click();

await expect(page).toHaveURL(/\/orders\/[^/]+$/);
await expect(
  page.getByRole("heading", { name: "Order confirmed" }),
).toBeVisible();

这套机制减少的是“元素还没准备好”造成的 Flakiness，不是所有异步问题。以下做法仍然会制造不稳定 Test：

• 用 page.waitForTimeout(2000) 猜测系统何时完成。
• 使用容易变化的 CSS Path 或 locator("div:nth-child(3)")。
• 对动态 List 调用不会等待的 locator.all()，却没有先断言 List 已稳定。
• 大量使用 { force: true } 绕过 Receives Events 等检查。
• 断言内部实现或 Class Name，而不是用户可观察的 Outcome。

force 适合明确要测试特殊低层行为的少数场景，不应作为 Overlay、Animation 或 Locator 问题的常规修复。

3. Interaction 与 Browser Event#

Playwright 可以驱动 Text Input、Checkbox、Radio、Select、Click、Keyboard Shortcut、Mouse、Focus、Drag and Drop、Scroll、Touch 相关行为和 File Upload。Playwright Actions

对 Popup、Download、FileChooser 等由 Action 触发的 Event，应先建立 Wait Promise，再执行 Action，避免 Event 在开始等待之前已经发生：

test("downloads an invoice", async ({ page }, testInfo) => {
  const downloadPromise = page.waitForEvent("download");
  await page.getByRole("button", { name: "Download invoice" }).click();
  const download = await downloadPromise;

  expect(download.suggestedFilename()).toMatch(/\.pdf$/);
  await download.saveAs(testInfo.outputPath(download.suggestedFilename()));
});

每个 BrowserContext 可以包含多个 Page；它们共享 Context Profile 中的 Cookie，同源 Page 也可观察到相同的 Local Storage / IndexedDB，而 Session Storage 属于各自的 Top-level Page。需要模拟两个独立用户时，应创建两个 BrowserContext，而不是只开两个 Tab。Playwright Pages

4. Test Isolation 与 Fixtures#

Playwright Test 默认给每个 Test 创建新的 BrowserContext 和 Page。BrowserContext 类似独立的 Incognito Profile，Cookie、Local Storage、Session Storage 等 Browser State 不会自动泄漏到下一个 Test。相比“执行后清理”，从 Clean Slate 开始更容易保证 Parallelism 与单测复现。Playwright Isolation

但 Browser Isolation 不等于系统完全隔离：

• Backend Database、Queue、Email Inbox、R2 Object 与第三方 Sandbox 仍可能被多个 Test 共享。
• 同一个 Account 的 Server-side State 不会因为换了 BrowserContext 自动清空。
• Parallel Test 必须使用唯一 Record、独立 Account、Namespace 或可重复 Reset 的 Test Data。

Fixtures 把 Setup、Dependency 与 Teardown 放在同一处。Test-scoped Fixture 每个 Test 建立一次；Worker-scoped Fixture 可在一个 Worker 内复用昂贵 Resource；Fixture 可以 Lazy、Composable、Type-safe，并依赖其他 Fixture。Playwright Fixtures

// tests/fixtures.ts
import { test as base } from "@playwright/test";

type AppFixtures = {
  projectId: string;
};

export const test = base.extend<AppFixtures>({
  projectId: async ({ request }, use) => {
    const response = await request.post("/api/test-data/projects", {
      data: { name: `e2e-${crypto.randomUUID()}` },
    });
    const project = await response.json();

    await use(project.id);

    await request.delete(`/api/test-data/projects/${project.id}`);
  },
});

export { expect } from "@playwright/test";

Fixture 不是把所有 Setup 都隐藏起来的理由。业务前置状态仍应在 Test Name、Step 或 Test Data Builder 中可读；Worker-scoped Fixture 也不能共享会被 Test 修改的 State。

5. Projects、Browser 与 Device Emulation#

Projects 是“使用同一配置运行的一组 Test”。它不仅能表示 Chromium、Firefox、WebKit，也能表示 Mobile Viewport、Logged-in / Logged-out、不同 Locale、不同 Environment、不同 Retry 或 Timeout Strategy。每增加一个 Project，匹配的 Test 通常就会多执行一遍。Playwright Projects

Playwright 提供 Chromium、Firefox、WebKit Browser Build；还可以通过 Channel 使用机器上的 Google Chrome 与 Microsoft Edge。需要注意：Playwright Firefox 依赖 Patch，不能控制 branded Firefox；Playwright WebKit 来自 WebKit Main Branch，也不能控制 branded Safari。最接近 Safari 的自动化覆盖通常是在 macOS 上运行 Playwright WebKit，但它仍不是在真实 Safari 或 iPhone Hardware 上执行。Playwright Browsers

Device Descriptor 会组合 User Agent、Screen Size、Viewport、Touch 与 isMobile 等参数；Playwright 还可以 Emulate Locale、Timezone、Geolocation、Permission、Color Scheme、Reduced Motion、Offline 等状态。这是 Browser Behavior Emulation，不是真实 CPU、Memory、Radio、GPU、Mobile OS、Virtual Keyboard 或 Sensor Hardware Test。Playwright Emulation

// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  projects: [
    {
      name: "chromium-desktop",
      use: { ...devices["Desktop Chrome"] },
    },
    {
      name: "webkit-mobile",
      use: {
        ...devices["iPhone 13"],
        locale: "zh-CN",
        timezoneId: "Asia/Shanghai",
      },
    },
    {
      name: "reduced-motion",
      use: {
        ...devices["Desktop Chrome"],
        reducedMotion: "reduce",
      },
    },
  ],
});

推荐先让 Critical Flow 在一个 Primary Project 中稳定，再根据真实用户和故障风险增加 Browser / Device Matrix；无差别运行所有 Test × 所有 Profile 很容易让 CI 成本膨胀，却没有带来等比例信心。

特殊与 Experimental Automation Surface#

Playwright 还覆盖少量 Browser 之外或嵌入式的 Surface，但这些能力有额外前置条件，不能把它们泛化成完整 Native App Testing。

Playwright Chrome Extensions Playwright WebView2 Playwright Electron API Playwright Android API Playwright BrowserType API Playwright CDPSession API Playwright Coverage API

6. Authentication 与多角色#

Playwright 可以把已登录的 Browser State 保存为 storageState，让后续 Test 从已认证状态开始；推荐用 Setup Project 生成 Authentication State，再通过 Project Dependency 让目标 Project 使用它。这样不用每个 Test 重复 UI Login。Playwright Authentication

Authentication State 可能包含足以冒充 Test Account 的 Cookie 和 Header，官方明确不建议提交到 Public 或 Private Repository。应把 playwright/.auth 加入 .gitignore，在 CI 临时生成，并使用最低权限的专用 Test Account。

storageState 也不是“保存所有 Browser State”：它不自动保存 sessionStorage；默认覆盖 Cookie 与 Local Storage，IndexedDB 和 Virtual WebAuthn Credential 需要显式启用对应选项。若 Application 把 Token 只放在 sessionStorage，需要自行建立保存 / 恢复方案。Playwright storageState API

共享 Account 只适合 Test 不会修改共享 Server-side State 的场景。若 Test 修改 Profile、Document 或 Permission，应为 Parallel Worker 或 Test 分配独立 Account。多角色协作可以在一个 Test 中创建多个带不同 storageState 的 BrowserContext：

test("admin approves a request created by a member", async ({ browser }) => {
  const memberContext = await browser.newContext({
    storageState: "playwright/.auth/member.json",
  });
  const adminContext = await browser.newContext({
    storageState: "playwright/.auth/admin.json",
  });

  const memberPage = await memberContext.newPage();
  const adminPage = await adminContext.newPage();

  // Member creates the request; admin observes and approves it.

  await memberContext.close();
  await adminContext.close();
});

7. Network、API、HAR 与 WebSocket#

Playwright 能监听 HTTP(S)、XHR 与 fetch Request / Response，也能通过 page.route 或 browserContext.route Abort、Continue、修改 Request、Fulfill Mock Response，或者先请求真实 Provider 再修改 Response。HAR 可以记录并回放一组 Network Interaction。Playwright Network Playwright Mock APIs

await page.route("**/api/recommendations", async (route) => {
  const response = await route.fetch();
  const json = await response.json();

  await route.fulfill({
    response,
    json: { ...json, items: [] },
  });
});

Network Mock 适合稳定制造 Empty、Error、Timeout 与 Edge Case，但应保留少量调用真实 Backend 的 Integration / E2E Test。否则 Mock 只证明“Frontend 能处理自己编造的 Response”，不能证明 Production Provider 真会返回该 Shape。

APIRequestContext 可以直接从 Node.js 发 HTTP(S) Request，常用于：

1. 不打开页面地测试 REST API。
2. 在 UI Test 前创建 Server-side Test Data。
3. 完成 UI Action 后检查 Server Post-condition。

Cookie Jar 是否共享取决于 Context 来源：browserContext.request 与 page.request 会和对应 BrowserContext 共享 Cookie，Response 的 Set-Cookie 也会更新 Browser State；独立创建的 APIRequestContext 或独立 request Fixture 则可以保持隔离。Playwright API Testing

这仍不等同于 Pact 等 Consumer-driven Contract Testing。Playwright API Test 通常验证具体 Provider Instance 的请求结果；Pact Contract 则需要 Consumer Interaction Artifact 和 Provider Verification Workflow。

Playwright 还支持 WebSocket Inspection、Mock 与 Frame Modification；page.on("websocket") 可以观察 Sent / Received Frame。它适合验证 Realtime UI 对 Message 的反应，但不负责证明 Backend 在高并发、断线重连、顺序、Exactly-once / At-least-once 等 Delivery Semantics 下正确。Playwright WebSocket

当 Service Worker 或 MSW 接管 Request 时，Playwright 原生 Route 可能看不到相应 Network Event。官方建议需要原生 Routing 时考虑 serviceWorkers: "block"，并根据目标决定是测试 Service Worker 本身，还是绕开它测试 Page Network。Playwright Network and Service Workers

8. Browser API、Permission 与 Clock#

对 Geolocation、Permission、Color Scheme 等常见能力，优先使用 BrowserContext / Emulation Option。对 Battery 等没有统一 Automation API 或 Browser 支持不完整的接口，可以在 Page Load 前通过 page.addInitScript() 提供受控 Mock。Playwright Mock Browser APIs

page.clock 可以固定 Date，或控制 Timer、requestAnimationFrame、performance 等时间相关 Global，用于测试 Countdown、Scheduled Refresh、Debounce 与 Expiration，而不必真实等待。Clock 安装顺序会影响 Page 中原生 Function，必须按官方约束在相关调用之前安装。Playwright Clock

9. Oracle：Behavior、Geometry、Visual 与 ARIA#

Playwright 不会自行知道“什么是正确 UI”。它提供多种 Observation Surface 和 Comparator，团队仍需选择与 Requirement 对应的 Oracle。

Visual Comparison 不是普通 Screenshot#

page.screenshot() 只捕获图片；expect(page).toHaveScreenshot() 或 expect(locator).toHaveScreenshot() 才会创建并比较 Baseline。首次运行会生成 Reference，后续运行产生比较结果。Operating System、Browser Version、Font、Hardware、Headless Mode 等都可能改变 Rendering，因此 Baseline 与 Comparison 必须在一致环境执行。Playwright Screenshots Playwright Visual Comparisons

Visual Regression 更适合稳定、高价值的 Page 或 Region。Dynamic Timestamp、Animation、Random Avatar 等内容应通过稳定 Test Data、Clock、Animation Control 或小范围 Mask 处理；不要用巨大 Mask 和宽松 Threshold 把真实变化一起隐藏。

ARIA Snapshot 不是 Screenshot，也不是 WCAG Certificate#

toMatchAriaSnapshot 比较 Accessibility Tree 的 YAML Template，适合检查 Role、Accessible Name、State 与 Hierarchy。它比整页 DOM Snapshot 更接近辅助技术可感知的语义，但不会验证 Pixel、Color Contrast、完整 Keyboard Flow 或 Screen Reader 体验。Playwright ARIA Snapshot

Playwright 官方 Accessibility Guide 使用 @axe-core/playwright 执行自动化 Scan，同时明确提示许多问题只能通过 Manual Testing 发现。W3C WAI 也指出，没有任何单一工具能判定 Site 是否满足 Accessibility Standard，仍需要有知识的人工评估。Playwright Accessibility Testing W3C WAI Evaluating Web Accessibility

推荐的最小 Accessibility Evidence 是：

• 用 Role / Label Locator 迫使关键 Control 暴露稳定语义。
• 用 Keyboard 驱动 Tab、Enter、Escape 与 Focus Return。
• 对关键 Structure 使用小范围 ARIA Snapshot。
• 用 axe 扫描常见自动规则。
• 对 Critical Flow 做 Manual Keyboard、Screen Reader 与 Inclusive User Review。

10. Trace、Screenshot、Video 与 Report#

Playwright 的强项不仅是“执行 Browser”，还包括失败后的 Post-mortem Evidence。

Trace Viewer 可以查看 Action 前、Action 时、Action后的 DOM Snapshot，并关联 Network、Console 与 Source，对“只在 CI 失败”或 Agent 提交尤其有价值。Trace 是调试 Artifact，不是额外 Assertion；没有 Assertion 的 Flow 即使 Trace 很完整，也不构成有效 Acceptance Test。Playwright Trace Viewer

Video 默认关闭，只有 BrowserContext 关闭后才完整保存。Video 适合观察长 Flow 与 Animation，但通常没有 Trace 的 DOM、Network 和 Locator 信息精确；不建议每次成功运行都长期保留。Playwright Videos

11. Parallelism、Retries、Sharding 与 CI#

Playwright 默认并行运行 Test File；同一 File 中的 Test 默认在同一个 Worker 内按声明顺序执行。Worker 是独立 OS Process，每个 Worker 启动自己的 Browser；发生 Test Failure 后，Runner 会关闭有问题的 Worker 并用新 Worker 继续，以保持后续环境干净。Playwright Parallelism

Retry 会把结果区分为 passed、flaky 与 failed。Retry 是收集间歇失败证据和降低偶发基础设施噪声的手段，不是把 Flaky Test 视为健康。团队应跟踪 flaky，而不是只看最终退出码；风险较高的 CI 可以启用 failOnFlakyTests，让 Retry 后才通过的 Test 仍阻断 Build。Playwright Retries Playwright failOnFlakyTests

Sharding 用 --shard=1/4 等参数把 Suite 分到多个 Machine。fullyParallel: true 时可以按单个 Test 更均匀地分配；否则主要按 Test File 分配。多个 Shard 可以输出 Blob Report，下载后合并成统一 Report。Playwright Sharding

// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./tests/e2e",
  fullyParallel: true,
  forbidOnly: Boolean(process.env.CI),
  failOnFlakyTests: Boolean(process.env.CI),
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 2 : undefined,
  reporter: process.env.CI
    ? [["blob"], ["junit", { outputFile: "test-results/junit.xml" }]]
    : [["html", { open: "never" }]],
  use: {
    baseURL: "http://127.0.0.1:4173",
    trace: "on-first-retry",
    screenshot: "only-on-failure",
    video: "retain-on-failure",
  },
  projects: [
    {
      name: "chromium",
      use: { ...devices["Desktop Chrome"] },
    },
  ],
  webServer: {
    command: "pnpm preview --host 127.0.0.1 --port 4173",
    url: "http://127.0.0.1:4173",
    reuseExistingServer: !process.env.CI,
  },
});

官方 CI Guide 提供 GitHub Actions、Azure Pipelines、CircleCI 等配置，并推荐安装与 Playwright Version 匹配的 Browser Binary 和 System Dependency。CI 应固定 Package Lockfile、Browser Version、Operating System Image 与 Font；Visual Job 尤其不能让 Baseline Environment 漂移。Playwright CI

12. UI Mode、Codegen 与 Page Object Model#

UI Mode 提供 Watch、Filter、逐 Step Trace 与 Time-travel Debugging，适合本地开发和快速缩小 Failure；Codegen 会记录操作并优先生成 Role、Text、Test ID 等 Locator，适合得到第一版脚手架。Playwright UI Mode Playwright Codegen

Codegen 产物不是完成品。它不知道业务边界、哪些结果必须断言、哪些 Test Data 需要隔离，也可能记录冗余操作。Reviewer 应把录制结果重写成有明确 Intent 的 Test。

Page Object Model 可以集中常用 Locator 与 Page-level Operation，但不应把所有 Assertion 与业务 Flow 隐藏进一个巨大 Class。推荐：

• Page / Component Object 封装稳定的 UI Vocabulary 与低层操作。
• Fixture 封装 Resource Lifecycle 与 Test Data。
• Test File 保留 Scenario Intent、关键 Assertion 与 Acceptance ID。
• 重复只出现两次且仍在变化的 Flow，先保持显式，不急于抽象。

13. Component Testing#

Playwright 1.62 当前提供稳定的内置 Component Testing Workflow，使用 @playwright/test 的 mount() Fixture：Test 仍在 Node.js 中运行，Component 由项目自己的 Dev Server 通过 Story Gallery Page 在真实 Browser 中渲染。它没有专用 Component Runtime、Bundler Integration 或额外 Framework Package；这一方案替代旧的 @playwright/experimental-ct-react、@playwright/experimental-ct-vue 等 Package。Playwright Component Testing

Gallery 是 Application Code，由团队维护。它发现 *.story.* File，提供 window.mount() / window.unmount() Contract，并负责 Global CSS、Decorator、Provider 与 App-wide Setup。Playwright Test 通过 String Story ID Mount Scenario：

import { test, expect } from "@playwright/test";

test("expands details", async ({ mount }) => {
  const component = await mount("components/Expandable/Stateful");

  await component.getByRole("button", { name: "Show details" }).click();
  await expect(component.getByTestId("expanded")).toHaveValue("true");
});

适合采用这条路径的条件：

• 团队希望 Component Test 与 E2E 共用 Projects、Retry、Trace、Visual Comparison 和 Reporter。
• 已有或愿意维护 Story Gallery，并能把 Framework-specific State 放进 Story。
• Component Scenario 数量有限，或者 Runner 统一性比最短反馈时间更重要。

不一定优先采用的条件：

• 项目已经使用 Vite / Vitest，并有大量直接 Import Component 的 Test。
• Storybook 已经承担完整的 Component State Catalog、Interaction 与 Visual Review。
• 大量 Pure Logic、Hook、Reducer 和 Edge Case 需要更快的 Node Feedback。

官方 Component Testing 配置会用 reuseContext: true 换取速度，但 1.62 API Reference 仍把它标为 Discouraged、Experimental，并说明 Reset 只是 Best-effort。它不适合直接复制到普通 E2E Project，也不能当作 Fresh BrowserContext 的隔离保证。Playwright reuseContext API

不要同时用 Vitest Browser Mode 与 Playwright Component Testing 重写同一批 Scenario。选择一个主要 Component Runner，再把 Playwright 的重心保留给 Application Flow，通常更容易维护。

14. Playwright Test Agents#

Playwright 当前提供三个 Test Agents：Planner 探索 Application 并生成 Human-readable Markdown Plan，Generator 把 Plan 转成 Playwright Test，Healer 执行失败 Test、检查当前 UI、提出 Patch 并重跑。Agent Definition 可以通过 init-agents 生成，并应在 Playwright Upgrade 后重新生成。Playwright Test Agents

这是一条 Authoring Workflow，不是新的 Oracle。官方明确说明 Generated Test 可能包含初始错误；Healer 的输出可能是 Passing Test，也可能在判断 Product Functionality 已损坏时 Skip Test。因此 Agent 不能自行拥有以下权限：

• 删除或弱化关键 Assertion。
• 把 Failure 改成 .skip 后宣称任务完成。
• 自动批准所有 Screenshot / ARIA Baseline 更新。
• 放宽 Pixel Threshold、Timeout 或 Retry 来隐藏 Regression。
• 修改 Acceptance Criteria，让实现反过来定义需求。
• 用 Mock 替换真实 Integration，却不披露 Coverage Scope 已改变。

Agent 提交的 Playwright Test 至少应留下这条可审阅链路：

Requirement / Acceptance ID
  -> Human-readable Plan
  -> Playwright Test 与明确 Assertion
  -> CI Result
  -> Failure 时的 Trace / Screenshot / Video
  -> Baseline 或 Contract Change 的独立 Review

对 Regression Fix，还应验证新增 Test 在修复前确实失败、修复后才通过；否则 Agent 可能只为当前实现写了一个永远为 Green 的描述性 Test。

最小可复现 Smoke Test#

以下示例不依赖业务 Application，只验证 Playwright 安装、Browser Launch、Locator、Auto-waiting、Keyboard、Focus 与 Web-first Assertion 是否工作。示例按 @playwright/test 1.62.1 API 编写。

安装#

pnpm add -D @playwright/test@1.62.1
pnpm exec playwright install chromium

配置#

// playwright.config.ts
import { defineConfig } from "@playwright/test";

export default defineConfig({
  testDir: "./tests",
  reporter: [["html", { open: "never" }]],
  use: {
    trace: "on-first-retry",
  },
  projects: [
    {
      name: "chromium",
      use: { browserName: "chromium" },
    },
  ],
});

Test#

// tests/dialog.spec.ts
import { test, expect } from "@playwright/test";

test("AC-DIALOG-01: Escape closes the dialog and restores focus", async ({
  page,
}) => {
  await page.setContent(`
    <button id="open" type="button">Open settings</button>
    <dialog aria-label="Settings">
      <button id="close" type="button">Close</button>
    </dialog>
    <script>
      const openButton = document.querySelector("#open");
      const closeButton = document.querySelector("#close");
      const dialog = document.querySelector("dialog");

      openButton.addEventListener("click", () => dialog.showModal());
      closeButton.addEventListener("click", () => dialog.close());
      dialog.addEventListener("close", () => openButton.focus());
    </script>
  `);

  const trigger = page.getByRole("button", { name: "Open settings" });
  const dialog = page.getByRole("dialog", { name: "Settings" });

  await trigger.click();
  await expect(dialog).toBeVisible();
  await expect(page.getByRole("button", { name: "Close" })).toBeFocused();

  await page.keyboard.press("Escape");
  await expect(dialog).toBeHidden();
  await expect(trigger).toBeFocused();
});

执行#

pnpm exec playwright test
pnpm exec playwright test --ui
pnpm exec playwright show-report

这个 Test 只能证明 Native Dialog 的这段 Behavior 在已安装 Chromium 和当前环境中成立；它没有验证业务 Routing、Backend、Visual Baseline 或其他 Browser。扩大结论前，应明确增加对应 Project 和 Oracle。

Playwright、Vitest、jsdom、Testing Library 与 Storybook 横向比较#

它们不处于同一抽象层：Vitest 和 Playwright Test 是 Runner；jsdom 是 Node.js 中的 Web Platform Implementation；Testing Library 是 Query / Interaction Utility 与测试哲学；Storybook 是 Component State Catalog 与 Workshop，并可通过 Addon 接入 Runner。

Vitest Node 与 Playwright#

Vitest 复用 Vite Transformation、Alias 和 Plugin，提供 Mock、Fake Timer、Snapshot、Coverage 与 Type Testing，适合大量 Function、Module、Hook、Reducer、SDK 和 Node Service Test。Playwright 启动 Browser、Server 与 Context 的成本更高，但能验证 Navigation、Rendering、Browser Event、Network 与完整 Flow。Why Vitest

默认选择：能通过直接调用 Function 精确证明的 Rule 放 Vitest；需要真实 Page / Browser Boundary 才成立的事实放 Playwright。

jsdom 与 Playwright#

jsdom 是在 Node.js 中实现大量 Web Standard 的 Library，不是 Browser，也不是 Test Runner。它适合低成本构造 DOM、Render Component 与验证 Text、Role、Attribute、Form State。jsdom 官方明确把 Navigation 与 Layout 列为 Scope 之外，许多 Layout Property 只能返回零等 Dummy Behavior，因此不能用 jsdom Test 证明 CSS Geometry、真实 Scrolling、Popup 或 Page Navigation 正确。jsdom Unimplemented Web Platform

默认选择：不依赖真实 Layout / Browser API 的大量 Component Behavior 可以留在 jsdom；Focus、Event Propagation、CSS、Canvas、Browser API、Navigation 与 Cross-browser Risk 应进入 Vitest Browser Mode 或 Playwright。

Vitest Browser Mode 与 Playwright Test#

两者都运行真实 Browser，也都能做 Component、Visual 与 ARIA Test。主要差别是 Workflow：

• Vitest Browser Mode 延续 Vite / Vitest Module Graph、Watch、Mock 与靠近 Source 的 Component Test Experience。
• Playwright Test 以 Browser Automation、BrowserContext Isolation、Application Project Matrix、Retry、Trace 与 CI Artifact 为中心。

Vitest 官方推荐 Browser Mode 做 Component Testing，因为它能发现 Simulated DOM 遗漏的 CSS、Browser API、Event 与 Focus 问题；同时官方仍把 Browser Mode 描述为 Early Development，并建议用 Playwright 等 Standalone Browser-side Runner 补充 Critical Flow。Vitest Browser Mode Vitest Component Testing

Vitest Browser Mode 使用 Playwright Provider 时也能生成 Playwright trace.zip，并用 Playwright Trace Viewer 打开；因此 Trace 不是 Playwright Test 独占能力。差别在于 Runner、Test Code 所在 Context、Isolation Model、Fixture / Project Workflow 与 Artifact Integration，而不只是“有没有 Trace”。Vitest Trace View

默认选择：大量靠近 Component Source 的 Test 用 Vitest Browser Mode；跨 Page、Authentication、Popup、Download、Multi-user、部署 URL 与 Failure Trace 用 Playwright Test。

Testing Library 与 Playwright#

Testing Library 不是 Runner 或 Runtime。它提供从用户视角 Query DOM 的 Utility，并强调 Test 应尽量接近 Software 的真实使用方式。它可以运行在 Vitest + jsdom、Vitest Browser Mode、Storybook 等不同组合中。Playwright 自带 Locator 与 Web-first Assertions，通常不需要再把 DOM Testing Library Query 套到 Playwright Page 上。Testing Library Guiding Principles

两者共享的实践是优先 Role、Label、Accessible Name 与 User-observable Outcome；区别是 Playwright Locator 直接驱动真实 Browser，并带 Actionability 与 Auto-retry。

Storybook 与 Playwright#

Storybook 的核心价值是把 Component 的 Loading、Empty、Error、Disabled、Long Content、Theme、Locale 等状态命名为可浏览、可复用的 Story。它不是 Playwright E2E Runner 的同类替代品。当前 Storybook Vitest Addon 会把 Story 转成 Vitest Test，并默认通过 Playwright Chromium Provider 在 Browser Mode 运行；Visual Tests 则可接入 Chromatic。Storybook UI Testing Storybook Vitest Addon

默认选择：Storybook 管 Component State Catalog 和跨角色 Review；Playwright 管完整 Application Flow。Playwright Component Testing 也使用 Story Gallery 思想，但那是项目自行维护的 *.story.* Contract，不等于 Storybook Product 本身。

推荐的工程分层#

一个以 React / Vite 为例的默认组合可以是：

重点不是层数越多越好，而是每种 Risk 只在最小且足够真实的层首先被发现：

• Business Rule Failure 应先由 Vitest Unit Test 定位。
• Component State Failure 应先由 Component Test 定位。
• Browser / Navigation / Deployment Failure 应由 Playwright 定位。
• Visual Change 应输出 Diff 并经过批准。
• Consumer / Provider Incompatibility 应由真正的 Contract Verification 定位。

常见误区#

1. 把所有 Test 都升级为 E2E。结果通常是 Feedback 变慢、Failure Scope 变大，而 Pure Logic Coverage 反而下降。
2. 看到 Playwright 使用 WebKit，就宣称已经测试真实 Safari / iPhone。WebKit Build 和 Device Emulation 都有明确边界。
3. 使用 CSS Selector 和固定 Sleep 对抗 Flakiness。应优先 Locator、Actionability、Web-first Assertion 和确定的 System Signal。
4. 把 Retry 后通过当成健康。Playwright 会把它标记为 flaky，团队仍需调查。
5. 每个 Test 都从 UI Login 开始。应根据 Isolation 和 Server State 选择 Storage State、Setup Project 或 Per-worker Account。
6. Mock 所有 API 后宣称 E2E 通过。此时验证的是 Frontend + Mock，不是完整 Stack。
7. 用 Screenshot 替代 Behavior Assertion。Pixel Diff 无法精确证明 Callback、URL、Focus 或 Server Side Effect。
8. 随手执行 --update-snapshots。Baseline Update 是 Expected Behavior Change，应独立审阅。
9. 把 ARIA Snapshot 或 axe Scan 当成完整 Accessibility Conformance。
10. 让 Agent 同时修改 Product、Test、Baseline、Threshold 与 Requirement，并只审阅最终 Green Result。
11. 让 Test 依赖执行顺序。默认 Parallelism、Retry、Shard 与单 Test Debug 都会暴露这种隐式共享 State。
12. 不上传 Trace 和 Diff。远程 CI 只留下 Timeout Message 时，Playwright 最有价值的诊断能力没有被使用。

推荐的落地顺序#

1. 选择三到五条真正阻断业务的 Critical User Journey，不从追求页面数量开始。
2. 为每条 Flow 定义 Test Data、Role、Environment、成功结果和失败 Artifact。
3. 只启用 Chromium Primary Project，建立 Locator、Isolation 与 Fixture 规范。
4. CI 使用 trace: "on-first-retry"、Failure Screenshot、HTML / Blob Report，并确认 Artifact 在失败后可下载。
5. 把 Authentication State、Secret 和专用 Account 纳入安全管理；避免多个 Parallel Test 修改同一 Account。
6. 根据真实 User Distribution 与已知 Risk 增加 WebKit、Firefox、Mobile、Locale 或 Reduced Motion Project。
7. 只为稳定、高价值 Region 增加 Visual Baseline，并建立独立 Baseline Approval Workflow。
8. 对关键 Keyboard、Focus 和 Accessible Structure 增加明确 Assertion，再补充 axe 与 Manual Review。
9. Suite 变大后再启用 Fully Parallel、Shard 与 Blob Report Merge；先修复 Shared State，再扩 Worker。
10. Agent 可以生成 Plan 和 Test，但 Skip、Baseline、Threshold、Mock Boundary 与 Acceptance Criteria Change 必须独立 Review。

站内关联阅读#

• 前端 UI 测试全景：Vitest、Playwright、视觉回归与 Agent 契约：继续理解 UI Observation Surface、传统 Contract Testing 与 Agent Acceptance Evidence Chain。
• Vitest 使用指南：适用场景、核心能力与工程实践：查看 Unit、Mock、Coverage、Type Testing、Browser Mode 与 Test Projects。
• Matt Pocock Skills：从需求澄清到工程交付的 Agent 工作流：从 Specification、TDD 与 Review 理解 Agent 交付闭环。

官方资料#

• Playwright Installation
• Playwright Library
• Playwright Supported Languages
• Playwright Coding Agents CLI
• Playwright MCP
• Writing Tests
• Locators
• Auto-waiting
• Actions
• Isolation
• Fixtures
• Projects
• Browsers
• Emulation
• Chrome Extensions
• WebView2
• Electron API
• Android API
• Authentication
• Network
• API Testing
• Mock APIs
• Mock Browser APIs
• Pages and Popups
• Downloads
• Clock
• Screenshots
• Visual Comparisons
• ARIA Snapshots
• Accessibility Testing
• Trace Viewer
• Videos
• Reporters
• Retries
• Parallelism
• Sharding
• Continuous Integration
• UI Mode
• Test Generator
• Component Testing
• Playwright Test Agents
• Vitest Why Browser Mode
• Vitest Component Testing
• Vitest Trace View
• jsdom Unimplemented Parts of the Web Platform
• Testing Library Guiding Principles
• Testing Library Query Priority
• Storybook UI Testing
• Storybook Vitest Addon
• W3C WAI Evaluating Web Accessibility