小程序 E2E 测试绕不开开发者工具？有人把官方基础库搬进了浏览器

wxa-runner：在浏览器里运行微信小程序

微信小程序的自动化测试有个绕不开的依赖：微信开发者工具。官方的 miniprogram-automator 靠它驱动模拟器，而开发者工具只有 Windows 和 macOS 版，想让 E2E 进流水线，就得专门养一台装好工具的测试机，Linux CI 无能为力。10 月 13 日创建的开源项目 wxa-runner（MIT 协议）换了个思路：把微信官方基础库直接搬进浏览器，小程序在普通 Chrome 里运行，Playwright 无头测试、GitHub Actions 上的 Linux 环境都不再需要开发者工具。短短 10 天，这个项目收了 499 个 star。

原理：跑的是官方基础库，不是编译成 H5

wxa-runner 文档站

wxa-runner 运行的是小程序的编译产物：原生小程序直接跑 project.config.json 所在目录，uni-app、Taro 项目跑 dist/dev/mp-weixin 这类产物目录。渲染、组件、生命周期全部由微信官方基础库驱动。这套基础库被单独拆成 wxa-baselib 仓库，版权仍归腾讯，MIT 协议只覆盖 wxa-runner 自身代码。

这一点和"编译成 H5 再测"有本质区别：uni-app、Taro 编 H5 时运行的是框架为浏览器重新实现的组件和 API，setData、WXSS、自定义组件相关的问题可能测不出来，原生小程序更没有 H5 版本；wxa-runner 跑的 mp-weixin 产物和线上小程序是同一份代码。浏览器里默认渲染一台 iPhone X，导航栏、tabBar、toast 这些界面由 wxa-runner 自己实现，和真机可能存在差异。

一行命令跑起来，DevTools 直接调试

bash

# 原生小程序
npx wxa-runner dev . --open

# uni-app：终端 1 跑监听构建，终端 2 指向产物目录
npm run dev:mp-weixin
npx wxa-runner dev ./dist/dev/mp-weixin

浏览器打开 http://localhost:3000 就是一台模拟手机。按 F12 打开 Chrome DevTools：每个 JS 文件单独加载，行号和源文件一致；基础库代码进了 DevTools 忽略列表，断点和调用栈都停在业务代码上；wx.request 由开发服务器转发，Network 面板里能直接看。改了 WXSS、WXML 和页面 JS 后热更新，data 和页面栈都保留。

setup 预置登录态，测试不再卡在登录页

自动化测试最烦的往往是登录。wxa-runner 的 setup 文件在 App.onLaunch 之前执行，预置 Storage、替换原生 API、按 URL 拦截请求，不用改业务代码：

// wxa.setup.ts
export default defineSetup({
  storage: { token: 'test-token' },
  network: {
    routes: {
      'POST **/api/auth/login': {
        body: { code: 200, data: { token: 'test-token' } }
      }
    }
  }
});

需要真实 wx.login code 的场景，加 --devtools-login 可以借本机开发者工具的登录态。

Playwright 无头 E2E，GitHub Actions 直接跑

用 Playwright 测试微信小程序

测试用 Playwright 写。@open-wxa/wxa-runner-playwright 提供 miniProgram fixture，locator、断言、录屏、trace 这些 Playwright 能力都能用：

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

CI 是这个项目最大的价值点。没有开发者工具时，wxa-runner 用内置基础库 3.7.0 和官方 npm 包 miniprogram-compiler 里的编译器，GitHub Actions 的 ubuntu-latest 自带 Chrome，npm ci 之后直接 npx playwright test，项目自己的测试套件也是这么跑的。

和官方 miniprogram-automator 相比：后者控制开发者工具或真机，能测真机和插件，但必须有装了工具的 Windows/macOS 机器；wxa-runner 胜在 Linux 无头和 Playwright 生态。文档建议的组合是：日常提交在 Linux CI 用 wxa-runner 跑，发版前用 automator 在真机回归。

边界：发布流程仍然归开发者工具

wxa-runner 不做预览、上传和真机调试；基础库 3.7.1 起要手动 --baselib 指定；蓝牙等设备能力、插件的自定义组件还没支持；真实项目只验证过 uni-app（Vue 3），Taro 产物理论上能跑但还没经过实战检验。未实现的原生 API 会返回成功以免打断业务代码，测试里会把它们报出来。项目还在 0.x 阶段，README 致谢里点名了前辈 WEPT。

对维护小程序又想让测试进 CI 的团队，这是个值得盯着的选项，只是先别急着卸载开发者工具，发版那一步还离不开它。