Playwright 组件测试迁移指南：从 Testing Library 切换到 mount 组件测试模型

2026-09-06 17:06:02作者：范靓好Udolf

本文基于 Playwright 官方文档 Migrating from Testing Library，讲解如何将基于 DOM Testing Library、React Testing Library 或 Vue Testing Library 编写的组件测试，迁移到 Playwright Test 内置的组件测试模型（story + gallery + mount fixture）。读完本文，你将掌握完整的 API 对照表、逐行迁移方法，并能结合源码理解 mount() 在底层是如何通过一个 #root Locator 驱动真实浏览器渲染的。

一、迁移的总体思路

原 Testing Library 的写法是在测试里直接调用 render() 内联地把组件挂载到测试环境；Playwright 则把这份"设置"抽离到一个 story（一个把组件嵌入特定场景的小包装器），由你自己的 dev server 以 gallery（组件库页面）的形式对外提供，测试中只用 id 引用它。gallery 的完整搭建方法见组件测试指南。

需要注意的一个边界情况：如果你是在浏览器中使用 DOM Testing Library（例如用 webpack 打包端到端测试），可以直接切换到 Playwright Test——原文档中的示例聚焦组件测试，但做端到端测试时，只需把 await mount(...) 换成 await page.goto('http://localhost:3000/') 打开被测页面即可。

二、API 对照速查表（Cheat Sheet）

下面是原文档给出的完整对照表，迁移时可直接照此替换：

Testing Library	Playwright
`screen`	`page` 与 `component`（Locator）
queries（`getBy...` / `findBy...`）	locators
async helpers（`waitFor` 等）	assertions
user events（`@testing-library/user-event`）	Locator 的 actions
`await user.click(screen.getByText('Click me'))`	`await component.getByText('Click me').click()`
`await user.click(await screen.findByText('Click me'))`	`await component.getByText('Click me').click()`
`await user.type(screen.getByLabelText('Password'), 'secret')`	`await component.getByLabel('Password').fill('secret')`
`expect(screen.getByLabelText('Password')).toHaveValue('secret')`	`await expect(component.getByLabel('Password')).toHaveValue('secret')`
`screen.getByRole('button', { pressed: true })`	`component.getByRole('button', { pressed: true })`
`screen.getByLabelText('...')`	`component.getByLabel('...')`
`screen.queryByPlaceholderText('...')`	`component.getByPlaceholder('...')`
`screen.findByText('...')`	`component.getByText('...')`
`screen.getByTestId('...')`	`component.getByTestId('...')`
`render(<Component />);`	一个 story 导出 + `await mount('Component/Default');`
`const { unmount } = render(<Component />);`	`const component = await mount('...'); await component.unmount();`
`const { rerender } = render(<Component />);`	`const component = await mount('...'); await component.update(props);`

三、完整示例：逐行迁移一个登录测试

Testing Library 原版：

import React from 'react';
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

test('sign in', async () => {
  // Setup the page.
  const user = userEvent.setup();
  render(<SignInPage />);

  // Perform actions.
  await user.type(screen.getByLabelText('Username'), 'John');
  await user.type(screen.getByLabelText('Password'), 'secret');
  await user.click(screen.getByRole('button', { name: 'Sign in' }));

  // Verify signed in state by waiting until "Welcome" message appears.
  expect(await screen.findByText('Welcome, John')).toBeInTheDocument();
});

逐行迁移后，场景先从测试搬进组件旁边的 story 文件：

import { SignInPage } from './SignInPage';

export const Default = () => <SignInPage />; // 1

然后测试按 id 挂载这个 story：

const { test, expect } = require('@playwright/test'); // 2

test('sign in', async ({ mount }) => { // 3
  // Setup the page.
  const component = await mount('pages/SignInPage/Default'); // 4

  // Perform actions.
  await component.getByLabel('Username').fill('John'); // 5
  await component.getByLabel('Password').fill('secret');
  await component.getByRole('button', { name: 'Sign in' }).click();

  // Verify signed in state by waiting until "Welcome" message appears.
  await expect(component.getByText('Welcome, John')).toBeVisible(); // 6
});

迁移要点（对应代码中的内联注释）：

注释 1：过去 render() 在测试里内联设置的一切——props、providers、mock 数据——都变成 story 的导出。story 运行在浏览器里，因此活的 JS 对象（回调、实例）不再需要跨越 Node.js/浏览器边界进入测试。
注释 2：组件测试和端到端测试都统一从 @playwright/test 导入。
注释 3：测试函数拿到 page（与其他测试隔离）和 mount（在该 page 中渲染 story）两个 fixtures。它们是 Playwright Test fixtures 体系的一部分。
注释 4：render 被 mount fixture 替代，它接收 story id，返回一个作用域限定在 gallery 根元素上的 component locator。
注释 5：用 Locator.locator / Page.locator 创建的 Locator 完成绝大多数交互操作。
注释 6：用 assertions 验证状态。

四、查询（Queries）如何迁移

Testing Library 的 getBy...、findBy...、queryBy... 及其多元素版本（getAllBy...）统一替换为 component.getBy... Locator。由于 Locator 始终自动等待并在必要时重试，你不必再纠结该选 getBy、findBy 还是 queryBy 哪个方法——findByText 的"等待出现"语义已由自动等待覆盖。

当你需要做列表操作（例如断言一列文本），Playwright 会自动执行多元素操作，详见 Locators 的 Lists 章节。

五、用断言替换 `waitFor`

Playwright 的断言会自动等待条件成立，因此通常不需要显式的 waitFor / waitForElementToBeRemoved 调用：

// Testing Library
await waitFor(() => {
  expect(getByText('the lion king')).toBeInTheDocument();
});
await waitForElementToBeRemoved(() => queryByText('the mummy'));

// Playwright
await expect(page.getByText('the lion king')).toBeVisible();
await expect(page.getByText('the mummy')).toBeHidden();

如果找不到合适的断言，使用 expect.poll 替代：

await expect.poll(async () => {
  const response = await page.request.get('https://api.example.com');
  return response.status();
}).toBe(200);

六、用嵌套 Locator 替换 `within`

可以用 Locator.locator 方法在一个 Locator 内部再创建 Locator，作用即等价于 within：

// Testing Library
const messages = screen.getByTestId('messages');
const helloMessage = within(messages).getByText('hello');

// Playwright
const messages = component.getByTestId('messages');
const helloMessage = messages.getByText('hello');

七、源码视角：`mount` fixture 到底做了什么

原文档强调 mount 接收 story id 并返回"作用域限定在 gallery 根上的 component locator"。这一点可以在仓库源码中得到印证：mount fixture 的完整实现位于 packages/playwright/src/index.ts。从源码结构看，其行为可以拆解为四步：

强制要求 baseURL：若配置中没有设置 baseURL，mount() 会直接抛出 mount() requires baseURL to point at the component gallery. Set it in your Playwright config.——这解释了为什么组件测试项目的配置里 baseURL 必须指向 gallery 页面（见组件测试指南的配置示例）。
导航到 gallery：await page.goto(baseURL)，然后 page.evaluate 调用页面暴露的 window.mount({ story: storyId, props })；如果 gallery 页面没有定义 window.mount()，也会抛出明确的错误。
返回作用域 Locator：mount 返回的是 page.locator('#root') 上附加了额外方法的对象——这就是"component locator 限定在 gallery 根"的实现本体，测试中的所有查询都从 #root 向下作用域。
附加 update 与 unmount：
- update(newProps) 再次以新 props 调用 window.mount（不重新导航）；从源码注释看，若 gallery 复用了渲染根节点，框架会做 reconcile，组件状态得以保留——这正是对照表中 rerender 的替代方案。
- unmount() 则调用 window.unmount?.()。

此外源码中还有一个值得注意的细节：调用 window.mount 时使用了 { exposeFunctions: true } 选项，意味着传入的 props 中如果包含函数，会被转换为真正可在浏览器内调用、并回调到测试进程的函数。

配套的 gallery 规范（window.mount / window.unmount 契约、#root 挂载点、根节点复用等）在仓库中以 agent skill 的形式提供，位于 playwright-component-testing skill，其中还附有 React 实现参考、Vue 实现参考和实验包迁移参考。