Automate WeChat Mini Program DevTools from the terminal with `miniprogram-automator`. Use when harness engineering needs repeatable Mini Program flows such as launching or connecting to DevTools, re-launching routes, tapping selectors, filling inputs, collecting page data, mocking `wx` methods, or capturing screenshots during debugging and smoke checks.
Automate WeChat Mini Program DevTools from the terminal with `miniprogram-automator`. Use when harness engineering needs repeatable Mini Program flows such as launching or connecting to DevTools, re-launching routes, tapping selectors, filling inputs, collecting page data, mocking `wx` methods, or capturing screenshots during debugging and smoke checks.
WeChat Mini Program Automator
Drive WeChat Mini Program DevTools through miniprogram-automator instead of ad hoc UI clicking. Prefer the bundled runner for stable, JSON-driven harness workflows.
Prerequisite check
Before running any workflow, verify all of the following:
If require.resolve fails, install the package in the working directory:
npm install miniprogram-automator
If connecting to an already-open DevTools window, ensure the target project is open with automation enabled. The package reports connection failures as "check if target project window is opened with automation enabled".
Resolve the current repo first. Do not assume the working directory is itself the DevTools project root.
If the resolver returns multiple hosted targets, present the candidate hosts to the user and ask them to choose before continuing.
Prefer cli auto bootstrapping plus connect, even when you know the project path.
Use launch only as a fallback for clean, disposable sessions where the project is not already open in DevTools.
Store the interaction plan as JSON in a temporary file instead of embedding long action arrays directly in the prompt.
Run the bundled script and inspect its JSON output.
Save screenshots or other artifacts under output/wechat-miniprogram-automator/ when the repo already has an output area. Otherwise use /tmp.
For multi-page smoke checks, prefer run_wechat_batch.cjs so the batch leaves one top-level report.json plus one subreport per case.
On Taro React pages, prefer adding root or inspectDataTree when you need structure-level snapshots. Business hook state such as loading or houseData may resolve to undefined from page.data(path).
Before a long batch, prefer a short canary or preflight flow that proves the page has moved beyond loading or skeleton state.
Readiness selector guidance:
container selector: the page shell, root node, list wrapper, or layout block that can appear before real content is ready
business selector: the first selector that only appears after real data has rendered, such as the first card, the real title text block, an image inside a swiper, or an enabled submit button
For preflight and smoke checks, prefer business selector over container selector
If the page can render a skeleton immediately, do not use only the route root as the final readiness condition
Resolve project shape first
Use the resolver before picking launch or connect:
node "$WXA_RESOLVER" --cwd "$PWD"
The resolver returns one of these shapes:
standalone-miniprogram: the current repo is itself the Mini Program root. Use projectPath directly.
hosted-subpackage: the current repo builds into one or more host Mini Programs. Use selectedTarget.devtoolsProjectPath as the DevTools project path, not the current repo path.
unknown: the skill could not find either shape and needs manual input.
For hosted subpackages, the resolver inspects package.json, .mps.config.js, and config/index.js, then returns structured target metadata such as:
weappType: internal build target such as tongcheng or wuba
scriptSuffix: script-facing short name such as wbfc or ajk
publishKey: script-facing target such as weapp-wbfc
devScript: watch command to keep the subpackage output synced into the host
hostProjectPath: runtime Mini Program root that contains app.json
devtoolsProjectPath: DevTools project root that contains project.config.json
subpackageRoot: relative path from the host root to the mounted subpackage output
isActiveCandidate: whether the resolver found a matching running watch process
selectionReason: why the target was marked active or recommended
--target accepts any of weappType, scriptSuffix, publishKey, or full script names such as dev:weapp-wbfc.
This split matters because some hosts keep project.config.json one level above the runtime miniprogram/ directory. Opening the runtime root in DevTools can start a broken or partial session even though the files exist.
Ask the user to choose the host
When the resolver returns more than one hosted target, do not silently pick one and continue.
Instead:
Summarize the candidate hosts in plain language.
Include enough fields for the user to recognize the right target:
weappType
devScript
devtoolsProjectPath
subpackageRoot
Ask the user to choose one target.
Only continue with bootstrap, connect, route changes, or screenshots after the user has picked the target.
Use the resolver default only when there is exactly one hosted target.
When the resolver can uniquely match a running dev:weapp-* or taro build --watch process, it also returns recommendedTarget. Use that recommendation to prefill or highlight the likely host, but still ask the user to confirm when multiple hosts exist.
Internally this runs cli auto --project ... --auto-port <port>. If you call bootstrap directly, you can still manage a fixed port yourself. If you use the higher-level flow or batch entrypoints, they now derive a stable per-project port from devtoolsProjectPath so different projects do not accidentally reuse the same old session. That flow is idempotent enough for day-to-day use:
if the project is already open, DevTools reuses it instead of trying to open a duplicate window
if the project is closed, DevTools opens it and enables automation
After bootstrapping, connect to the matching websocket port. Low-level scripts can target a manual endpoint such as ws://127.0.0.1:9420; high-level entrypoints choose the project-specific port automatically.
Hosted subpackage workflow
When the current repo is a subpackage business repo instead of a standalone Mini Program:
Run the resolver.
If multiple targets are returned, stop and ask the user which host to use.
After the user chooses, use that target, for example tongcheng or weapp-wbfc.
Start the matching watch script from selectedTarget.devScript so the host-mounted output stays fresh.
Bootstrap DevTools against selectedTarget.devtoolsProjectPath.
Use normal actions such as reLaunch, tap, data, and screenshot after the host app is open.
Important: for hosted subpackages, --project-path in the bootstrap step must point at the DevTools project root, not blindly at the nearest app.json directory. Those can differ.
In Codex-like sandboxed environments, local websocket ports may be unreachable even when DevTools is correctly configured. If lsof shows the target port listening but plain node or curl still cannot connect, re-run the port probe and the automator command before changing the Mini Program workflow.
There is a second sandbox failure mode worth treating separately: cli auto succeeds, lsof shows the port listening, and curl -i http://127.0.0.1:<port> returns 426 Upgrade Required, but Node-based scripts still fail with messages such as "check if target project window is opened with automation enabled" or a bootstrap false negative. Treat that as a sandbox transport issue rather than a DevTools configuration issue. In that case:
run cli auto --project ... --auto-port 9420
verify with lsof -nP -iTCP:9420 -sTCP:LISTEN
verify with curl -i http://127.0.0.1:9420
rerun the Node automator command outside the sandbox
Quick start
Launch DevTools for a local project and run a route smoke flow:
If you do not pass --port here, the flow script chooses a stable port for the current DevTools project. That prevents cross-project collisions when you switch between repos such as anxinwechat and anjuke_weapp.
wait for one business selector or data condition that proves content is no longer just loading or skeleton
optionally capture one screenshot
If preflight fails, treat that as an environment or readiness blocker first. Do not immediately interpret a full batch of selector timeouts as twelve independent product regressions.
The script prints one JSON object to stdout so harness code can parse the result without scraping logs.
Guardrails
Prefer selectors that are stable across builds. If the app exposes data-testid-style classes or ids, use those instead of brittle layout selectors.
Keep action files declarative. Do not add arbitrary JS execution unless the user explicitly needs it.
Prefer cli auto plus connect over launch, because opening the same DevTools project twice is unreliable and can fail with opaque automator errors.
Re-run the flow with longer waits if the page depends on network or async hydration.
When a selector fails, collect data() or a screenshot before changing the action file so the failure remains diagnosable.
In connect mode, disconnect from the websocket when finished; do not close the user-owned DevTools instance. Closing DevTools from a shared session breaks subsequent routes and batch captures.
For multi-page capture or batch smoke tests, either keep one long-lived session open or invoke the runner repeatedly in connect mode. Do not tear down the underlying DevTools window between pages.
References
Open only what is needed:
workflow details and action schema: references/workflow.md
