@mpcore/test 1.0.0 → 1.1.0

package/README.md

@@ -1,41 +1,54 @@
 # @mpcore/test
 
-面向微信小程序编译产物的 runner 无关测试 API。它模拟微信宿主和逻辑 WXML 树，不创建浏览器 DOM。
+面向微信小程序编译产物的 runner 无关测试 API。它模拟微信宿主和逻辑 WXML 树，不创建浏览器 DOM，也不计算 CSS layout。
 
 ```ts
-const project = createTestProject({
-  artifact: { projectPath: '/path/to/project' },
-  host: createWxMock({
-    request: { url: '/api/count', response: { data: { count: 1 } } },
-  }),
-})
+import { artifactFromProject, createTestProject } from '@mpcore/test'
 
-const result = await project.renderComponent('components/counter/index', {
-  properties: { value: 1 },
-  slots: { default: '<text>计数器</text>' },
+const project = createTestProject({
+  artifact: artifactFromProject(process.cwd()),
 })
 
-await result.user.tap(result.screen.getByRole('button', { name: '增加' }))
+try {
+  const result = await project.renderComponent('components/counter/index', {
+    properties: { value: 1 },
+    slots: { default: '<text>计数器</text>' },
+    events: ['change'],
+  })
+
+  await result.user.tap(result.screen.getByRole('button', { name: '增加' }))
+  expect(result.emitted('change')).toEqual([{ value: 2 }])
+  await result.setProperties({ value: 3 })
+  await result.setData({ expanded: true })
+  await result.unmount()
+}
+finally {
+  await project.close()
+}
 ```
 
-查询支持 text、role、test id、attribute、`within()` 及 `get/query/find/getAll/findAll` 变体，并保留 `$` / `$$` 选择器逃生口。`tap/input/change/blur/trigger` 会等待同步更新和 microtask 稳定后刷新逻辑树。
+`renderPage('/pages/index/index')` 挂载页面。组件通过内存宿主页挂载，属性更新复用同一组件实例并保留内部状态；`setData()` 更新组件自身数据。`unmount()` 触发组件卸载而保留测试会话，`close()` 释放整个渲染会话，`project.close()` 关闭项目内全部渲染。
 
-未匹配的网络 mock 会抛错；未捕获运行时异常和 `console.error` 默认令测试失败。可通过 `diagnostics()` 断言 warning，负向 console 测试可显式设置 `failOnConsoleError: false`。
+查询支持 text、role、test id、attribute、`within()` 及 `get/query/find/getAll/findAll` 变体，并保留 `$` / `$$` 选择器逃生口。`tap/input/change/blur/trigger` 会等待同步更新和 microtask 稳定后刷新逻辑树。保留的 `within()` 查询共享最新快照，并按原 runtime `nodeId` 确定范围；该 ID 缺失时查询报错，不会按相同 test id 重定位。runtime 可能在条件节点恢复等情况下复用同一路径的 `nodeId`，此时保留的节点和作用域会解析到当前快照中该 ID 对应的节点。
 
-`@mpcore/test` 为真实微信小程序编译产物提供页面和组件单测环境。它模拟微信宿主与逻辑 WXML 树，不提供浏览器 `document` 或 CSS layout。
+事件需要显式订阅：`events: ['change']` 从挂载阶段开始收集，`on: { change(detail, event) {} }` 同时收集并回调。挂载后可调用 `result.on('change', listener)`，返回取消订阅函数；省略 listener 时只收集。`off()` 取消对应订阅，已收集的 `emitted()` 历史保留。动态订阅复用组件实例。
 
-```ts
-import { artifactFromProject, createTestProject } from '@mpcore/test'
+子组件可按标签名递归替换：
 
-const project = createTestProject({
-  artifact: artifactFromProject(process.cwd()),
+```ts
+const result = await project.renderComponent('components/profile/index', {
+  usingComponents: {
+    'remote-avatar': {
+      properties: { label: '' },
+      template: '<text>{{label}}</text><slot />',
+    },
+    'remote-panel': '/components/local-panel/index',
+  },
 })
+```
 
-const { screen, user } = await project.renderPage('/pages/index/index')
-await user.tap(screen.getByRole('button', { name: '增加' }))
-expect(screen.getByText('2')).toBeDefined()
+替换应用于当前渲染中的整个组件依赖树，不修改磁盘编译产物，也不影响同项目的其他渲染。字符串指向替代组件；声明式替身支持 `template`、属性默认值 `properties` 和初始 `data`，默认模板为 `<slot />`。
 
-await project.close()
-```
+`toMiniProgramSnapshot(result.screen)` 将 screen、节点或 `page.snapshot()` 转为稳定语义树，保留标签、公开属性、文本、事件类型和子节点，过滤 runtime ID 与作用域标记，事件 handler 名统一显示为 `[handler]`。`mpcoreSnapshotSerializer` 可注册到支持 Jest serializer 协议的 runner；`@mpcore/vitest` 会自动注册。完整诊断快照仍可通过 `page.snapshot()` 获取。
 
-组件测试通过内存宿主页挂载构建后的组件，不会修改小程序产物。
+未匹配的网络 mock 会抛错；未捕获运行时异常和 `console.error` 默认令测试失败。可通过 `diagnostics()` 断言 warning，负向 console 测试可显式设置 `failOnConsoleError: false`。宿主请求可通过 `createWxMock()` 显式配置。

package/dist/index.d.mts

@@ -5,7 +5,7 @@ interface RoleQueryOptions {
   name?: TextMatcher;
 }
 //#endregion
-//#region src/screen/index.d.ts
+//#region src/screen/node.d.ts
 export declare class MiniProgramNode {
   private readonly owner;
   readonly nodeId: string;
@@ -22,12 +22,17 @@ export declare class MiniProgramNode {
   get tagName(): string | undefined;
   get textContent(): string;
   getAttribute(name: string): string;
+  /** 返回当前节点的稳定语义树，卸载后的节点不能生成快照。 */
+  snapshot(): MiniProgramTreeSnapshot;
 }
+//#endregion
+//#region src/screen/index.d.ts
 export declare class MiniProgramScreen {
   private readonly page;
-  private currentSnapshot;
+  private snapshotStore;
   private readonly rootNodeId?;
   constructor(page: HeadlessTestingPageHandle, snapshot: HeadlessTestingPageSnapshot, rootNodeId?: string);
+  private get currentSnapshot();
   private get root();
   private allElements;
   private wrap;
@@ -38,6 +43,8 @@ export declare class MiniProgramScreen {
   resolveNode(nodeId: string): HeadlessTestingLogicalNode;
   refresh(): Promise<void>;
   within(node: MiniProgramNode): MiniProgramScreen;
+  /** 返回用于断言的稳定语义树，不包含页面数据与内部节点身份。 */
+  snapshot(): MiniProgramTreeSnapshot;
   queryAllByText(matcher: TextMatcher): MiniProgramNode[];
   queryByText(matcher: TextMatcher): MiniProgramNode;
   getAllByText(matcher: TextMatcher): MiniProgramNode[];
@@ -101,9 +108,20 @@ export interface CreateTestProjectOptions {
   platform?: PlatformAdapter;
 }
 export interface RenderComponentOptions {
-  on?: Record<string, (detail: unknown, event: Record<string, any>) => void>;
+  /** 从首次挂载开始收集指定事件，无需提供回调。 */
+  events?: string[];
+  on?: Record<string, MiniProgramEventListener>;
   properties?: Record<string, unknown>;
   slots?: Record<string, string>;
+  /** 递归替换本次渲染的组件别名；字符串路径相对于小程序产物根目录。 */
+  usingComponents?: Record<string, string | InlineComponentStub>;
+}
+export type MiniProgramEventListener = (detail: unknown, event: Record<string, any>) => void;
+/** 声明式子组件替身；properties 的值为默认属性值。 */
+export interface InlineComponentStub {
+  data?: Record<string, unknown>;
+  properties?: Record<string, unknown>;
+  template?: string;
 }
 export interface MiniProgramRenderResult {
   close: () => Promise<void>;
@@ -116,6 +134,18 @@ export interface MiniProgramRenderResult {
 export interface MiniProgramEmissionSource {
   emitted: (eventName: string) => unknown[];
 }
+export interface MiniProgramComponentRenderResult extends MiniProgramRenderResult {
+  /** 移除当前事件的全部订阅，或移除指定回调的全部订阅。 */
+  off: (eventName: string, listener?: MiniProgramEventListener) => void;
+  /** 每次调用建立独立订阅；返回值仅取消本次订阅，省略回调时只收集事件。 */
+  on: (eventName: string, listener?: MiniProgramEventListener) => () => void;
+  /** 更新当前组件实例的数据，并等待渲染完成。 */
+  setData: (data: Record<string, unknown>) => Promise<void>;
+  /** 通过宿主绑定更新当前组件的属性，并等待渲染完成。 */
+  setProperties: (properties: Record<string, unknown>) => Promise<void>;
+  /** 移除组件主体并触发真实卸载流程，保留可独立关闭的测试会话。 */
+  unmount: () => Promise<void>;
+}
 export interface MiniProgramMatcherResult {
   message: () => string;
   pass: boolean;
@@ -148,7 +178,7 @@ export declare class MiniProgramTestProject {
   constructor(options: CreateTestProjectOptions);
   private render;
   renderPage(route: string): Promise<MiniProgramRenderResult>;
-  renderComponent(componentPath: string, options?: RenderComponentOptions): Promise<MiniProgramRenderResult>;
+  renderComponent(componentPath: string, options?: RenderComponentOptions): Promise<MiniProgramComponentRenderResult>;
   close(): Promise<void>;
 }
 export declare function artifactFromProject(projectPath: string): {
@@ -156,4 +186,25 @@ export declare function artifactFromProject(projectPath: string): {
 };
 export declare function createTestProject(options: CreateTestProjectOptions): MiniProgramTestProject;
 //#endregion
-export { type RoleQueryOptions, type TextMatcher, wechat };
+//#region src/snapshot/tree.d.ts
+interface MiniProgramElementSnapshot {
+  attributes: Record<string, string>;
+  children: MiniProgramTreeSnapshot[];
+  tag: string;
+}
+interface MiniProgramTextSnapshot {
+  text: string;
+}
+type MiniProgramTreeSnapshot = MiniProgramElementSnapshot | MiniProgramTextSnapshot;
+//#endregion
+//#region src/snapshot/index.d.ts
+export type MiniProgramSnapshotSource = MiniProgramScreen | MiniProgramNode | HeadlessTestingPageSnapshot;
+/** 将查询对象或完整诊断快照显式转换为适合稳定断言的语义树。 */
+export declare function toMiniProgramSnapshot(source: MiniProgramSnapshotSource): MiniProgramTreeSnapshot;
+/** 通过 Vitest/Jest 的公开 serializer 接口，仅格式化本包的查询对象。 */
+export declare const mpcoreSnapshotSerializer: {
+  test(value: unknown): value is MiniProgramScreen | MiniProgramNode;
+  serialize(value: MiniProgramScreen | MiniProgramNode): string;
+};
+//#endregion
+export { type MiniProgramElementSnapshot, type MiniProgramTextSnapshot, type MiniProgramTreeSnapshot, type RoleQueryOptions, type TextMatcher, wechat };

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import path from "node:path";
 import { HeadlessTestingPageHandle, createArtifactProject, createHeadlessSession, createMemoryArtifactSource, createOverlayArtifactSource, createProjectDescriptor, loadProject, wechat, wechat as wechat$1 } from "@mpcore/simulator";
+import path from "node:path";
 //#region src/host.ts
 function asList(value) {
 	if (!value) return [];
@@ -61,6 +61,258 @@ const mpcoreMatchers = {
 	toHaveTextContent
 };
 //#endregion
+//#region src/componentHarness/data.ts
+/** 在测试 API 边界复制 JSON 数据，避免调用方引用进入 runtime。 */
+function serializeComponentData(value, label) {
+	try {
+		return JSON.stringify(value, (_key, item) => {
+			if (typeof item === "function" || typeof item === "symbol" || typeof item === "bigint") throw new TypeError("Unsupported non-serializable value.");
+			return item;
+		});
+	} catch (error) {
+		throw new TypeError(`${label} must contain serializable data.`, { cause: error });
+	}
+}
+function cloneComponentData(value, label) {
+	return JSON.parse(serializeComponentData(value, label));
+}
+//#endregion
+//#region src/overrides/index.ts
+function normalizeComponentPath(componentPath) {
+	const relativePath = componentPath.trim().replaceAll("\\", "/").replace(/^\/+/, "");
+	const normalized = path.posix.normalize(relativePath.replace(/\.(?:js|json|wxml)$/, ""));
+	if (/^[a-z]:/i.test(relativePath) || /^[a-z]:/i.test(normalized) || !normalized || normalized === "." || normalized === ".." || normalized.startsWith("../")) throw new TypeError("Component paths must point inside the mini-program artifact root.");
+	return normalized;
+}
+/** 在本次渲染的 artifact 读取边界递归覆盖组件依赖。 */
+function createComponentOverrides(project, overrides = {}) {
+	const root = project.miniprogramRootPath;
+	const replacements = {};
+	const entries = [];
+	for (const [index, [alias, replacement]] of Object.entries(overrides).entries()) {
+		if (typeof replacement === "string") {
+			replacements[alias] = `/${normalizeComponentPath(replacement)}`;
+			continue;
+		}
+		const relativePath = `mpcore-test/stubs/stub-${index}/index`;
+		const basePath = path.resolve(root, relativePath);
+		replacements[alias] = `/${relativePath}`;
+		entries.push([`${basePath}.json`, "{\"component\":true}"], [`${basePath}.wxml`, replacement.template ?? "<slot />"], [`${basePath}.js`, `Component(${serializeComponentData({
+			data: replacement.data ?? {},
+			properties: Object.fromEntries(Object.entries(replacement.properties ?? {}).map(([key, value]) => [key, {
+				type: null,
+				value
+			}]))
+		}, "Inline component stubs")})`]);
+	}
+	const source = createOverlayArtifactSource(createMemoryArtifactSource(entries), project.artifactSource);
+	if (Object.keys(replacements).length === 0) return source;
+	return {
+		has: (filePath) => source.has(filePath),
+		readText(filePath) {
+			const original = source.readText(filePath);
+			const basePath = filePath.replace(/\.json$/, "");
+			if (!filePath.endsWith(".json") || !source.has(`${basePath}.js`) || !source.has(`${basePath}.wxml`)) return original;
+			const config = JSON.parse(original ?? "{}");
+			return JSON.stringify({
+				...config,
+				usingComponents: {
+					...config.usingComponents,
+					...replacements
+				}
+			});
+		}
+	};
+}
+//#endregion
+//#region src/componentHarness/host.ts
+const COMPONENT_HOST_ROUTE = "mpcore-test/component-host/index";
+const COMPONENT_SUBJECT_SELECTOR = "#mpcore-subject";
+function createSlotMarkup(slots) {
+	return Object.entries(slots).map(([name, content]) => {
+		if (!/^[a-z_]\w*(?:-\w+)*$/i.test(name)) throw new TypeError("Component slot names must be valid WXML attribute names.");
+		return name === "default" ? content : `<block slot="${name}">${content}</block>`;
+	}).join("");
+}
+/** 宿主模板读取每轮订阅和属性名称，主体节点位置保持不变。 */
+function createComponentHostProject(project, componentPath, options, events) {
+	const root = project.miniprogramRootPath;
+	const hostRoot = path.resolve(root, COMPONENT_HOST_ROUTE);
+	const templatePath = `${hostRoot}.wxml`;
+	const propertyNames = /* @__PURE__ */ new Set();
+	const addPropertyNames = (names) => {
+		for (const name of names) if (!/^[a-z_]\w*(?:-\w+)*$/i.test(name)) throw new TypeError("Component property names must be valid WXML attribute names.");
+		names.forEach((name) => propertyNames.add(name));
+	};
+	addPropertyNames(Object.keys(options.properties ?? {}));
+	const slots = createSlotMarkup(options.slots ?? {});
+	const fixed = createMemoryArtifactSource([
+		[path.resolve(root, "app.json"), JSON.stringify({ pages: [COMPONENT_HOST_ROUTE] })],
+		[path.resolve(root, "app.js"), "App({})\n"],
+		[`${hostRoot}.json`, JSON.stringify({ usingComponents: { "mpcore-subject": `/${normalizeComponentPath(componentPath)}` } })],
+		[`${hostRoot}.js`, `Page({
+  data: { __mpcoreMounted: true, __mpcoreProperties: ${serializeComponentData(options.properties ?? {}, "Component properties").replaceAll("<", "\\u003c")} },
+  __mpcoreRecordEvent(event) { globalThis.__mpcoreRecordEvent(event.type, event.detail, event) }
+})\n`]
+	]);
+	return {
+		addPropertyNames,
+		project: createProjectDescriptor({
+			appConfig: { pages: [COMPONENT_HOST_ROUTE] },
+			appConfigPath: path.resolve(root, "app.json"),
+			artifactSource: createOverlayArtifactSource({
+				has: (filePath) => filePath === templatePath || fixed.has(filePath),
+				readText(filePath) {
+					if (filePath !== templatePath) return fixed.readText(filePath);
+					return `<mpcore-subject wx:if="{{__mpcoreMounted}}" id="mpcore-subject" ${[...propertyNames].map((key) => `${key}='{{__mpcoreProperties[${JSON.stringify(key)}]}}'`).join(" ")} ${events.names().map((name) => `bind:${name}="__mpcoreRecordEvent"`).join(" ")}>${slots}</mpcore-subject>`;
+				}
+			}, createComponentOverrides(project, options.usingComponents)),
+			miniprogramRoot: project.miniprogramRoot,
+			miniprogramRootPath: root,
+			plugins: project.plugins,
+			projectConfigFiles: project.projectConfigFiles,
+			projectPath: project.projectPath
+		})
+	};
+}
+//#endregion
+//#region src/componentHarness/index.ts
+/** 复用宿主会话更新与移除真实组件，不重新构造主体实例。 */
+function createComponentRenderResult(base, session, settle, host, events) {
+	let mounted = true;
+	let unmounting;
+	const assertMounted = () => {
+		session.assertActive();
+		if (!mounted) throw new Error("The test component has been unmounted.");
+	};
+	events.setChangeHandler(() => {
+		session.renderCurrentPage();
+	});
+	const refresh = async () => {
+		await settle();
+		await base.screen.refresh();
+	};
+	return Object.assign(base, {
+		off: events.off,
+		on(eventName, listener) {
+			assertMounted();
+			return events.on(eventName, listener);
+		},
+		async setData(data) {
+			assertMounted();
+			const payload = cloneComponentData(data, "Component data");
+			const subject = session.selectComponent(COMPONENT_SUBJECT_SELECTOR);
+			if (!subject) throw new Error("The test component is no longer mounted.");
+			await new Promise((resolve) => {
+				subject.setData(payload, resolve);
+			});
+			await refresh();
+		},
+		async setProperties(properties) {
+			assertMounted();
+			const payload = cloneComponentData(properties, "Component properties");
+			host.addPropertyNames(Object.keys(payload));
+			const previous = await base.page.data("__mpcoreProperties");
+			await base.page.setData({ __mpcoreProperties: {
+				...previous,
+				...payload
+			} });
+			await refresh();
+		},
+		async unmount() {
+			if (unmounting) return await unmounting;
+			session.assertActive();
+			mounted = false;
+			unmounting = (async () => {
+				try {
+					await base.page.setData({ __mpcoreMounted: false });
+				} finally {
+					events.clear();
+				}
+				await refresh();
+			})();
+			return await unmounting;
+		}
+	});
+}
+//#endregion
+//#region src/componentHarness/events.ts
+/** 将事件订阅映射到宿主声明绑定，不拦截组件 triggerEvent。 */
+function createComponentEvents(options = {}) {
+	const subscriptions = /* @__PURE__ */ new Map();
+	const log = /* @__PURE__ */ new Map();
+	let changed = () => {};
+	function normalizeEventName(eventName) {
+		if (!/^[\w:.-]+$/.test(eventName)) throw new TypeError("Component event names must contain only letters, numbers, underscores, colons, dots or hyphens.");
+		return eventName;
+	}
+	function on(eventName, listener) {
+		const name = normalizeEventName(eventName);
+		const listeners = subscriptions.get(name) ?? /* @__PURE__ */ new Map();
+		const token = Symbol(name);
+		subscriptions.set(name, listeners);
+		listeners.set(token, listener);
+		changed();
+		let active = true;
+		return () => {
+			if (active) {
+				active = false;
+				listeners.delete(token);
+				if (listeners.size === 0 && subscriptions.get(name) === listeners) subscriptions.delete(name);
+				changed();
+			}
+		};
+	}
+	function off(eventName, listener) {
+		if (listener === void 0) subscriptions.delete(eventName);
+		else {
+			const listeners = subscriptions.get(eventName);
+			for (const [token, registered] of listeners ?? []) if (registered === listener) listeners?.delete(token);
+			if (listeners?.size === 0) subscriptions.delete(eventName);
+		}
+		changed();
+	}
+	for (const name of options.events ?? []) on(name);
+	for (const [name, listener] of Object.entries(options.on ?? {})) on(name, listener);
+	return {
+		clear() {
+			subscriptions.clear();
+			changed = () => {};
+		},
+		emitted: (name) => [...log.get(name) ?? []],
+		names: () => [...subscriptions.keys()],
+		off,
+		on,
+		receive(name, detail, event) {
+			const listeners = subscriptions.get(name);
+			if (!listeners) return;
+			const entries = log.get(name) ?? [];
+			entries.push(detail);
+			log.set(name, entries);
+			for (const listener of [...listeners.values()]) listener?.(detail, event);
+		},
+		setChangeHandler(handler) {
+			changed = handler;
+		}
+	};
+}
+//#endregion
+//#region src/snapshot/tree.ts
+const EVENT_ATTRIBUTE = /^(?:(?:capture-)?(?:bind|catch)|mut-bind)(?::[\w:.-]+|\w+)$/;
+const SCOPED_STYLE_ATTRIBUTE = /^data-v-[a-f\d]+$/i;
+function snapshotAttributes(attributes) {
+	return Object.fromEntries(Object.entries(attributes).filter(([name]) => !name.startsWith("data-sim-") && !SCOPED_STYLE_ATTRIBUTE.test(name)).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([name, value]) => [name, EVENT_ATTRIBUTE.test(name) && value ? "[handler]" : value]));
+}
+/** 保留逻辑结构、文本和公开属性，仅移除宿主内部标识并隐藏事件方法名。 */
+function createMiniProgramTreeSnapshot(node) {
+	if (node.type === "text") return { text: node.text };
+	return {
+		attributes: snapshotAttributes(node.attrs),
+		children: node.children.map(createMiniProgramTreeSnapshot),
+		tag: node.tag ?? "root"
+	};
+}
+//#endregion
 //#region src/screen/helpers.ts
 function matchesText(value, matcher) {
 	if (typeof matcher === "string") return value === matcher;
@@ -96,7 +348,7 @@ function findNodeById(root, nodeId) {
 	}
 }
 //#endregion
-//#region src/screen/index.ts
+//#region src/screen/node.ts
 var MiniProgramNode = class {
 	owner;
 	nodeId;
@@ -128,16 +380,25 @@ var MiniProgramNode = class {
 	getAttribute(name) {
 		return this.current.attrs[name];
 	}
+	/** 返回当前节点的稳定语义树，卸载后的节点不能生成快照。 */
+	snapshot() {
+		return createMiniProgramTreeSnapshot(this.current);
+	}
 };
+//#endregion
+//#region src/screen/index.ts
 var MiniProgramScreen = class MiniProgramScreen {
 	page;
-	currentSnapshot;
+	snapshotStore;
 	rootNodeId;
 	constructor(page, snapshot, rootNodeId) {
 		this.page = page;
-		this.currentSnapshot = snapshot;
+		this.snapshotStore = { current: snapshot };
 		this.rootNodeId = rootNodeId;
 	}
+	get currentSnapshot() {
+		return this.snapshotStore.current;
+	}
 	get root() {
 		this.page.assertActive();
 		if (!this.rootNodeId) return this.currentSnapshot.root;
@@ -177,18 +438,27 @@ var MiniProgramScreen = class MiniProgramScreen {
 		}
 	}
 	hasNode(nodeId) {
+		this.page.assertActive();
 		return Boolean(findNodeById(this.currentSnapshot.root, nodeId));
 	}
 	resolveNode(nodeId) {
+		this.page.assertActive();
 		const node = findNodeById(this.currentSnapshot.root, nodeId);
 		if (!node) throw new Error("The mini-program node is no longer present in the rendered tree.");
 		return node;
 	}
 	async refresh() {
-		this.currentSnapshot = await this.page.snapshot();
+		this.snapshotStore.current = await this.page.snapshot();
 	}
 	within(node) {
-		return new MiniProgramScreen(this.page, this.currentSnapshot, node.nodeId);
+		this.resolveNode(node.nodeId);
+		const screen = new MiniProgramScreen(this.page, this.currentSnapshot, node.nodeId);
+		screen.snapshotStore = this.snapshotStore;
+		return screen;
+	}
+	/** 返回用于断言的稳定语义树，不包含页面数据与内部节点身份。 */
+	snapshot() {
+		return createMiniProgramTreeSnapshot(this.root);
 	}
 	queryAllByText(matcher) {
 		const matches = this.allElements().filter((node) => {
@@ -338,54 +608,6 @@ var MiniProgramUser = class {
 };
 //#endregion
 //#region src/project.ts
-const COMPONENT_HOST_ROUTE = "__mpcore__/component-host/index";
-function normalizeComponentPath(componentPath) {
-	return componentPath.trim().replace(/^\/+/, "").replace(/\.(?:js|json|wxml)$/, "");
-}
-function serializeProperties(properties) {
-	try {
-		return JSON.stringify(properties).replaceAll("<", "\\u003c");
-	} catch (error) {
-		throw new TypeError("Component properties must be serializable.", { cause: error });
-	}
-}
-function createSlotMarkup(slots) {
-	return Object.entries(slots).map(([name, content]) => {
-		return name === "default" ? content : `<block slot="${name}">${content}</block>`;
-	}).join("");
-}
-function createComponentHostProject(project, componentPath, options) {
-	const root = project.miniprogramRootPath;
-	const eventEntries = Object.keys(options.on ?? {}).map((eventName, index) => ({
-		eventName,
-		methodName: `__mpcoreEvent${index}`
-	}));
-	const eventMethods = eventEntries.map(({ eventName, methodName }) => {
-		return `${methodName}(event) { globalThis.__mpcoreRecordEvent(${JSON.stringify(eventName)}, event?.detail, event) }`;
-	}).join(",\n");
-	const propertyBindings = Object.keys(options.properties ?? {}).map((key) => `${key}="{{__mpcoreProperties.${key}}}"`).join(" ");
-	const eventBindings = eventEntries.map(({ eventName, methodName }) => `bind:${eventName}="${methodName}"`).join(" ");
-	const hostRoot = path.resolve(root, COMPONENT_HOST_ROUTE);
-	const overlay = createMemoryArtifactSource([
-		[path.resolve(root, "app.json"), JSON.stringify({ pages: [COMPONENT_HOST_ROUTE] })],
-		[path.resolve(root, "app.js"), "App({})\n"],
-		[`${hostRoot}.json`, JSON.stringify({ usingComponents: { "mpcore-subject": `/${normalizeComponentPath(componentPath)}` } })],
-		[`${hostRoot}.js`, `Page({
-  data: { __mpcoreProperties: ${serializeProperties(options.properties ?? {})} },
-  ${eventMethods}
-})\n`],
-		[`${hostRoot}.wxml`, `<mpcore-subject id="mpcore-subject" ${propertyBindings} ${eventBindings}>${createSlotMarkup(options.slots ?? {})}</mpcore-subject>`]
-	]);
-	return createProjectDescriptor({
-		appConfig: { pages: [COMPONENT_HOST_ROUTE] },
-		appConfigPath: path.resolve(root, "app.json"),
-		artifactSource: createOverlayArtifactSource(overlay, project.artifactSource),
-		miniprogramRoot: project.miniprogramRoot,
-		miniprogramRootPath: root,
-		projectConfigFiles: project.projectConfigFiles,
-		projectPath: project.projectPath
-	});
-}
 function formatDiagnostic(entry) {
 	return entry.args.map((arg) => {
 		if (arg && typeof arg === "object" && "message" in arg && typeof arg.message === "string") return "stack" in arg && typeof arg.stack === "string" ? arg.stack : arg.message;
@@ -405,14 +627,10 @@ var MiniProgramTestProject = class {
 			projectPath: options.artifact.projectPath
 		}) : loadProject(options.artifact.projectPath);
 	}
-	async render(project, route, on = {}) {
-		const eventLog = /* @__PURE__ */ new Map();
+	async render(project, route, events = createComponentEvents()) {
 		const session = createHeadlessSession({
 			globals: { __mpcoreRecordEvent(eventName, detail, event) {
-				const entries = eventLog.get(eventName) ?? [];
-				entries.push(detail);
-				eventLog.set(eventName, entries);
-				on?.[eventName]?.(detail, event);
+				events.receive(eventName, detail, event);
 			} },
 			project,
 			strictHostMocks: true
@@ -438,26 +656,36 @@ var MiniProgramTestProject = class {
 			close: async () => {
 				if (closed) return;
 				closed = true;
-				session.close();
-				this.renders.delete(result);
+				try {
+					session.close();
+				} finally {
+					events.clear();
+					this.renders.delete(result);
+				}
 				assertDiagnostics();
 			},
 			diagnostics: () => session.getDiagnostics(),
-			emitted: (eventName) => [...eventLog.get(eventName) ?? []],
+			emitted: events.emitted,
 			page,
 			screen,
 			user
 		};
 		this.renders.add(result);
 		await settle();
-		return result;
+		return {
+			result,
+			session,
+			settle
+		};
 	}
 	async renderPage(route) {
-		return await this.render(this.baseProject, route);
+		return (await this.render(this.baseProject, route)).result;
 	}
 	async renderComponent(componentPath, options = {}) {
-		const project = createComponentHostProject(this.baseProject, componentPath, options);
-		return await this.render(project, `/${COMPONENT_HOST_ROUTE}`, options.on);
+		const events = createComponentEvents(options);
+		const host = createComponentHostProject(this.baseProject, componentPath, options, events);
+		const { result, session, settle } = await this.render(host.project, `/${COMPONENT_HOST_ROUTE}`, events);
+		return createComponentRenderResult(result, session, settle, host, events);
 	}
 	async close() {
 		let firstError;
@@ -480,4 +708,19 @@ function createTestProject(options) {
 	});
 }
 //#endregion
-export { MiniProgramNode, MiniProgramScreen, MiniProgramTestProject, MiniProgramUser, applyWxMock, artifactFromProject, createTestProject, createWxMock, mpcoreMatchers, toBeInTheMiniProgram, toHaveAttribute, toHaveDataset, toHaveEmitted, toHaveTextContent, wechat };
+//#region src/snapshot/index.ts
+/** 将查询对象或完整诊断快照显式转换为适合稳定断言的语义树。 */
+function toMiniProgramSnapshot(source) {
+	return source instanceof MiniProgramScreen || source instanceof MiniProgramNode ? source.snapshot() : createMiniProgramTreeSnapshot(source.root);
+}
+/** 通过 Vitest/Jest 的公开 serializer 接口，仅格式化本包的查询对象。 */
+const mpcoreSnapshotSerializer = {
+	test(value) {
+		return value instanceof MiniProgramScreen || value instanceof MiniProgramNode;
+	},
+	serialize(value) {
+		return JSON.stringify(toMiniProgramSnapshot(value), null, 2);
+	}
+};
+//#endregion
+export { MiniProgramNode, MiniProgramScreen, MiniProgramTestProject, MiniProgramUser, applyWxMock, artifactFromProject, createTestProject, createWxMock, mpcoreMatchers, mpcoreSnapshotSerializer, toBeInTheMiniProgram, toHaveAttribute, toHaveDataset, toHaveEmitted, toHaveTextContent, toMiniProgramSnapshot, wechat };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mpcore/test",
   "type": "module",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Testing Library-style utilities for compiled WeChat mini-program artifacts",
   "author": "ice breaker <1324318532@qq.com>",
   "license": "MIT",
@@ -42,7 +42,7 @@
     "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "dependencies": {
-    "@mpcore/simulator": "1.0.0"
+    "@mpcore/simulator": "1.1.0"
   },
   "publishConfig": {
     "access": "public",