wxa-runner 是一个社区维护的微信小程序调试与测试工具:把原生小程序,或者 uni-app、Taro 编译出的微信小程序产物交给它,就能在 Chrome 里运行,用 Chrome DevTools 调试,再用 Playwright 写自动化测试。它复用微信官方基础库,运行的是小程序代码,因而适合检查 WXML、WXSS、组件和页面状态这条链路。预览上传、真机调试及设备能力验证,仍由微信开发者工具和真机承担。

浏览器里跑的是哪份代码
把 uni-app 或 Taro 编译成 H5 后测试,运行的是框架为网页实现的组件与 API。wxa-runner 接收的则是 mp-weixin 小程序产物,由微信基础库处理渲染、组件、setData 和生命周期。要测试小程序这条运行链路,就需要选择对应的小程序目录:
| 项目 | 交给 wxa-runner 的目录 |
|---|---|
| 原生小程序 | project.config.json 所在目录 |
| uni-app CLI 项目 | 微信小程序编译产物,开发模式常见为 dist/dev/mp-weixin |
| HBuilderX 项目 | 通常为 unpackage/dist/dev/mp-weixin |
| Taro 等框架 | 先完成微信小程序编译,再指向对应产物目录 |
导航栏、弹窗和部分原生 API 由 wxa-runner 自己实现,因此使用官方基础库也不代表所有行为都和微信客户端完全一致。项目主要验证路径包括原生小程序与 uni-app;v0.13.1 发布说明还记录了 Taro 3.4.3 真实项目的修复验证,这个具体案例不能扩展成全部 Taro 版本都已兼容。

先在 Chrome 打开项目
命令行包声明的最低要求是 Node.js 18。若准备接入下面的 Playwright 流程,按当前 Playwright 的支持范围准备最新版 Node.js 22.x、24.x 或 26.x,并安装 Google Chrome。这里的 Node 要求和小程序本身的微信基础库版本是两回事。
原生小程序在 project.config.json 所在目录运行:
npx wxa-runner dev . --open
uni-app 项目先启动微信小程序的监听编译,再用另一个终端运行产物:
# 终端 1:生成并持续更新小程序产物
npm run dev:mp-weixin
# 终端 2:运行上一步的产物目录
npx wxa-runner dev ./dist/dev/mp-weixin --open
默认地址是 http://localhost:3000。浏览器应显示模拟手机及项目页面;如果自己设置了端口,以终端输出的地址为准。要直接定位页面,可使用 /?path=pages/detail/detail&id=1,路径需要换成项目中真实存在的页面。
打开 Chrome DevTools 后,可以在 Sources 找业务文件断点,在 Network 查看请求。想在控制台调用 getCurrentPages() 或 wx.xxx,要先把执行上下文从 top 切到 wxa-appservice。页面本身使用 iframe,查看元素时也要分清所在层级。
接上一条 Playwright 测试
项目的 Playwright 包提供 miniProgram fixture,负责启动服务、打开浏览器并等待小程序就绪。下面按官方文档整理最小流程,以已安装 pnpm 的原生小程序项目为例。
pnpm add -D @playwright/test @open-wxa/wxa-runner-playwright
# 本机没有 Google Chrome 时再安装
npx playwright install chrome
在项目根目录新建 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',
wxaProject: '.'
}
});
如果是 uni-app 或 Taro,配置文件放在源码项目根目录,把 wxaProject 改成实际编译产物目录;跑测试之前先完成编译。然后新建 e2e/index.spec.ts:
import { test, expect } from '@open-wxa/wxa-runner-playwright';
test('首页能打开', async ({ miniProgram }) => {
await miniProgram.open();
// 改成 app.json 中自己的首页路径
await expect(miniProgram).toHavePath('pages/index/index');
});
这里的 test、expect 必须从 @open-wxa/wxa-runner-playwright 导入,才能使用 miniProgram 和它扩展的断言。运行:
npx playwright test --headed
预期结果是 Chrome 打开项目首页,页面路径与断言一致,用例通过。之后可以用 miniProgram.current.locator(...) 点击当前页元素,用 toHavePageData 检查页面数据,或核对提交给接口的请求体。移除 --headed 就是无头运行。
登录和请求要模拟得准确
浏览器里的 wx.login 默认返回模拟 code,真实后端不会认可;支付默认失败,定位等接口也有预设结果。测试登录后的页面时,通常要预置测试状态,或者拦截换取登录态的接口。否则页面能打开,却未必走到想测试的业务分支。
可以在启动前执行的 wxa.setup.ts 里声明配置,也可以在用例的 open() 之前调用 miniProgram.mock()、miniProgram.route()。例如,下面只表示一个“应用启动时检查本地 token”的测试场景:
// wxa.setup.ts
import { defineSetup } from '@open-wxa/wxa-runner-core/setup';
export default defineSetup({
storage: { token: 'test-token' }
});
如果应用每次启动都会请求后端验证 token,仅预置这一项还不够,需要按自己的接口结构配置请求拦截。没有匹配到的请求仍会真实发出;测试时应连接测试环境,避免把测试动作送到生产服务。setup 内容和 WXA_ 环境变量还会传到浏览器,里面只放测试用状态,不能把它当作保管服务器密钥的地方。
需要真实登录 code、手机号或插件页面时,项目另有 --devtools-login 路线,要借用本机开发者工具。v0.13.0 已用这个参数替换旧的 --real-login,照旧示例操作时要留意版本。
CI 和真机的边界
wxa-runner 可以在 Linux 上无头跑测试,省去维护一台常驻微信开发者工具机器的部分工作。但当前“不安装开发者工具”的编译器方案只支持 x86-64,不能直接套到 ARM 机器。官方 CI 使用内置的基础库 3.7.0,编译器也有单页节点数等差异。
本地装有开发者工具时,可能使用不同版本的基础库。排查“本地过、CI 不过”,可以先在 Linux 或 macOS 终端用相同基础库运行:
WXA_BASELIB=3.7.0 npx playwright test
uni-app 在 CI 里执行 build:mp-weixin 后,常见产物路径是 dist/build/mp-weixin;wxaProject 也要对应改过来,不能继续指向本机开发模式的目录。
选型时,下面几项会直接影响测试能覆盖到哪里:
- 未实现的 wx API:为避免中断业务,部分调用会先返回成功并输出警告;Playwright fixture 默认在用例结束时收集这些运行错误,使测试失败。自行关闭错误检查,会失去这道提示。
- 设备与云能力:蓝牙等设备能力不支持;云开发的
callFunction、数据库等调用会失败,不能用浏览器里的页面结果判断这些链路正常。 - 插件:当前支持借用登录态运行插件页面,插件自定义组件与
requirePlugin仍不支持。 - 发布流程:预览、上传和真机调试仍在微信开发者工具中完成,发版前还要验证真实端行为。
日常提交可以用浏览器测试检查页面交互、状态和请求,设备能力及发布前回归继续放在开发者工具和真机上。本文按文档整理了上手路径,未安装运行该工具或执行示例测试。
版本、许可与文档
本文于 2026-11-15 核对的正式版为 v0.13.1,发布于 2026-11-12,修复了鼠标拖动滚动等问题。它仍是 0.x 阶段的社区项目,接入长期测试流程时,适合通过项目依赖和锁文件管理版本。
wxa-runner 自身采用 MIT 许可;随项目使用的微信官方基础库 wxa-baselib 版权归腾讯所有,不适用项目的 MIT 协议。评估分发和集成时,要把两者分开看。
- 仓库:open-wxa/wxa-runner。
- 发布记录:wxa-runner Releases。
- 快速开始:https://open-wxa.github.io/wxa-runner/getting-started 。
- 测试与 setup:https://open-wxa.github.io/wxa-runner/testing 、https://open-wxa.github.io/wxa-runner/setup 。
- CI 与功能限制:https://open-wxa.github.io/wxa-runner/ci 、https://open-wxa.github.io/wxa-runner/features 。
- 在线预览:https://wxa-viewer.picfinder.workers.dev ;Playwright 环境要求:https://playwright.dev/docs/intro 。