feat: add tegg vitest adapter workspace

.gitignore

@@ -11,6 +11,7 @@ run
 .DS_Store
 .tmp
 .vscode
+codex-logs/
 
 package-lock.json
 yarn.lock

core/vitest/README.md

@@ -0,0 +1,64 @@
+# @eggjs/tegg-vitest
+
+Vitest adapter that provides tegg context injection and lifecycle handling via a custom Vitest runner.
+
+## Install
+
+This package lives in the tegg monorepo workspace.
+
+## Usage
+
+1. Create a Vitest setup file that calls `configureTeggRunner`:
+
+```ts
+// vitest.setup.ts
+import path from 'path';
+import mm from 'egg-mock';
+import { configureTeggRunner } from '@eggjs/tegg-vitest';
+
+const app = mm.app({
+  baseDir: path.join(__dirname, 'fixtures/apps/my-app'),
+  framework: require.resolve('egg'),
+});
+
+configureTeggRunner({
+  getApp: () => app,
+  restoreMocks: true,
+  parallel: process.env.VITEST_WORKER_ID != null,
+});
+```
+
+2. Wire it in `vitest.config.ts` with the custom runner:
+
+```ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    setupFiles: ['./vitest.setup.ts'],
+    runner: '@eggjs/tegg-vitest/runner',
+  },
+});
+```
+
+## Options
+
+- `getApp`: Provide a custom app getter. Default: `require('egg-mock/bootstrap').app`.
+- `parallel`: Skip auto `app.close()` when running in parallel mode. Default: auto-detected from `VITEST_WORKER_ID`.
+- `restoreMocks`: Restore mocks after each test (defaults to true).
+
+## Lifecycle & Context Injection
+
+The custom runner extends Vitest's `VitestTestRunner` and manages tegg context at the runner level:
+
+- **`importFile` (collection phase)**: Captures per-file config from `configureTeggRunner()` and calls `app.ready()`.
+- **`onBeforeRunSuite` (file suite)**: Creates a suite-scoped `ctx` via `app.mockContext()`, overrides `ctxStorage.getStore()`, and opens a held `beginModuleScope` that stays alive for the entire file.
+- **`onBeforeRunTask` (per test)**: Creates a per-test `ctx` and opens a held `beginModuleScope` for the test.
+- **`onAfterRunTask`**: Releases the test scope, restores mocks, and restores `ctxStorage.getStore()` back to the suite `ctx`.
+- **`onAfterRunSuite`**: Releases the suite scope, restores original `getStore()`, and calls `app.close()` unless `parallel` is true.
+
+## Limitations
+
+- Context is managed at the **file suite** level. `egg-mock`'s Mocha runner patch can switch context at the **`describe` suite** level. If your tests rely on describe-scoped suite context, you must manage that manually.
+- If `getApp` throws or returns `undefined`, the adapter will run tests without context injection.

core/vitest/index.ts

@@ -0,0 +1 @@
+export * from './src';

core/vitest/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@eggjs/tegg-vitest",
+  "version": "3.72.0",
+  "description": "Vitest adapter for tegg context injection",
+  "keywords": [
+    "egg",
+    "tegg",
+    "vitest",
+    "test",
+    "adapter"
+  ],
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./runner": {
+      "types": "./dist/runner.d.ts",
+      "default": "./dist/runner.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "typings": "dist/index.d.ts",
+  "scripts": {
+    "clean": "tsc -b --clean",
+    "tsc:pub": "ut run clean && tsc -p ./tsconfig.pub.json",
+    "test": "node --eval \"process.exit(parseInt(process.versions.node) < 18 ? 0 : 1)\" || vitest run"
+  },
+  "author": "killagu <killa123@126.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/eggjs/tegg",
+  "bugs": {
+    "url": "https://github.com/eggjs/tegg/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eggjs/tegg.git",
+    "directory": "core/vitest"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "egg-mock": "^5.5.0"
+  },
+  "peerDependencies": {
+    "vitest": "^1.6.0 || ^2.0.0 || ^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.2.4",
+    "typescript": "^5.0.4",
+    "vitest": "^1.6.0",
+    "egg": "^3.9.1",
+    "egg-tracer": "^2.0.0"
+  }
+}

core/vitest/runner.ts

@@ -0,0 +1 @@
+export { default } from './src/runner';

core/vitest/src/index.ts

@@ -0,0 +1,17 @@
+import {
+  defaultGetApp,
+} from './shared';
+import type { TeggVitestAdapterOptions } from './shared';
+
+export type { EggMockApp, TeggVitestAdapterOptions } from './shared';
+
+/**
+ * Configure the custom Vitest runner (used via globalThis.__teggVitestConfig).
+ * Call this in a setupFile and set `runner` in vitest.config.ts to use the runner approach.
+ */
+export function configureTeggRunner(options: TeggVitestAdapterOptions = {}) {
+  (globalThis as any).__teggVitestConfig = {
+    restoreMocks: options.restoreMocks ?? true,
+    getApp: options.getApp ?? defaultGetApp,
+  };
+}

core/vitest/src/runner.ts

@@ -0,0 +1,236 @@
+import { VitestTestRunner } from 'vitest/runners';
+import type { Suite, Task, File } from 'vitest';
+import {
+  debugLog,
+  defaultGetApp,
+  restoreEggMocksIfNeeded,
+} from './shared';
+import type { EggMockApp } from './shared';
+
+interface TeggRunnerConfig {
+  restoreMocks: boolean;
+  getApp: () => Promise<EggMockApp | undefined> | EggMockApp | undefined;
+}
+
+interface HeldScope {
+  scopePromise: Promise<void>;
+  endScope: () => void;
+}
+
+interface FileAppState {
+  app: EggMockApp;
+  config: TeggRunnerConfig;
+}
+
+interface FileScopeState {
+  app: EggMockApp;
+  config: TeggRunnerConfig;
+  suiteCtx: any;
+  suiteScope: HeldScope | null;
+}
+
+interface TaskScopeState {
+  testScope: HeldScope | null;
+  filepath: string;
+}
+
+/**
+ * Create a held beginModuleScope: starts the scope and waits until init() is
+ * complete (the inner fn starts executing), then returns the held scope.
+ * The scope stays alive until endScope() is called.
+ */
+async function createHeldScope(ctx: any): Promise<HeldScope> {
+  let endScope!: () => void;
+  const gate = new Promise<void>(resolve => {
+    endScope = resolve;
+  });
+
+  let scopeReady!: () => void;
+  const readyPromise = new Promise<void>(resolve => {
+    scopeReady = resolve;
+  });
+
+  const scopePromise = ctx.beginModuleScope(async () => {
+    // init() has completed at this point, signal readiness
+    scopeReady();
+    await gate;
+  });
+
+  // Race readyPromise against scopePromise: if beginModuleScope rejects
+  // before invoking the callback (so scopeReady is never called), the error
+  // propagates immediately instead of hanging forever on readyPromise.
+  // Promise.race attaches a rejection handler to scopePromise, so there are
+  // no unhandled rejections. scopePromise itself is preserved as-is for
+  // gate/endScope behavior in releaseHeldScope.
+  await Promise.race([ readyPromise, scopePromise ]);
+
+  return { scopePromise, endScope };
+}
+
+async function releaseHeldScope(scope: HeldScope | null) {
+  if (!scope) return;
+  scope.endScope();
+  await scope.scopePromise;
+}
+
+function isFileSuite(suite: Suite): suite is File {
+  return !suite.suite && !!suite.filepath;
+}
+
+function getTaskFilepath(task: Task): string | undefined {
+  return (task as any).file?.filepath;
+}
+
+export default class TeggVitestRunner extends VitestTestRunner {
+  private fileScopeMap = new Map<string, FileScopeState>();
+  private taskScopeMap = new Map<string, TaskScopeState>();
+  private fileAppMap = new Map<string, FileAppState>();
+  private warned = false;
+
+  /**
+   * Override importFile to capture per-file config set by configureTeggRunner()
+   * and await app.ready() during collection phase.
+   */
+  async importFile(filepath: string, source: Parameters<VitestTestRunner['importFile']>[1]): Promise<unknown> {
+    // Clear stale state for this file before re-collection in watch mode
+    if (source === 'collect') {
+      this.fileAppMap.delete(filepath);
+      this.warned = false;
+    }
+    // Clear any stale config before importing
+    delete (globalThis as any).__teggVitestConfig;
+
+    const result = await super.importFile(filepath, source);
+
+    if (source === 'collect') {
+      const rawConfig = (globalThis as any).__teggVitestConfig;
+      if (rawConfig) {
+        delete (globalThis as any).__teggVitestConfig;
+
+        const config: TeggRunnerConfig = {
+          restoreMocks: rawConfig.restoreMocks ?? true,
+          getApp: rawConfig.getApp ?? defaultGetApp,
+        };
+
+        debugLog(`captured config for ${filepath}`);
+
+        // Resolve app and await ready during collection
+        try {
+          const app = await config.getApp();
+          if (app) {
+            await app.ready();
+            this.fileAppMap.set(filepath, { app, config });
+            debugLog(`app ready for ${filepath}`);
+          }
+        } catch (err) {
+          if (!this.warned) {
+            this.warned = true;
+            // eslint-disable-next-line no-console
+            console.warn('[tegg-vitest] getApp failed, skip context injection.', err);
+          }
+        }
+      }
+    }
+
+    return result;
+  }
+
+  async onBeforeRunSuite(suite: Suite): Promise<void> {
+    if (isFileSuite(suite)) {
+      const filepath = suite.filepath!;
+      debugLog(`onBeforeRunSuite (file): ${filepath}`);
+
+      const fileApp = this.fileAppMap.get(filepath);
+      if (fileApp) {
+        const { app, config } = fileApp;
+
+        if (typeof app.mockContext === 'function' && app.ctxStorage) {
+          const suiteCtx = app.mockContext(undefined, {
+            mockCtxStorage: false,
+            reuseCtxStorage: false,
+          });
+          app.ctxStorage.enterWith(suiteCtx);
+
+          let suiteScope: HeldScope | null = null;
+          if (typeof suiteCtx.beginModuleScope === 'function') {
+            suiteScope = await createHeldScope(suiteCtx);
+            debugLog('suite held scope created');
+          }
+
+          this.fileScopeMap.set(filepath, { app, config, suiteCtx, suiteScope });
+          debugLog('file suite scope created');
+        }
+      }
+    }
+
+    await super.onBeforeRunSuite(suite);
+  }
+
+  async onAfterRunSuite(suite: Suite): Promise<void> {
+    if (isFileSuite(suite)) {
+      const filepath = suite.filepath!;
+      debugLog(`onAfterRunSuite (file): ${filepath}`);
+
+      const fileState = this.fileScopeMap.get(filepath);
+      if (fileState) {
+        await releaseHeldScope(fileState.suiteScope);
+        this.fileScopeMap.delete(filepath);
+      }
+      this.fileAppMap.delete(filepath);
+    }
+
+    await super.onAfterRunSuite(suite);
+  }
+
+  async onBeforeTryTask(test: Task, options?: { retry: number; repeats: number }): Promise<void> {
+    const filepath = getTaskFilepath(test);
+    if (filepath) {
+      const fileState = this.fileScopeMap.get(filepath);
+      if (fileState) {
+        // Release previous scope on retry to avoid leaks
+        const existing = this.taskScopeMap.get(test.id);
+        if (existing) {
+          await releaseHeldScope(existing.testScope);
+        }
+
+        debugLog(`onBeforeTryTask: ${test.name} (retry=${options?.retry})`);
+
+        const testCtx = fileState.app.mockContext!(undefined, {
+          mockCtxStorage: false,
+          reuseCtxStorage: false,
+        });
+        fileState.app.ctxStorage!.enterWith(testCtx);
+
+        let testScope: HeldScope | null = null;
+        if (typeof testCtx.beginModuleScope === 'function') {
+          testScope = await createHeldScope(testCtx);
+          debugLog('test held scope created');
+        }
+
+        this.taskScopeMap.set(test.id, { testScope, filepath });
+      }
+    }
+
+    await super.onBeforeTryTask(test);
+  }
+
+  async onAfterRunTask(test: Task): Promise<void> {
+    const taskState = this.taskScopeMap.get(test.id);
+    if (taskState) {
+      debugLog(`onAfterRunTask: ${test.name}`);
+
+      await releaseHeldScope(taskState.testScope);
+      this.taskScopeMap.delete(test.id);
+
+      const fileState = this.fileScopeMap.get(taskState.filepath);
+      if (fileState) {
+        await restoreEggMocksIfNeeded(fileState.config.restoreMocks);
+        // Restore suite context
+        fileState.app.ctxStorage!.enterWith(fileState.suiteCtx);
+        debugLog('restored suite context');
+      }
+    }
+
+    await super.onAfterRunTask(test);
+  }
+}