WeChat Mini Program Testing Guide and Common Issues

Introduction – Since the launch of WeChat Mini Programs in 2017, they enable rich functionality without installation; however, a complete testing guide is lacking. This document provides a concise overview of testing practices.

Mini Program Publication Review

Apply for an external domain name and configure it in the WeChat DevTools.

Upload code, then submit the version for review via the Mini Program management console.

After approval, publish the Mini Program; if rejected, modify and resubmit.

The first review typically takes about three days and requires a backend release.

Platform Limitations

Page navigation depth cannot exceed 10 levels.

Local cache is limited to 10 MB.

Code package size cannot exceed 3 MB; large assets must be hosted on a CDN.

All releases must pass WeChat’s review process.

External domain registration is required before submission (excluding WeChat domains).

Version Types

Development version – unrestricted package size, temporary QR code (expires after 30 min).

Experience version – requires developer and tester permissions, limited package size, QR code remains constant.

Online (production) version – accessible to all users, subject to package size limits.

Cache Mechanism

WeChat caches Mini Program files, authorization data, and login data.

Cache issues arise when switching environments, updating versions, or logging in/out; a simple workaround is to delete the Mini Program and relaunch.

Cold start vs. hot start behavior is illustrated in the original diagram.

Cache isolation is at the app level, user level, and device level as described.

Testing Workflow

Pre‑test preparation includes ensuring WeChat version ≥ 6.3.27, obtaining tester permissions, confirming AppID, and defining the test entry point.

Key test points:

Authorization – silent authorization using OpenID to generate user IDs.

Functionality – verify core features behave identically to production.

Cache – monitor 10 MB limit, page data persistence, and use wx.clearStorageSync() when needed.

Sharing – test friend‑list sharing, poster generation, and QR‑code redirects for each version.

Service Notifications – validate template message delivery, formId collection, and expiration handling.

Layer Management – avoid exceeding the 10‑level navigation limit by storing page paths in storage.

Compatibility – test across different WeChat client versions, device models, and OS platforms.

Instrumentation – verify analytics parameters (actiontype, pagetype, channel, pagechannel, scene, type) are correctly logged.

Common Issues and Solutions

Offline testing of public‑account messages may show “未关注公众号”; resolve by copying the online user’s UnionID and OpenID to the offline environment.

“User not authorized” errors stem from mismatched source IDs; synchronize the user_auth table between environments.

FormId errors include expiration, format mistakes, missing or already‑used IDs; ensure timely collection and correct usage per Mini Program.

Message template URL errors arise from incorrect page paths; verify the URL resolves to a published Mini Program page.

Testing Tools

Two utilities simplify testing:

Entry Builder – constructs URLs for M‑pages or webview entries, optionally adding channel parameters (e.g., pages/webview/webview?url=https://example.com).

Mini Program QR Code Tester – generates QR codes that jump to the specified version (dev/experience/online) and displays channel parameters for verification.

These tools help ensure that scans during development target the correct version and that channel tracking works as expected.