---
url: https://open-wxa.github.io/testing.md
description: >-
  用 Playwright 给微信小程序写 E2E 测试：安装 @open-wxa/wxa-runner-playwright，打开页面、点击、断言页面
  data，mock 原生 API、拦截和断言 wx.request。
---

# 用 Playwright 写微信小程序 E2E 测试

用 [Playwright](https://playwright.dev/) 测小程序：打开页面、点击，检查页面上的文字、页面 `data` 和发出的请求。CI 里无头运行，不需要开发者工具。

## fixture 是什么

`@open-wxa/wxa-runner-playwright` 提供一个 `miniProgram` fixture，和 Playwright 自带的 `page` 一样，在每个用例开始前准备好、作为参数传进来。
它负责启动 wxa-runner、打开浏览器、等小程序启动，用例里只写要测的东西：

```ts
test('点击「详情」进入详情页', async ({ miniProgram }) => {
  await miniProgram.open('pages/index/index');
  await miniProgram.current.locator('#detail').click();
  await expect(miniProgram).toHavePath('pages/detail/detail');
});
```

不用 Playwright，或者不想多装一个包，可以直接调用浏览器里的[测试 API](./test-api.md)。

## 快速上手

**1. 安装**

```bash
pnpm add -D @playwright/test @open-wxa/wxa-runner-playwright
```

用例在本机的 Google Chrome 里运行，没装时运行 `npx playwright install chrome`。

**2. 新建 `playwright.config.ts`**

* 原生小程序：放在 `project.config.json` 所在目录
* uni-app、Taro 等框架：放在源码根目录，用 `wxaProject` 指向编译产物目录。跑测试前先构建出这个目录

```ts
// playwright.config.ts
import { defineConfig } from '@playwright/test';
import type { WxaOptions } from '@open-wxa/wxa-runner-playwright';

export default defineConfig<WxaOptions>({
  testDir: 'e2e',
  use: {
    channel: 'chrome',
    // uni-app、Taro：编译产物目录，相对这个配置文件
    // wxaProject: './dist/dev/mp-weixin',
    // setup 文件，相对这个配置文件
    // wxaServerOptions: { setup: './wxa.setup.ts' },
  }
});
```

**3. 写第一个用例**

```ts
// e2e/index.spec.ts
import { test, expect } from '@open-wxa/wxa-runner-playwright';

test('首页能打开', async ({ miniProgram }) => {
  await miniProgram.open();
  // 换成你的首页路径
  await expect(miniProgram).toHavePath('pages/index/index');
});
```

`test` 和 `expect` 要从 `@open-wxa/wxa-runner-playwright` 导入，不是 `@playwright/test`，否则没有 `miniProgram` 和 `toHavePath` 等断言。

**4. 运行**

```bash
npx playwright test            # 无头运行全部用例
npx playwright test --headed   # 打开浏览器窗口，看着它运行
npx playwright test --ui       # 图形界面，可以一步步回看
```

## 写用例

一个完整的例子：mock 登录、拦截下单接口，点击提交后检查跳转、页面 data 和发出的请求。各部分见后面几节。

```ts
import { test, expect } from '@open-wxa/wxa-runner-playwright';

test('提交订单后跳转到结果页', async ({ miniProgram }) => {
  // 打开页面前声明，App.onLaunch 里就生效
  await miniProgram.mock('login', { code: 'test_code' });
  await miniProgram.route('POST **/api/orders', {
    status: 201,
    body: { id: 'o-1' }
  });
  await miniProgram.open('pages/cart/cart');

  // current 是当前页，跳转后自动指向新页面
  await miniProgram.current.locator('#submit').click();

  // 跳转需要时间，这两个断言会自动重试，不用手动等待
  await expect(miniProgram).toHavePath('pages/result/result');
  await expect(miniProgram).toHavePageData({ orderId: 'o-1' });

  const req = await miniProgram.waitForRequest(
    'POST **/api/orders'
  );
  expect(req.body).toEqual({ skuId: 1, count: 2 });
});
```

### 打开页面

| 写法 | 作用 |
| --- | --- |
| `await miniProgram.open()` | 打开首页 |
| `await miniProgram.open('pages/detail/detail?id=1')` | 打开指定页面，`?` 后面是页面参数 |

* 页面不在 `app.json` 里时直接报错，不会停在首页上继续执行
* 同一个用例里再次 `open()` 会整页重新加载，之前的 `mock`、`route` 仍然生效

### 操作页面

`miniProgram.current` 是当前页，用法和 Playwright 的 `page.frameLocator()` 一样，跳转后自动指向新页面：

```ts
const page = miniProgram.current;
await page.locator('#add').click();
await page.getByText('去结算').click();
await expect(page.locator('#count')).toHaveText('1');
```

### 断言

除了 Playwright 自带的断言，还能断言小程序的状态，不满足时自动重试到超时：

| 写法 | 检查 |
| --- | --- |
| `expect(miniProgram).toHavePath('pages/result/result')` | 当前页是这个页面 |
| `expect(miniProgram).toHavePageData({ status: 'ok' })` | 当前页的 `data` 包含这些字段和值，没列出的字段不比较 |
| `expect(miniProgram).toHavePageData(data, { path })` | 页面栈里指定页面的 `data` |

别忘了 `await`。两者都可以加 `.not`，也可以传 `{ timeout }` 改超时时间（毫秒）。

### mock 原生 API、拦截请求

在 `open()` 之前调用，`App.onLaunch` 里就生效；之后调用，从下一次调用开始生效：

```ts
await miniProgram.mock('getLocation', {
  latitude: 31.23,
  longitude: 121.47
});
await miniProgram.route('GET **/api/feed', {
  body: { list: [] }
});
await miniProgram.open();
```

* 写法和 setup 的 [`mock`](./setup.md#mock)、[`network.routes`](./setup.md#network) 一样，会覆盖 setup 里的同名配置
* `unmock(api?)`、`unroute(pattern?)` 撤销，不传参数时撤销全部，包括 setup 里声明的

也可以传函数，按调用参数或请求内容返回结果。函数在 Node 里执行，能用用例里的变量，也能写断言：

```ts
await miniProgram.route('POST **/api/orders', request => {
  expect(request.body).toEqual({ skuId: 1, count: 2 });
  return { status: 201, body: { id: 'o-1' } };
});
```

函数里的断言失败时，这次调用失败，用例结束时也会失败，不会被忽略。

* 函数的结果是异步返回的。基础库同步调用的 API 只能传对象：以 `Sync` 结尾的，以及 `getSystemInfo`、`getMenuButtonBoundingClientRect`（`wx.getWindowInfo` 等都经过 `getSystemInfo`）
* 参数和返回值要能序列化。`route` 的函数拿到的 `request.body` 已经按 Content-Type 解析好（JSON、表单）

### 检查发出的请求

```ts
await miniProgram.clearRequests();
await miniProgram.current.locator('#save').click();

const req = await miniProgram.waitForRequest(
  'POST **/api/profile'
);
expect(req.body).toEqual({ name: '张三' });
```

* `waitForRequest(pattern)`：等到发出匹配的请求，返回最近的一个。之前发出的也算，所以只关心某个操作之后的请求时，操作前先 `clearRequests()`
* `requests(pattern?)`：已发出的全部请求，按发出顺序，被拦截的和真正发出的都有，只保留最近 1000 个
* 规则写法同 `route`

每个请求有：

| 字段 | 说明 |
| --- | --- |
| `method` | 大写，如 `POST` |
| `url` | 完整地址 |
| `header` | 请求头 |
| `body` | 按 Content-Type 解析好的请求体：JSON 是对象，表单是 `{ 字段: 值 }` |
| `data` | 没解析的原始请求体 |
| `routedBy` | 拦截它的规则；没被拦截、真正发出去的为 `null` |

### 读取状态、直接跳转

| 写法 | 作用 |
| --- | --- |
| `pageData(path?)` | 页面的 `data`。不传时读当前页 |
| `currentPage()` / `pageStack()` | 当前页 / 整个页面栈，每页有 `path`、`query` |
| `webViews()` / `webView()` | 当前页的 web-view / 新窗口模式下 web-view 打开的网页窗口，见 [web-view 里的网页](#web-view-里的网页) |
| `waitForPage(path)` | 等到这个页面成为当前页 |
| `callPageMethod(name, ...args)` | 调用当前页的方法，返回方法的返回值 |
| `navigateTo(url)`、`navigateBack()`、`redirectTo(url)`、`reLaunch(url)`、`switchTab(url)` | 直接跳转，同 `wx` 上的同名 API |
| `getStorage(key)` / `clearStorage()` | 读取 / 清空小程序的存储 |

都是 async 的，要 `await`。每个成员在编辑器里悬停都能看到详细说明。

### 选择图片

`wx.chooseImage`、`wx.chooseMedia` 打开浏览器的文件选择框，用 Playwright 的 `filechooser` 事件直接给文件，不弹系统窗口。
相册和拍摄都可选时（默认），和真机一样先弹出「拍摄 / 从手机相册选择」菜单，要先点菜单项：

```ts
test('上传头像', async ({ miniProgram, page }) => {
  await miniProgram.open('pages/profile/profile');
  await miniProgram.current.locator('#avatar').click();

  const [chooser] = await Promise.all([
    page.waitForEvent('filechooser'),
    page.getByRole('button', { name: '从手机相册选择' }).click()
  ]);
  await chooser.setFiles('fixtures/avatar.png');
});
```

* 菜单、图片预览这些弹层在 `page` 上，不在 `miniProgram.current` 里。预览层用 `page.getByRole('dialog', { name: '图片预览' })` 找到
* `chooser.setFiles([])` 等于用户关掉选择框，页面收到 `cancel`

### web-view 里的网页

默认模式下，web-view 的网页是当前页里的 iframe：

```ts
const h5 = miniProgram.current.frameLocator('iframe');
await expect(h5.locator('h1')).toHaveText('活动详情');
```

网页和模拟器（localhost）不是同一个站点时，网页的 Cookie 多半不生效（原因见 [web-view 的 Cookie](./features.md#web-view-的-cookie)）。
需要登录态等 Cookie 时开启新窗口模式，网页在新窗口里打开，用 `miniProgram.webView()` 拿到这个窗口（Playwright 的 `Page`）。
Cookie 用 Playwright 自带的 `context.addCookies` 注入：

```ts
test.use({ wxaWebView: 'window' });

test('H5 登录后显示用户名', async ({ miniProgram, context }) => {
  await context.addCookies([{ name: 'session', value: 'x', url: 'https://h5.example.com', sameSite: 'Lax' }]);
  await miniProgram.open('pages/webview/webview?src=' + encodeURIComponent('https://h5.example.com/user'));

  const h5 = await miniProgram.webView();
  await expect(h5.locator('#user')).toHaveText('张三');
});
```

* `webView()` 等当前页的网页窗口打开后返回，默认超时 10 秒。当前页有多个 web-view 时用 `webView({ index })` 指定
* 跳到下一页时窗口关闭，返回后重新打开，要再调用一次 `webView()` 拿新窗口。网页设置了 `Cross-Origin-Opener-Policy` 时，`src` 改变也会换成新窗口
* 新窗口模式不触发 `bindload`，其他和微信的差异见 [web-view 的 Cookie](./features.md#web-view-的-cookie)
* 弹出窗口靠 Playwright 默认的 `--disable-popup-blocking` 参数，不要在 `ignoreDefaultArgs` 里去掉它

### 检查运行时错误

每个用例结束时，fixture 检查小程序有没有出错，有就让用例失败：

* 逻辑层、渲染层的运行时错误，包括被基础库捕获、只打印到控制台的（生命周期、事件处理函数、wx API 回调里抛出的）
* 调用了还没实现的 `wx` API。它们返回成功以免打断业务代码，测试里要 mock 掉

`miniProgram.errors()` 能看到具体内容。有意触发错误的用例，用 `test.use({ wxaCheckErrors: false })` 关掉检查。

## 配置项

在 `playwright.config.ts` 的 `use` 里设置：

| 选项 | 默认值 | 作用 |
| --- | --- | --- |
| `wxaProject` | `'.'` | 小程序目录，相对配置文件 |
| `wxaServerOptions` | `{}` | 开发服务器的其他参数，如 `setup`、`baseLibVersion`、`devtoolsLogin`。路径相对配置文件 |
| `wxaCheckErrors` | `true` | 用例结束时[检查运行时错误](#检查运行时错误) |
| `wxaWebView` | `'iframe'` | web-view 的网页嵌在页面里（`'iframe'`），还是在新窗口打开（`'window'`），见 [web-view 里的网页](#web-view-里的网页) |

* 每个 worker（Playwright 并行运行用例的进程）启动一个开发服务器，小程序只编译一次；每个用例用新的浏览器上下文，Storage、文件和页面栈互不影响
* 测试时不监听文件变化、不热更新，运行环境和真机一致
* `wxaProject`、`wxaServerOptions` 只能写在配置文件或用例文件顶层的 `test.use` 里，不能写在 `describe` 里
* 启动 Chrome 时默认加上 V8 参数 `--js-flags=--no-enable-lazy-source-positions`，打开页面快约 1/3（见下方说明）。`launchOptions.args` 里已有 `--js-flags` 时合并进去；
  已经指定了 `lazy-source-positions` 相关参数时按你的来。用例文件里的 `test.use({ launchOptions })` 会整个替换 fixture 的设置，不再加这个参数，要改启动参数请写在配置文件里

V8 编译函数时默认不记源码位置，需要时再重新解析函数补上。Playwright 连着浏览器时 V8 要给每个函数补，
基础库是几 MB 的压缩文件，外层几个函数几乎就是整个文件，每补一个都要重新解析几十毫秒：WAService.js 初始化从约 110ms 变成约 350ms。
编译时就记下源码位置能省掉这一步；不连着浏览器时这个参数不影响速度。

存在开发服务器的内存里，按浏览器会话隔离，会话标识存在 localStorage 里：同一个上下文里的页面和刷新共用这些文件，新的上下文是独立的目录。
关掉浏览器上下文时服务器上的文件不会马上清理，开发服务器关闭时全部释放，重启后不保留。
文件接口的同步、异步和真机一致：只有 `Sync` 结尾的接口用同步 XHR，其他都是异步请求。

## 注意事项

* **跳转后的选择器**：新旧页面有同一个选择器时，先 `await expect(miniProgram).toHavePath(...)` 等跳转完成，免得断言落在上一个页面上
* **text 组件的文字**：基础库 3.3.x 及更早的版本里，`textContent`（`toHaveText` 默认用它）会把 text 组件的文字读两遍，改用 `toHaveText(text, { useInnerText: true })` 或 `innerText()`
