### [wxa-runner：在浏览器里运行微信小程序，用 Playwright 做自动化测试](https://www.appmiao.com/article/12141)

**Published:** 2026-11-07T03:32:49

**Author:** 阿喵#

**Excerpt:** wxa-runner 是免费开源的微信小程序浏览器运行工具，使用微信官方基础库，支持 Chrome DevTo…

## 阿喵前言

给小程序补一条自动化测试，难道就得先把微信开发者工具搬进 CI？wxa-runner 把微信官方基础库带进普通浏览器，**直接运行小程序编译产物，用 Playwright 测页面和请求**，不用为了测试再维护一套 H5。阿喵觉得它最对路的地方，就是让小程序也能接上熟悉的浏览器调试和自动化流程。

## 资源介绍

wxa-runner 是免费开源的微信小程序浏览器运行工具，面向本地调试和端到端自动化测试。它使用微信官方基础库处理渲染、组件、setData 和生命周期，而不是把小程序重新实现成 H5；原生项目可直接启动，uni-app、Taro 则使用微信小程序编译产物。

它支持 Chrome DevTools 调试、保存后热更新，以及通过 setup 预置存储、模拟原生接口和拦截请求。接入 Playwright 后，可以检查页面路径、页面数据和请求内容，也适合放进 Linux CI。当前正式版为 **v0.13.0**，命令行包已发布到 npm。

### 截图

![wxa-runner在线查看器的小程序首页与setup配置面板](https://oss.amiao.app/website/2026/11/07033214/wxa-runner-013-demo-advmo-cb260d6a6346.webp)

在线查看器：小程序首页与 setup 配置面板。

![wxa-runner官方示例的小程序帖子详情页](https://oss.amiao.app/website/2026/11/07033220/wxa-runner-013-detail-advmo-9fd728e7f700.webp)

官方示例：小程序帖子详情页。

在线演示使用 mock 数据展示界面，画面中的账号、投票与帖子不是生产环境数据。

### 特色

-   **不用另做 H5：**直接运行原生小程序目录或框架生成的 mp-weixin 目录。
-   **浏览器里调试：**用 DevTools 打断点、看 DOM 和网络请求，修改后热更新。
-   **测试不必遥控开发者工具：**Playwright 直接操作浏览器，可在 CI 中无头运行。
-   **绕开测试前置障碍：**用 setup 配置测试登录态、接口应答和原生 API 模拟，不改业务代码。
-   **直接定位页面：**通过带路径与参数的地址打开目标页，少走重复导航。

### 注意

-   它是调试与测试工具，不代表所有行为都与真机完全等价。蓝牙等设备能力、云开发调用不支持；微信扫码预览、上传和真机调试仍要回到微信开发者工具。
-   登录、用户信息等开放接口默认返回假数据，支付和扫码默认失败；未实现的部分 API 可能返回成功，测试时应明确 mock 并检查运行时错误。
-   不装开发者工具的 Linux／CI 环境目前只支持 x86-64。Taro 可接入标准编译产物，但项目明确验证过的真实框架项目主要是 uni-app。
-   项目代码采用 MIT；内置微信官方基础库版权归腾讯，不适用本项目的 MIT 许可。

## 使用教程

1.  **先看演示。**打开在线查看器，可先了解浏览器中的小程序界面；它展示的是配置好的示例，不需要导入自己的项目。
2.  **准备项目和环境。**命令行工具需要 Node.js 18 及以上与 Chrome。原生项目找到 project.config.json 所在目录；uni-app 或 Taro 先完成微信小程序端编译。
3.  **启动浏览器调试。**原生项目在上述目录执行：
    
    ```
    npx wxa-runner dev . --open
    ```
    
    uni-app 常见编译目录可用：
    
    ```
    npx wxa-runner dev ./dist/dev/mp-weixin --open
    ```
    
    HBuilderX 项目通常改为 unpackage/dist/dev/mp-weixin。框架的监听构建需继续运行。
    
4.  **处理测试所需条件。**按[setup 文档](https://open-wxa.github.io/wxa-runner/setup)准备模拟接口和测试存储，再用 Chrome DevTools 查看业务代码。涉及真实登录时按需阅读专门文档，不要把默认假 code 当作真实授权。
5.  **接入自动化。**按[Playwright 教程](https://open-wxa.github.io/wxa-runner/testing)添加测试包和配置。测试中的 test、expect 从 @open-wxa/wxa-runner-playwright 导入，再逐步加入页面路径、数据和请求断言。

若想把小程序打包成 .wxapack，再导出静态查看器分享给团队，需走[查看器文档](https://open-wxa.github.io/wxa-runner/viewer)里的仓库构建流程；这一功能目前尚未发布到 npm，不能直接照搬为 npm 包已具备的命令。

## 资源获取

[GitHub 开源仓库](https://github.com/open-wxa/wxa-runner) · [npm 命令行包](https://www.npmjs.com/package/wxa-runner) · [在线演示](https://wxa-viewer.picfinder.workers.dev) · [中文文档](https://open-wxa.github.io/wxa-runner/)

**Tags:** Node.js, Playwright, Taro, uni-app, 开发工具, 开源软件, 微信小程序, 持续集成, 浏览器, 自动化测试

**Categories:** 开源项目

---