@mpcore/vitest 0.2.7 → 1.1.0

package/README.md

@@ -1,16 +1,44 @@
 # @mpcore/vitest
 
-Vitest 5 integration for `@mpcore/test`. Add `mpcoreTest()` to the Vitest plugin list, then use `createMpcoreTest()` for an isolated mini-program project fixture per test.
+Vitest 5 integration for `@mpcore/test`. Import the configuration plugin from `@mpcore/vitest/config`; this entry does not load the test worker's `expect` or `test`. Test files import fixtures from `@mpcore/vitest`, using the same Vitest peer instance as setup and matchers.
+
+Configure an explicit artifact factory. The integration does not depend on a particular compiler; for weapp-vite:
 
 ```ts
-import { createMpcoreTest } from '@mpcore/vitest'
+// vitest.config.ts
+import { mpcoreTest } from '@mpcore/vitest/config'
+import { buildWeappViteTestArtifact, watchWeappViteTestArtifact } from '@mpcore/weapp-vite'
+import { defineConfig } from 'vitest/config'
 
-const test = createMpcoreTest({
-  artifact: { projectPath: process.cwd() },
+const options = { cwd: import.meta.dirname, platform: 'weapp' as const }
+
+export default defineConfig({
+  plugins: [mpcoreTest({
+    artifact: {
+      build: () => buildWeappViteTestArtifact(options),
+      watch: callbacks => watchWeappViteTestArtifact({ ...options, ...callbacks }),
+    },
+  })],
 })
+```
+
+Run mode calls `build` once per project. Watch mode calls `watch` instead; the returned watcher owns its initial build and exposes that artifact. After a successful update, the plugin provides the new artifact and asks the current runner to rerun only that project's specifications. Build and scheduling errors are recorded and printed by the runner. Closing waits for startup, pending updates and the owned watcher; it does not start or stop another test process.
+
+Vite+ uses the same plugin and `vp test`; import `defineConfig` from `vite-plus` in that host's configuration and keep its Vitest peer aligned with the runner.
+
+Each test receives an isolated mini-program runtime from the injected artifact:
+
+```ts
+import { createMpcoreTest } from '@mpcore/vitest'
+
+const test = createMpcoreTest()
 
 test('renders a page', async ({ mpcore, expect }) => {
   const result = await mpcore.renderPage('/pages/index/index')
   expect(result.screen.getByText('ready')).toBeInTheMiniProgram()
 })
 ```
+
+`createMpcoreTest({ artifact: { projectPath: process.cwd() } })` still accepts an existing artifact directly. `createVitestProject()` also uses the configured artifact when omitted, and closes its runtime with the current test. Optional host mocks and `failOnConsoleError` can be passed without replacing the injected artifact. Calling either helper without a configured or explicit artifact reports an actionable error.
+
+Setup also registers the semantic tree snapshot serializer from `@mpcore/test`. Use `expect(result.screen).toMatchSnapshot()` or snapshot an individual node. Snapshots preserve public tree and event-binding semantics while removing runtime IDs, style scope markers and generated handler names. Full diagnostic snapshots returned by `page.snapshot()` remain unchanged; use `toMiniProgramSnapshot()` explicitly to serialize one.

package/dist/config-1SyUfssv.mjs

@@ -0,0 +1,77 @@
+import { fileURLToPath } from "node:url";
+//#region src/artifact.ts
+const MPCORE_ARTIFACT_KEY = "mpcoreArtifact";
+/** 每次 configureVitest 调用只持有当前 project 的 watcher 和重跑队列。 */
+async function configureArtifact(factory, { project, vitest }) {
+	let closed = false;
+	let ready = false;
+	let earlyArtifact;
+	let watcher;
+	let pending = Promise.resolve();
+	let starting = Promise.resolve();
+	let closing;
+	const onError = (error) => {
+		if (!closed) {
+			vitest.state.catchError(error, "Mpcore Artifact Error");
+			vitest.logger.printError(error);
+		}
+	};
+	const onRebuilt = (artifact) => {
+		if (closed) return Promise.resolve();
+		if (!ready) {
+			earlyArtifact = artifact;
+			return Promise.resolve();
+		}
+		pending = pending.then(async () => {
+			if (closed) return;
+			project.provide(MPCORE_ARTIFACT_KEY, artifact);
+			const specifications = await vitest.globTestSpecifications();
+			if (!closed) await vitest.rerunTestSpecifications(specifications.filter((specification) => specification.project === project));
+		}).catch(onError);
+		return pending;
+	};
+	vitest.onClose(() => {
+		return closing ??= (async () => {
+			closed = true;
+			await starting.catch(() => {});
+			const ownedWatcher = watcher;
+			watcher = void 0;
+			const errors = (await Promise.allSettled([Promise.resolve().then(() => ownedWatcher?.close()), pending])).filter((result) => result.status === "rejected").map((result) => result.reason);
+			if (errors.length) throw new AggregateError(errors, "Mpcore artifact cleanup failed");
+		})();
+	});
+	starting = (async () => {
+		if (closed) return;
+		let artifact;
+		if (vitest.config.watch && factory.watch) {
+			watcher = await factory.watch({
+				onRebuilt,
+				onError
+			});
+			artifact = watcher.artifact;
+		} else artifact = await factory.build();
+		if (!closed) {
+			project.provide(MPCORE_ARTIFACT_KEY, earlyArtifact ?? artifact);
+			ready = true;
+		}
+	})();
+	await starting;
+}
+//#endregion
+//#region src/config.ts
+/** 配置入口仅依赖 runner 的公开类型，不提前加载测试线程的 expect/test。 */
+function mpcoreTest(options = {}) {
+	const setupFile = fileURLToPath(new URL("./setup.mjs", import.meta.url));
+	return {
+		name: "mpcore:vitest",
+		config(config) {
+			const existing = config.test?.setupFiles;
+			return { test: { setupFiles: (typeof existing === "string" ? [existing] : existing ?? []).includes(setupFile) ? [] : [setupFile] } };
+		},
+		async configureVitest(context) {
+			if (options.artifact) await configureArtifact(options.artifact, context);
+		}
+	};
+}
+//#endregion
+export { MPCORE_ARTIFACT_KEY as n, mpcoreTest as t };

package/dist/config-D3NKpUBr.d.mts

@@ -0,0 +1,43 @@
+import { MiniProgramArtifact } from "@mpcore/test";
+import { VitestPluginContext } from "vitest/node";
+//#region src/artifact.d.ts
+interface MpcoreArtifactWatcher {
+  artifact: MiniProgramArtifact;
+  close: () => void | Promise<void>;
+}
+interface MpcoreArtifactWatchCallbacks {
+  onRebuilt: (artifact: MiniProgramArtifact) => Promise<void>;
+  onError: (error: unknown) => void;
+}
+interface MpcoreArtifactFactory {
+  build: () => MiniProgramArtifact | Promise<MiniProgramArtifact>;
+  /** watcher 负责首次构建并返回初始产物，避免 run 与 watch 重复构建。 */
+  watch?: (callbacks: MpcoreArtifactWatchCallbacks) => MpcoreArtifactWatcher | Promise<MpcoreArtifactWatcher>;
+}
+declare module 'vitest' {
+  interface ProvidedContext {
+    mpcoreArtifact: MiniProgramArtifact;
+  }
+}
+//#endregion
+//#region src/config.d.ts
+interface MpcoreVitestOptions {
+  artifact?: MpcoreArtifactFactory;
+}
+interface MpcoreVitestPlugin {
+  config: (config: {
+    test?: {
+      setupFiles?: string | string[];
+    };
+  }) => {
+    test: {
+      setupFiles: string[];
+    };
+  };
+  configureVitest: (context: VitestPluginContext) => Promise<void>;
+  name: string;
+}
+/** 配置入口仅依赖 runner 的公开类型，不提前加载测试线程的 expect/test。 */
+declare function mpcoreTest(options?: MpcoreVitestOptions): MpcoreVitestPlugin;
+//#endregion
+export { MpcoreArtifactWatchCallbacks as a, MpcoreArtifactFactory as i, MpcoreVitestPlugin as n, MpcoreArtifactWatcher as o, mpcoreTest as r, MpcoreVitestOptions as t };

package/dist/config.d.mts

@@ -0,0 +1,2 @@
+import { a as MpcoreArtifactWatchCallbacks, i as MpcoreArtifactFactory, n as MpcoreVitestPlugin, o as MpcoreArtifactWatcher, r as mpcoreTest, t as MpcoreVitestOptions } from "./config-D3NKpUBr.mjs";
+export { type MpcoreArtifactFactory, type MpcoreArtifactWatchCallbacks, type MpcoreArtifactWatcher, MpcoreVitestOptions, MpcoreVitestPlugin, mpcoreTest };

package/dist/config.mjs

@@ -0,0 +1 @@
+export { t as mpcoreTest } from "./config-1SyUfssv.mjs";

package/dist/index.d.mts

@@ -1,26 +1,15 @@
+import { a as MpcoreArtifactWatchCallbacks, i as MpcoreArtifactFactory, n as MpcoreVitestPlugin, o as MpcoreArtifactWatcher, r as mpcoreTest, t as MpcoreVitestOptions } from "./config-D3NKpUBr.mjs";
 import { CreateTestProjectOptions, MiniProgramEmissionSource, MiniProgramNode, MiniProgramTestProject } from "@mpcore/test";
 export * from "@mpcore/test";
 //#region src/index.d.ts
 export interface MpcoreVitestFixture {
   mpcore: MiniProgramTestProject;
 }
-export interface MpcoreVitestPlugin {
-  config: (config: {
-    test?: {
-      setupFiles?: string | string[];
-    };
-  }) => {
-    test: {
-      setupFiles: string[];
-    };
-  };
-  name: string;
-}
-export declare function mpcoreTest(): MpcoreVitestPlugin;
-export declare function createMpcoreTest(options: CreateTestProjectOptions): import("vitest").TestAPI<{
+export type MpcoreTestProjectOptions = Omit<CreateTestProjectOptions, 'artifact'> & Partial<Pick<CreateTestProjectOptions, 'artifact'>>;
+export declare function createMpcoreTest(options?: MpcoreTestProjectOptions): import("vitest").TestAPI<{
   mpcore: MiniProgramTestProject;
 }>;
-export declare function createVitestProject(options: CreateTestProjectOptions): MiniProgramTestProject;
+export declare function createVitestProject(options?: MpcoreTestProjectOptions): MiniProgramTestProject;
 export declare function registerMpcoreMatchers(): void;
 declare module 'vitest' {
   interface Matchers<R, T> {
@@ -31,4 +20,5 @@ declare module 'vitest' {
     toHaveTextContent: T extends MiniProgramNode ? (value: string | RegExp) => R : never;
   }
 }
-//#endregion
+//#endregion
+export { type MpcoreArtifactFactory, type MpcoreArtifactWatchCallbacks, type MpcoreArtifactWatcher, type MpcoreVitestOptions, type MpcoreVitestPlugin, mpcoreTest };

package/dist/index.mjs

@@ -1,24 +1,19 @@
-import { fileURLToPath } from "node:url";
+import { t as mpcoreTest } from "./config-1SyUfssv.mjs";
 import { createTestProject, mpcoreMatchers } from "@mpcore/test";
-import { expect, onTestFinished, test } from "vitest";
+import { expect, inject, onTestFinished, test } from "vitest";
 export * from "@mpcore/test";
 //#region src/index.ts
-function toList(value) {
-	if (!value) return [];
-	return Array.isArray(value) ? value : [value];
-}
-function mpcoreTest() {
-	const setupFile = fileURLToPath(new URL("./setup.mjs", import.meta.url));
+function projectOptions(options = {}) {
+	const artifact = options.artifact ?? inject("mpcoreArtifact");
+	if (!artifact) throw new Error("No mpcore artifact was provided. Configure mpcoreTest({ artifact }) from @mpcore/vitest/config or pass an explicit artifact.");
 	return {
-		name: "mpcore:vitest",
-		config(config) {
-			return { test: { setupFiles: [...toList(config.test?.setupFiles), setupFile] } };
-		}
+		...options,
+		artifact
 	};
 }
 function createMpcoreTest(options) {
 	return test.extend({ mpcore: async ({}, use) => {
-		const project = createTestProject(options);
+		const project = createTestProject(projectOptions(options));
 		try {
 			await use(project);
 		} finally {
@@ -27,7 +22,7 @@ function createMpcoreTest(options) {
 	} });
 }
 function createVitestProject(options) {
-	const project = createTestProject(options);
+	const project = createTestProject(projectOptions(options));
 	onTestFinished(async () => {
 		await project.close();
 	});

package/dist/setup.mjs

@@ -1,6 +1,7 @@
-import { mpcoreMatchers } from "@mpcore/test";
+import { mpcoreMatchers, mpcoreSnapshotSerializer } from "@mpcore/test";
 import { expect } from "vitest";
 //#region src/setup.ts
 expect.extend(mpcoreMatchers);
+expect.addSnapshotSerializer(mpcoreSnapshotSerializer);
 //#endregion
 export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mpcore/vitest",
   "type": "module",
-  "version": "0.2.7",
+  "version": "1.1.0",
   "description": "Vitest integration for @mpcore/test",
   "author": "ice breaker <1324318532@qq.com>",
   "license": "MIT",
@@ -31,6 +31,10 @@
     "./setup": {
       "types": "./dist/setup.d.mts",
       "import": "./dist/setup.mjs"
+    },
+    "./config": {
+      "types": "./dist/config.d.mts",
+      "import": "./dist/config.mjs"
     }
   },
   "main": "./dist/index.mjs",
@@ -41,26 +45,33 @@
     "dist"
   ],
   "engines": {
-    "node": "^20.19.0 || >=22.12.0"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "peerDependencies": {
     "vitest": ">=5.0.0"
   },
   "dependencies": {
-    "@mpcore/test": "0.1.15"
+    "@mpcore/test": "1.1.0"
   },
   "devDependencies": {
-    "vitest": "~5.0.2"
+    "vitest": "~5.0.5"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
+  "tsd": {
+    "compilerOptions": {
+      "module": "NodeNext",
+      "moduleResolution": "NodeNext"
+    }
+  },
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown -w",
     "test": "vitest run",
-    "test:types": "pnpm build && tsd",
+    "test:types": "pnpm build && pnpm run test:types:check",
+    "test:types:check": "tsd --files \"test-d/**/*.test-d.ts\"",
     "typecheck": "tsc --noEmit"
   }
 }