大家好本文将围绕微信小程序 E2E 测试这个老大难问题展开。做过小程序自动化测试的同学都知道官方的 miniprogram-automator 要靠一台装了微信开发者工具的 Windows/macOS 机器才能跑Linux CI 上根本装不了开发者工具而把 uni-app、Taro 项目编译成 H5 再测测的又不是小程序真实运行的那套代码。本文介绍一个 2026 年值得关注的开源项目 wxa-runner231 starMIT 协议它在普通浏览器里用微信官方基础库直接运行小程序编译产物用 Playwright 写无头 E2E 测试Linux CI 上不装开发者工具也能跑。从一行命令启动、跳过登录、mock 原生 API到写第一个测试用例、接入 GitHub Actions一篇讲全。无论你是刚接触小程序测试的新手还是正在搭 CI 流水线的工程师希望都能有所收获。本文目录小程序 E2E 测试为什么这么难wxa-runner 是什么在浏览器里跑微信官方基础库5 分钟上手一行命令跑起来用 Chrome DevTools 调试打断点、看请求、看页面结构启动前准备setup跳过登录、mock 原生 API、拦截 wx.request用 Playwright 写 E2E 测试在 GitHub Actions 的 Linux CI 上无头运行和官方 miniprogram-automator 怎么选功能与限制上车前必看的避坑清单总结一、小程序 E2E 测试为什么这么难先把痛点摆出来看看现在的方案各自卡在哪方案 1官方 miniprogram-automator。微信官方的自动化 SDK用 Node.js 脚本控制开发者工具的模拟器或真机。问题很明显依赖开发者工具而开发者工具只有 Windows、macOS 版Linux 服务器上装不了GitHub Actions 等主流 CI 环境直接出局还得在工具的安全设置里手动打开「CLI/HTTP 调用」测试机环境维护成本高mock 网络请求只能用mockWxMethod整个替换wx.request做不到按 URL 拦截、断言请求体。方案 2编译成 H5 再测。uni-app、Taro 都能编译出 H5 版本用 Playwright 直接测。但这时的组件和 API 是框架为 H5重新实现的一套代码和小程序里跑的不是同一份setData、WXSS、自定义组件相关的问题可能测不出来原生小程序项目更是连 H5 版本都没有。方案 3手动点。每次发版前人工回归一遍核心链路累且不可持续。三个方案共同的缺口是要一套既贴近真机运行环境、又能在 Linux CI 上无头跑的 E2E 方案。wxa-runner 补的就是这个缺口。二、wxa-runner 是什么在浏览器里跑微信官方基础库wxa-runner 是 open-wxa 组织下的开源项目一句话概括在普通浏览器里用微信官方基础库运行小程序为本地调试和 E2E 自动化测试而生。它的原理是把微信官方基础库wxa-baselib和官方编译器内置进项目直接运行小程序的编译产物——原生小程序目录或 uni-app、Taro 编译出的mp-weixin目录。这意味着页面里的渲染、组件、setData、生命周期走的都是微信官方基础库的代码不是 H5 那样由框架重新实现的和小程序真机上运行的是同一份产物。四大核心能力和真机一致官方基础库渲染测出来的问题就是真机上会出现的问题无头 E2E用 Playwright 直接在浏览器里测试不用远程控制开发者工具CI 里无头运行Linux 上不需要开发者工具用熟悉的工具调试Chrome DevTools 打断点、看网络请求、看 DOM保存文件后热更新页面栈和全局状态保留跳过走不通的环节在 setup 文件里预置登录态、mock 原生 API、拦截请求不用改一行业务代码。当前版本 v0.7.0MIT 协议内置基础库 wxa-baselib 是微信官方代码版权归腾讯所有。项目还明确了一点它不替代开发者工具——预览、上传、真机调试这些仍然要用开发者工具它只负责把「运行、调试、测试」搬进浏览器。三、5 分钟上手一行命令跑起来环境要求只有一条Node.js ≥ 18。基础库和编译器都内置了不用另外装。原生小程序在project.config.json所在目录运行npx wxa-runner dev . --openuni-app / Taro 项目先跑框架的监听构建再对编译产物目录启动以 uni-app 为例产物在dist/dev/mp-weixinHBuilderX 创建的项目在unpackage/dist/dev/mp-weixinnpm run dev:mp-weixin # 终端 1框架构建 npx wxa-runner dev ./dist/dev/mp-weixin --open # 终端 2wxa-runner # → http://localhost:3000uni-app 还有更省事的玩法——装 Vite 插件npm run dev:mp-weixin时自动拉起 wxa-runnerpnpm add -D open-wxa/unplugin-wxa-runner open-wxa/wxa-runner-core// vite.config.ts import uni from dcloudio/vite-plugin-uni; import wxaRunner from open-wxa/unplugin-wxa-runner/vite; export default defineConfig({ plugins: [uni(), wxaRunner()] });启动后浏览器里会出现一台「模拟手机」可以像模拟器一样点击、滚动。两个高频技巧直接打开任意页面地址加?path参数开发和测试都能一步定位不用从首页一路点过去http://localhost:3000/?pathpages/detail/detailid1长期使用或跑 CI装成开发依赖pnpm add -D wxa-runner别每次走 npx 下载。四、用 Chrome DevTools 调试打断点、看请求、看页面结构打开 Chrome DevToolsWindows 按F12之前只能在开发者工具调试器里干的事现在都是熟悉的 Chrome 套路想做什么怎么做打断点Sources 面板按CtrlP输入文件名如pages/index/index在控制台调用getCurrentPages()、wx.xxx控制台左上角上下文从top切到wxa-appservice看wx.request发出的请求Network 面板地址形如/__wxa__/proxy/https/api.example.com/user/info看被拦截的 mock 请求显示为/__wxa__/mock/https/…控制台同时打印[wxa-runner] 拦截请求看页面结构Elements 面板每个页面是一个 iframe体验上有两个细节很加分报错和单步调试会停在业务代码上不会跳进基础库修改 WXSS、WXML 和页面、组件的 JS 后热更新不刷新页面data、页面栈和globalData尽量保留——改样式、调交互的循环快了很多。五、启动前准备setup跳过登录、mock 原生 API、拦截 wx.request浏览器里拿不到真实的登录 code、用户信息和定位而小程序一启动往往就要登录。wxa-runner 的解法是setup 文件在App.onLaunch之前执行不改业务代码就能预置存储、替换原生 API、拦截wx.request。新建wxa.setup.ts// wxa.setup.ts import { defineSetup } from open-wxa/wxa-runner-core/setup; export default defineSetup({ storage: { token: test-token } });项目类型文件放在启动方式原生小程序project.config.json所在目录wxa-runner dev .自动找到uni-appVite 插件项目根目录npm run dev:mp-weixin自动找到uni-app、Taro命令行启动源码目录wxa-runner dev ./dist/dev/mp-weixin --setup ./wxa.setup.ts生效后浏览器控制台会打印[wxa-runner] setup 已应用。配置一共四项按storage → mock → network → run的顺序执行。1. 预置存储一启动就是已登录。按小程序判断登录的方式选写法启动只看本地 token 就用storage预置启动时调wx.login拿 code 换 token就拦截换 token 的接口export default defineSetup({ storage: { token: test-token, userInfo: { id: 1, nickName: 测试用户 } }, network: { routes: { POST **/api/auth/login: { body: { code: 200, data: { token: test-token } } } } } });wx.login不用管它返回wxa_mock_code_开头的假 code真实后端不认但换 token 的请求已经被拦下后端根本收不到。如果后端一定要真实的 code 或手机号启动时加--devtools-login可以借用本机开发者工具的登录态。2. 模拟定位、授权等原生 API。默认已授权用户信息和定位wx.getLocation返回北京天安门的坐标要换位置或模拟「未授权」直接 mockexport default defineSetup({ mock: { getLocation: { latitude: 31.23, longitude: 121.47 }, // 上海 // 模拟摄像头权限被拒errMsg 为 authorize:fail auth deny authorize: ({ scope }) { if (scope scope.camera) throw new Error(auth deny); return {}; } } });3. 模拟接口返回、报错和慢网络。拦截规则写成请求方法 地址*匹配一段路径、**匹配任意内容还能传函数按请求内容返回、加delay模拟慢网络export default defineSetup({ network: { routes: { GET **/api/feed: { body: { list: [] } }, // 返回空列表 GET **/api/user/*: { status: 500, body: { msg: 异常 } }, // 服务端报错 GET **/api/banner: { body: { list: [] }, delay: 3000 }, // 3 秒后才返回 // 按请求内容返回 POST **/api/orders: req { const { skuId } JSON.parse(req.data as string); return { status: 201, body: { id: order-${skuId} } }; } } } });4. token 不写死导出函数从环境变量读只有WXA_开头的变量会传进来git 提交和密钥安全两不误export default defineSetup(({ env }) ({ storage: { token: env.WXA_TOKEN } }));WXA_TOKENxxx wxa-runner dev .⚠️ 注意setup 文件和WXA_环境变量都会发到浏览器里只放测试用的 token不要放真正的密钥。六、用 Playwright 写 E2E 测试这是 wxa-runner 最核心的场景。官方提供了open-wxa/wxa-runner-playwright包给了一个miniProgramfixture——它会自动启动 wxa-runner、打开浏览器、等小程序就绪用例里直接写要测的东西。1. 安装用例在本机安装的 Google Chrome 里运行没装就先npx playwright install chromepnpm add -D playwright/test open-wxa/wxa-runner-playwright2. 新建playwright.config.ts原生小程序放在project.config.json所在目录uni-app、Taro 放源码根目录用wxaProject指向编译产物目录// playwright.config.ts import { defineConfig } from playwright/test; import type { WxaOptions } from open-wxa/wxa-runner-playwright; export default defineConfig({ testDir: e2e, use: { channel: chrome, // uni-app、Taro编译产物目录相对这个配置文件 // wxaProject: ./dist/dev/mp-weixin, // setup 文件相对这个配置文件 // wxaServerOptions: { setup: ./wxa.setup.ts }, } });3. 写第一个用例。注意test和expect要从open-wxa/wxa-runner-playwright导入不是playwright/test——这样用例里才有miniProgramexpect才有toHavePath等小程序专属断言// 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); });4. 运行npx playwright test # 无头运行全部用例 npx playwright test --headed # 打开浏览器窗口看着它运行 npx playwright test --ui # 图形界面可以一步步回看5. 一个完整例子下单前 mock 登录、拦截下单接口点击提交后检查跳转、页面 data 和发出的请求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 }); });常用能力一览写法作用miniProgram.open(pages/detail/detail?id1)打开指定页面?后是页面参数页面不在app.json里直接报错miniProgram.current.locator(#add).click()操作当前页跳转后自动指向新页面用法同page.frameLocator()expect(miniProgram).toHavePath(...)/toHavePageData({...})断言当前页路径 / 页面data不满足自动重试miniProgram.waitForRequest(pattern)等小程序发出匹配的请求返回的请求带method/url/header/bodybody已按 Content-Type 解析好miniProgram.mock(api, result)/route(pattern, handler)用例级 mock 原生 API / 拦截请求覆盖 setup 同名配置pageData()/pageStack()/callPageMethod()/navigateTo()等读页面 data、页面栈、调页面方法、直接跳转还有两个贴心的设计每个用例结束时 fixture 会自动检查运行时错误逻辑层/渲染层报错、调用了未实现的wxAPI有错就让用例失败不用自己加 try-catch测试时每个 worker 启动一个开发服务器、每个用例用新的浏览器上下文存储、页面栈互不影响天然支持并行。七、在 GitHub Actions 的 Linux CI 上无头运行前面的铺垫就是为了这一步CI 里无头运行Linux 上不需要开发者工具。标准 Playwright 流程即可跑通uni-app 项目在测试前先构建出mp-weixin目录# .github/workflows/e2e.yml name: e2e on: [push] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm ci # uni-app 项目先构建npm run build:mp-weixin - run: npx playwright install chrome - run: npx playwright test注意两个限制没有开发者工具的环境如 Linux CI只支持x86-64架构此时用的是内置编译器版本较旧模板运行时有少量差异。另外测试模式下不监听文件变化、不热更新运行环境和真机一致——这正是我们想要的测试条件。八、和官方 miniprogram-automator 怎么选两者不是替代关系选型看场景。核心差异miniprogram-automatorwxa-runner维护方微信官方社区开源还在 0.x 阶段运行在开发者工具的模拟器也能控制真机普通 Chrome可无头运行开发者工具必须还要开「CLI/HTTP 调用」不需要没装时用内置基础库和编译器操作系统工具只有 Windows、macOS 版Windows、macOS、Linux 都行真机支持miniProgram.remote()不支持写测试自己的 API配任意 Node 测试框架Playwright 的 locator 和断言 miniProgramfixturemock 网络请求mockWxMethod整体替换wx.request按 URL 规则拦截可断言请求体截图/调试开发者工具的调试器Playwright 截图、录屏、traceChrome DevTools用 automator 更合适要在真机上跑自动化小程序用了插件的自定义组件或要测蓝牙、Worker 里的网络请求等 wxa-runner 不支持的能力已有的 automator 用例能跑就不折腾。用 wxa-runner 更合适要在 Linux CI 上无头跑 E2E不想维护装开发者工具的测试机想用 Playwright 的 UI 模式、trace、并行、自动重试断言测试里要跳过登录、按 URL mock 大量接口。推荐组合日常提交在 Linux CI 上用 wxa-runner 跑发版前用 automator 在开发者工具或真机上回归预览、上传始终在开发者工具里做。已经用 automator 写过用例的迁移也不难reLaunch(/pages/index/index)对应miniProgram.open(pages/index/index)page.data()对应miniProgram.pageData()mockWxMethod(request, ...)对应route(GET **/api/feed, ...)。九、功能与限制上车前必看的避坑清单不替代开发者工具预览、上传、真机调试仍然要用开发者工具不支持真机需要真机自动化的场景用 automator基础库版本默认支持 3.7.0 及以下更新的版本要用--baselib或WXA_BASELIB指定且超出已验证范围导航栏、tabBar、原生 API 是 wxa-runner 自己实现的和真机可能有差异没实现的 API 调用后返回成功以免打断业务代码但会在测试里记进miniProgram.errors()让用例失败——所以发布前仍然要在真机上验证requestPayment、scanCode默认返回失败业务流程里用到支付、扫码时必须在 setup 或用例里 mock 掉同步 API 只能 mock 对象以Sync结尾的以及getSystemInfo等同步调用的 APImock 不能传函数text 组件取文字基础库 3.3.x 及更早版本里textContent会把 text 组件的文字读到两遍断言时用toHaveText(text, { useInnerText: true })或innerText()跳转后的选择器新旧页面有同一个选择器时先await expect(miniProgram).toHavePath(...)等跳转完成免得断言落在上一个页面上框架支持真实项目上只验证过 uni-appVue 3Taro 等框架的编译产物也是标准小程序代码理论可用但还没在真实项目上验证Worker、蓝牙等能力有已知限制重度依赖这些能力的小程序先看官方「功能与限制」文档。十、总结回顾一下本文核心要点wxa-runner 在浏览器里用微信官方基础库运行小程序编译产物渲染、组件、setData、生命周期都是官方代码和真机一致不是 H5 重新实现的那套一行命令npx wxa-runner dev ./dist/dev/mp-weixin启动原生小程序、uni-app、Taro 编译产物都能跑?path参数直达任意页面调试用 Chrome DevTools打断点、切wxa-appservice上下文、Network 看请求改文件热更新且保留页面栈wxa.setup.ts在App.onLaunch前预置 storage、mock 原生 API、按 URL 拦截wx.request不改业务代码跳过登录环境变量传 token 别放真密钥Playwright 测试用miniProgramfixtureopen/toHavePath/toHavePageData/route/waitForRequest用例结束自动检查运行时错误Linux CI 无头运行不需要开发者工具x86-64和 automator 互补日常 CI 用 wxa-runner发版前真机回归用 automator。FAQQwxa-runner 能替代微信开发者工具吗A不能。它只负责「运行、调试、测试」预览、上传、真机调试仍要开发者工具。QCI 里不装开发者工具真的能跑小程序 E2EA能这正是它的核心卖点。基础库和编译器都内置在包里GitHub Actions 的 ubuntu-latest 无头跑通注意 x86-64 架构限制。Q测出来的结果可信吗A渲染层是官方基础库可信度高但导航栏、tabBar、原生 API 是 wxa-runner 实现的与真机可能有差异发版前建议真机回归一遍。Quni-app 和 Taro 都支持吗Auni-appVue 3已在真实项目验证过Taro 编译产物理论上可用属于「能跑但未在真实项目验证」状态。如果这篇文章对你有帮助欢迎点赞、收藏支持一下你在小程序自动化测试上踩过什么坑、有什么更好的方案也欢迎在评论区聊聊。更多内容可以关注我的博客后续会继续更新前端工程化与测试方向的实践文章。参考资料wxa-runner GitHub 仓库wxa-runner 官方文档微信官方 miniprogram-automator 文档Playwright 官方文档相关链接名称链接wxa-runnerhttps://github.com/open-wxa/wxa-runnerwxa-runner 官方文档https://open-wxa.github.io/wxa-runner/微信官方 miniprogram-automator 文档https://developers.weixin.qq.com/miniprogram/dev/devtools/auto/Playwright 官方文档https://playwright.dev/