Registry / testing / miniprogram-simulate

miniprogram-simulate

JSON →
library1.6.1jsnpmunverified

miniprogram-simulate is a testing utility designed to facilitate unit testing for WeChat miniprogram custom components. It addresses the challenges of testing in the miniprogram's unique dual-threaded runtime environment by simulating a single-threaded DOM environment. This approach allows developers to leverage standard JavaScript testing frameworks like Jest, Karma, or Mocha (with JSDOM) to test their miniprogram components. The package essentially recreates the component tree within a DOM environment for easier assertion and interaction. The current stable version is 1.6.1, and it maintains a relatively active release cadence, with minor versions typically released every 1-3 months. Its key differentiator is providing a mock DOM environment for miniprogram components, abstracting away the platform-specific runtime intricacies.

npm install miniprogram-simulate
INSTALL
IMPORT
SIG · MINIPROGRAM-SIMULA
M
miniprogram-simulate
testingjavascriptv1.6.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

simulate
const simulate = require('miniprogram-simulate')
import simulate from 'miniprogram-simulate'
The primary usage demonstrated in documentation is CommonJS. While ESM might work with bundlers, CJS is the officially shown pattern for direct Node.js execution within test runners like Jest.
Simulate
import type { Simulate } from 'miniprogram-simulate'
import { Simulate } from 'miniprogram-simulate'
Used for TypeScript type imports to leverage type definitions for the 'simulate' object. The main runtime export is usually a default or single named export of an object.
load, render
const simulate = require('miniprogram-simulate'); simulate.load(...); simulate.render(...);
import { load, render } from 'miniprogram-simulate'
Functions like `load` and `render` are methods of the main `simulate` object, not direct named exports. Destructuring from the package root will not work.

This quickstart demonstrates how to load and render a miniprogram custom component using `miniprogram-simulate` within a Jest testing environment, including basic assertion and prop updates.

const simulate = require('miniprogram-simulate'); const path = require('path'); // Assuming a basic Jest setup with JSDOM environment // and a component at 'src/components/my-comp/index.js' describe('MyComponent', () => { let id; beforeAll(() => { // Load the component definition. Adjust path as needed. // Ensure your test runner is configured to resolve miniprogram paths. id = simulate.load(path.resolve(__dirname, './src/components/my-comp/index')); }); test('should render correctly and display initial text', () => { // Render the component instance const comp = simulate.render(id); // Get the shadow root of the component (if applicable, or direct element for non-shadow-dom) // For miniprograms, custom components often behave like web components with internal encapsulation const element = comp.querySelector('.my-text'); // Assuming an element with class 'my-text' inside the component expect(element.textContent).toBe('Hello World'); }); test('should update text on prop change', async () => { const comp = simulate.render(id, { initialText: 'Initial' }); let element = comp.querySelector('.my-text'); expect(element.textContent).toBe('Initial'); // Simulate prop update (often via setData for miniprograms) await comp.setData({ initialText: 'Updated' }); element = comp.querySelector('.my-text'); // Re-query or expect direct update on existing reference expect(element.textContent).toBe('Updated'); }); });
Debug
Known issues
gotchaminiprogram-simulate is a simulation tool, not a full miniprogram runtime. It relies on a DOM environment (like JSDOM or a real browser) but does not emulate all aspects of the WeChat miniprogram environment, such as specific native modules, certain API behaviors, or full lifecycle parity. Developers should consult the '暂不支持特性' (currently unsupported features) documentation for limitations.
fix
Always refer to the '暂不支持特性' and '细节实现' sections of the official documentation to understand current limitations and adjust test strategies accordingly. For features not supported, consider integration tests on a real device or E2E tests using official WeChat DevTools capabilities.
affects: >=1.0.0
gotchaThe tool fundamentally requires a DOM environment. Running tests in a pure Node.js environment without JSDOM or a similar browser-like context will result in errors.
fix
Ensure your test runner (e.g., Jest) is configured to use a JSDOM environment. For Jest, add `testEnvironment: 'jsdom'` to your `jest.config.js` or package.json. Alternatively, use a browser-based test runner like Karma.
affects: >=1.0.0
gotchaComponent paths for `simulate.load()` must be resolvable from the test file's perspective. Miniprogram component paths often differ from standard Node.js module resolution. Relative paths from the project root or absolute paths may be needed.
fix
Use `path.resolve()` with `__dirname` or project root to construct robust paths for `simulate.load()`. Ensure any custom path aliases or resolvers used in your miniprogram project are also configured in your test setup if `miniprogram-simulate` needs to load sub-components or dependencies via those aliases.
affects: >=1.0.0
Errors
Common errors & fixes
ReferenceError: document is not defined
The test environment is a pure Node.js environment without a simulated DOM.
fix
Configure your test runner (e.g., Jest) to use a JSDOM environment. For Jest, add `testEnvironment: 'jsdom'` to your `jest.config.js` or package.json.
Error: Cannot find module 'path/to/component'
The component path provided to `simulate.load()` is incorrect or not resolvable by the test runner.
fix
Verify the path to your miniprogram component. Use `path.resolve(__dirname, 'relative/path/to/component')` to ensure an absolute path. Check if your test runner's module name mapper or resolver configuration needs adjustment for miniprogram-specific path aliases.
TypeError: simulate.load is not a function (or similar for render, etc.)
The 'simulate' object was not correctly imported or required, or you're trying to destructure methods that are not direct exports.
fix
Ensure you are using `const simulate = require('miniprogram-simulate')` for CommonJS. If using ESM, try `import * as simulate from 'miniprogram-simulate'`. Do not try to destructure `load` or `render` directly from the package as they are methods on the `simulate` object.
Upgrade
Version history
1.6.1latest on npm
Audit
Dependencies
jestoptionalCommonly used test runner to execute miniprogram-simulate tests; provides test environment and assertions.
jsdomoptionalProvides a simulated DOM environment necessary for miniprogram-simulate to render components when running in Node.js.
Agent activity
6 hits · last 30 days
node
6
Resources
miniprogram-simulate — npm install miniprogram-simulate · libregistry