open-wxa/wxa-runner

wxa-runner is worth a look if you build WeChat mini-programs and your debugging or test loop is currently tied to WeChat DevTools. It runs compiled mini-program output in an ordinary browser on top of the official WeChat base library, so the page you inspect and the page Playwright drives are the same kind of runtime your users get.

The problem

A mini-program developer wants to click through a screen, set a breakpoint, inspect a failed request, and then run that same flow in CI. Today that usually means opening WeChat DevTools, driving it remotely for automation, or relying on an H5 reimplementation where the framework renders components itself. Each of those either needs the desktop tool present or drifts from real rendering. wxa-runner replaces the preview step: you point it at the compiled directory (dist/dev/mp-weixin or a Taro/uni-app build output), open localhost, and get the mini-program running in Chrome. Debugging then uses Chrome DevTools, and the same running app can be exercised by Playwright headless, including on Linux CI without DevTools installed.

What's different

The mechanism is the selling point: rendering, components, setData and lifecycle come from WeChat's official base library rather than a framework-level rewrite. That matters when a bug lives in a component's real behavior or in lifecycle timing, which an H5 substitute can mask. Debugging also becomes ordinary browser work: breakpoints, network panel and DOM inspection, plus hot reload after saving. A setup hook lets you inject login state, mock native APIs and intercept wx.request without touching business code, which removes the most annoying prerequisite of testing authenticated flows.

The trade-off is scope. The README is explicit that this does not replace DevTools: preview, upload and real-device debugging still belong there. There is also a documented route for borrowing DevTools' login state when you need a real code or phone number, which suggests those flows are not fully self-contained. Treat it as a faster inner loop and CI harness, not a complete replacement for the official toolchain.

Who should try it

A good fit is a team with an existing mini-program build (native, Taro or uni-app) that wants Playwright E2E coverage in CI, especially on Linux runners where installing WeChat DevTools is awkward. It also suits developers who prefer Chrome DevTools over the DevTools mini-program panel for breakpoints and network inspection, and who need to seed login or mock APIs in tests.

A poor fit is someone who mainly needs preview, upload or real-device debugging; those remain DevTools jobs. Teams expecting the runner to be a full simulator for publishing workflows will be disappointed by design, not by a missing feature.

Requirements and limitations

You need a compiled mini-program output directory, Node to run npx, and WeChat's base library and compiler, which the project depends on. The docs separate installation, the base library and compiler, and a setup step for login and API mocking, so budget time for configuration before the first run. Real code and phone-number flows or service-market and plugin pages require the DevTools login-state workaround, which ties those tests to a machine with DevTools available.

The bundled wxa-baselib is WeChat official code owned by Tencent and is not covered by this project's MIT license. That is a licensing boundary to check before redistributing or embedding the runner. Ongoing upkeep means tracking base-library and compiler versions as the mini-program platform evolves; the README does not spell out a compatibility policy.

HotRepo's take

HotRepo first recorded this repository on 2026-10-24; it reached #18 on the TypeScript NEW-REPOSITORY board (新项目榜, not the overall Trending board) at 583 total stars on 2026-10-25. Coverage has no comparable daily-board history, so persistence cannot yet be judged from these two dated samples. Before adopting, check the platform's functional limitations against the APIs your app relies on, since the base-library approach decides where the runner can and cannot stand in for DevTools.