@grest-ts/testkit 0.0.6 → 0.0.8

package/src/GGTestRuntimeWorker.ts

@@ -1,159 +1,159 @@
-import {IPCClient, IPCClientRequest} from "@grest-ts/ipc";
-import {GGLog} from "@grest-ts/logger";
-import {GGLoggerConsole} from "@grest-ts/logger-console";
-import {GGRuntime} from "@grest-ts/runtime";
-import {GGLocatorKey, GGLocatorScope} from "@grest-ts/locator";
-import {pathToFileURL} from "url";
-import {GGTestCommand, GGTestEnvConfig} from "./GGTestRuntime";
-import {GGExtensionDiscovery} from "@grest-ts/common";
-import {type MockableTestContext, runWithMockableContext} from "@grest-ts/testkit-runtime";
-import {CALL_THROUGH} from "./mockable/GGMockableInterceptorsServer";
-import {GGMockableIPC} from "./mockable/GGMockableIPC";
-import {registerOnCallHandler} from "./callOn/registerOnCallHandler";
-import {TestableIPC} from "./callOn/TestableIPC";
-
-export const GG_TEST_RUNTIME_WORKER = new GGLocatorKey<GGTestRuntimeWorker>("GGTestRuntimeWorker");
-
-export class GGTestRuntimeWorker {
-
-    private static beforeRuntimeStartHandlers: (() => void)[] = [];
-    private static beforeRuntimeStartExecuted = false;
-
-    public readonly ipcClient: IPCClient;
-    public readonly config: GGTestEnvConfig;
-    public runtime: GGRuntime = undefined
-    private runtimeStopped = false;
-
-    private readonly scope: GGLocatorScope;
-
-    constructor(config: GGTestEnvConfig) {
-        this.ipcClient = new IPCClient(config.testRouterPort);
-        this.config = config;
-        this.scope = new GGLocatorScope("GGTestRuntimeWorker").enter();
-        this.scope.set(GG_TEST_RUNTIME_WORKER, this);
-        GGLog.init();
-        GGLog.add(new GGLoggerConsole({showData: true}));
-    }
-
-    /**
-     * Register a function to be called before the runtime starts.
-     * Safe to call at module load time - just adds to array.
-     * Handlers are executed during start() after extensions are loaded but before runtime creation.
-     */
-    public static onBeforeRuntimeStart(handler: () => void): void {
-        if (this.beforeRuntimeStartExecuted) {
-            throw new Error("Cannot register beforeRuntimeStart handler after worker has started");
-        }
-        this.beforeRuntimeStartHandlers.push(handler);
-    }
-
-    public async start(createRuntime?: () => GGRuntime): Promise<void> {
-        process.env.GG_LOCAL_ROUTER_PORT = String(this.config.testRouterPort);
-
-        await new GGExtensionDiscovery('testkit').load();
-
-        // Create mockable context that bridges to IPC
-        const mockableContext: MockableTestContext = {
-            CALL_THROUGH,
-            sendCall: async (className, methodName, callArgs) => {
-                return this.ipcClient.sendFrameworkRequest(GGMockableIPC.testServer.call, {
-                    className,
-                    methodName,
-                    callArgs
-                });
-            },
-            sendSpyResult: async (className, methodName, callResult) => {
-                await this.ipcClient.sendFrameworkRequest(GGMockableIPC.testServer.spyResult, {
-                    className,
-                    methodName,
-                    callResult
-                });
-            }
-        };
-
-        // Wrap in mockable context so @mockable decorators can intercept
-        await runWithMockableContext(mockableContext, async () => {
-            await this.ipcClient.connect(this.config.runtimeId);
-            GGLog.debug(this, 'Connected to test router');
-
-            // Register testable handler for direct service invocation from tests
-            registerOnCallHandler(this);
-
-            GGTestRuntimeWorker.beforeRuntimeStartExecuted = true;
-            GGTestRuntimeWorker.beforeRuntimeStartHandlers.forEach(handler => handler());
-
-            if (createRuntime) {
-                this.runtime = createRuntime();
-            } else {
-                // Dynamic import of the runtime source file.
-                // Always use file:// URL — required by Node ESM on Windows.
-                const moduleUrl = this.config.executablePath.startsWith('file:')
-                    ? this.config.executablePath
-                    : pathToFileURL(this.config.executablePath).href;
-                const module = await import(moduleUrl);
-                const RuntimeClass = module[this.config.className];
-                if (!RuntimeClass) {
-                    throw new Error(
-                        `Runtime class '${this.config.className}' not found in module '${this.config.executablePath}'. ` +
-                        `Make sure the class is exported.`
-                    );
-                }
-                this.runtime = new RuntimeClass();
-            }
-            await this.runtime!.start();
-
-            // Send registered locator keys to test runner for callOn routing
-            const keys = this.runtime!.scope.getKeys();
-            await this.ipcClient.sendFrameworkRequest(TestableIPC.server.registerKeys, {
-                runtimeId: this.config.runtimeId,
-                keys
-            });
-            GGLog.debug(this, `Sent ${keys.length} locator keys to test runner`);
-        });
-    }
-
-    /**
-     * Stop the GGRuntime (teardown services) but keep IPC alive.
-     * The runtime reference is kept so IPC handlers can still access
-     * async contexts (logs, metrics, config) via runInContext().
-     */
-    public async stopRuntime(): Promise<void> {
-        if (this.runtimeStopped) return;
-        this.runtimeStopped = true;
-        if (this.runtime) {
-            await this.runtime.scope.run(() => this.runtime!.teardown());
-        }
-    }
-
-    /**
-     * Register an IPC request handler that automatically runs within the runtime's context.
-     * Use this instead of ipcClient.onFrameworkRequest() for handlers that need access to
-     * runtime services (logs, metrics, config, etc.) even after runtime.stop().
-     */
-    public onIpcRequest<Req, Res>(
-        type: IPCClientRequest<Req, Res>,
-        handler: (payload: Req) => Res | Promise<Res>
-    ): void {
-        this.ipcClient.onFrameworkRequest(type, async (payload) => {
-            if (this.runtime) {
-                return this.runtime.scope.run(() => handler(payload));
-            }
-            return handler(payload);
-        });
-    }
-
-    /**
-     * Fully shutdown the worker, including IPC disconnection.
-     * Calls stopRuntime() if not already stopped.
-     */
-    public async shutdown(): Promise<void> {
-        if (!this.runtimeStopped) {
-            await this.stopRuntime();
-        }
-        this.ipcClient.disconnect();
-    }
-
-    public getInitialCommandsFor<Payload>(type: IPCClientRequest<Payload, any>): GGTestCommand<Payload>[] {
-        return this.config.initialCommands.filter(cmd => cmd.method === type) as GGTestCommand<Payload>[];
-    }
-}
+import {IPCClient, IPCClientRequest} from "@grest-ts/ipc";
+import {GGLog} from "@grest-ts/logger";
+import {GGLoggerConsole} from "@grest-ts/logger-console";
+import {GGRuntime} from "@grest-ts/runtime";
+import {GGLocatorKey, GGLocatorScope} from "@grest-ts/locator";
+import {pathToFileURL} from "url";
+import {GGTestCommand, GGTestEnvConfig} from "./GGTestRuntime";
+import {GGExtensionDiscovery} from "@grest-ts/common";
+import {type MockableTestContext, runWithMockableContext} from "@grest-ts/testkit-runtime";
+import {CALL_THROUGH} from "./mockable/GGMockableInterceptorsServer";
+import {GGMockableIPC} from "./mockable/GGMockableIPC";
+import {registerOnCallHandler} from "./callOn/registerOnCallHandler";
+import {TestableIPC} from "./callOn/TestableIPC";
+
+export const GG_TEST_RUNTIME_WORKER = new GGLocatorKey<GGTestRuntimeWorker>("GGTestRuntimeWorker");
+
+export class GGTestRuntimeWorker {
+
+    private static beforeRuntimeStartHandlers: (() => void)[] = [];
+    private static beforeRuntimeStartExecuted = false;
+
+    public readonly ipcClient: IPCClient;
+    public readonly config: GGTestEnvConfig;
+    public runtime: GGRuntime = undefined
+    private runtimeStopped = false;
+
+    private readonly scope: GGLocatorScope;
+
+    constructor(config: GGTestEnvConfig) {
+        this.ipcClient = new IPCClient(config.testRouterPort);
+        this.config = config;
+        this.scope = new GGLocatorScope("GGTestRuntimeWorker").enter();
+        this.scope.set(GG_TEST_RUNTIME_WORKER, this);
+        GGLog.init();
+        GGLog.add(new GGLoggerConsole({showData: true}));
+    }
+
+    /**
+     * Register a function to be called before the runtime starts.
+     * Safe to call at module load time - just adds to array.
+     * Handlers are executed during start() after extensions are loaded but before runtime creation.
+     */
+    public static onBeforeRuntimeStart(handler: () => void): void {
+        if (this.beforeRuntimeStartExecuted) {
+            throw new Error("Cannot register beforeRuntimeStart handler after worker has started");
+        }
+        this.beforeRuntimeStartHandlers.push(handler);
+    }
+
+    public async start(createRuntime?: () => GGRuntime): Promise<void> {
+        process.env.GG_LOCAL_ROUTER_PORT = String(this.config.testRouterPort);
+
+        await new GGExtensionDiscovery('testkit').load();
+
+        // Create mockable context that bridges to IPC
+        const mockableContext: MockableTestContext = {
+            CALL_THROUGH,
+            sendCall: async (className, methodName, callArgs) => {
+                return this.ipcClient.sendFrameworkRequest(GGMockableIPC.testServer.call, {
+                    className,
+                    methodName,
+                    callArgs
+                });
+            },
+            sendSpyResult: async (className, methodName, callResult) => {
+                await this.ipcClient.sendFrameworkRequest(GGMockableIPC.testServer.spyResult, {
+                    className,
+                    methodName,
+                    callResult
+                });
+            }
+        };
+
+        // Wrap in mockable context so @mockable decorators can intercept
+        await runWithMockableContext(mockableContext, async () => {
+            await this.ipcClient.connect(this.config.runtimeId);
+            GGLog.debug(this, 'Connected to test router');
+
+            // Register testable handler for direct service invocation from tests
+            registerOnCallHandler(this);
+
+            GGTestRuntimeWorker.beforeRuntimeStartExecuted = true;
+            GGTestRuntimeWorker.beforeRuntimeStartHandlers.forEach(handler => handler());
+
+            if (createRuntime) {
+                this.runtime = createRuntime();
+            } else {
+                // Dynamic import of the runtime source file.
+                // Always use file:// URL — required by Node ESM on Windows.
+                const moduleUrl = this.config.executablePath.startsWith('file:')
+                    ? this.config.executablePath
+                    : pathToFileURL(this.config.executablePath).href;
+                const module = await import(moduleUrl);
+                const RuntimeClass = module[this.config.className];
+                if (!RuntimeClass) {
+                    throw new Error(
+                        `Runtime class '${this.config.className}' not found in module '${this.config.executablePath}'. ` +
+                        `Make sure the class is exported.`
+                    );
+                }
+                this.runtime = new RuntimeClass();
+            }
+            await this.runtime!.start();
+
+            // Send registered locator keys to test runner for callOn routing
+            const keys = this.runtime!.scope.getKeys();
+            await this.ipcClient.sendFrameworkRequest(TestableIPC.server.registerKeys, {
+                runtimeId: this.config.runtimeId,
+                keys
+            });
+            GGLog.debug(this, `Sent ${keys.length} locator keys to test runner`);
+        });
+    }
+
+    /**
+     * Stop the GGRuntime (teardown services) but keep IPC alive.
+     * The runtime reference is kept so IPC handlers can still access
+     * async contexts (logs, metrics, config) via runInContext().
+     */
+    public async stopRuntime(): Promise<void> {
+        if (this.runtimeStopped) return;
+        this.runtimeStopped = true;
+        if (this.runtime) {
+            await this.runtime.scope.run(() => this.runtime!.teardown());
+        }
+    }
+
+    /**
+     * Register an IPC request handler that automatically runs within the runtime's context.
+     * Use this instead of ipcClient.onFrameworkRequest() for handlers that need access to
+     * runtime services (logs, metrics, config, etc.) even after runtime.stop().
+     */
+    public onIpcRequest<Req, Res>(
+        type: IPCClientRequest<Req, Res>,
+        handler: (payload: Req) => Res | Promise<Res>
+    ): void {
+        this.ipcClient.onFrameworkRequest(type, async (payload) => {
+            if (this.runtime) {
+                return this.runtime.scope.run(() => handler(payload));
+            }
+            return handler(payload);
+        });
+    }
+
+    /**
+     * Fully shutdown the worker, including IPC disconnection.
+     * Calls stopRuntime() if not already stopped.
+     */
+    public async shutdown(): Promise<void> {
+        if (!this.runtimeStopped) {
+            await this.stopRuntime();
+        }
+        this.ipcClient.disconnect();
+    }
+
+    public getInitialCommandsFor<Payload>(type: IPCClientRequest<Payload, any>): GGTestCommand<Payload>[] {
+        return this.config.initialCommands.filter(cmd => cmd.method === type) as GGTestCommand<Payload>[];
+    }
+}

package/src/GGTestSharedRef.ts

@@ -1,116 +1,116 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import * as os from 'os';
-
-/**
- * Reference counting for shared test resources across workers.
- *
- * Used to coordinate shared resources (e.g. database schemas)
- * that multiple workers use simultaneously. Handles file-system
- * based locking so callers don't need their own locking mechanism.
- *
- * - acquire(key, onCreate): first caller runs onCreate, others wait and skip
- * - release(key, onLast): last caller runs onLast (e.g. cleanup)
- */
-export class GGTestSharedRef {
-
-    private static getRefDir(): string {
-        const runId = process.env.GG_TEST_RUN_ID;
-        if (!runId) {
-            throw new Error("GG_TEST_RUN_ID not set. Add globalSetup '@grest-ts/testkit-vitest/globalSetup' to vitest.config.ts.");
-        }
-        const dir = path.join(os.tmpdir(), `gg-test-${runId}`);
-        fs.mkdirSync(dir, {recursive: true});
-        return dir;
-    }
-
-    private static getRefFile(key: string): string {
-        return path.join(this.getRefDir(), `${key}.ref`);
-    }
-
-    private static getLockPath(key: string): string {
-        return path.join(this.getRefDir(), `${key}.lock`);
-    }
-
-    private static async acquireLock(key: string): Promise<void> {
-        const lockPath = this.getLockPath(key);
-        const timeout = 60000;
-        const start = Date.now();
-        while (true) {
-            try {
-                fs.mkdirSync(lockPath);
-                return;
-            } catch {
-                if (Date.now() - start > timeout) {
-                    throw new Error(`[GGTestSharedRef] Failed to acquire lock for '${key}' after ${timeout}ms`);
-                }
-                await new Promise(resolve => setTimeout(resolve, 50 + Math.random() * 50));
-            }
-        }
-    }
-
-    private static releaseLock(key: string): void {
-        try { fs.rmdirSync(this.getLockPath(key)); } catch {}
-    }
-
-    /**
-     * Acquire a shared reference. If this is the first reference,
-     * the onCreate callback is called (e.g. to create a shared resource).
-     * Other callers wait for the lock and skip onCreate.
-     */
-    static async acquire(key: string, onCreate: () => Promise<void>): Promise<void> {
-        await this.acquireLock(key);
-        try {
-            const file = this.getRefFile(key);
-            let count = 0;
-            try { count = parseInt(fs.readFileSync(file, 'utf-8')); } catch {}
-
-            if (count === 0) {
-                await onCreate();
-            }
-
-            fs.writeFileSync(file, (count + 1).toString());
-        } finally {
-            this.releaseLock(key);
-        }
-    }
-
-    /**
-     * Release a shared reference. If this is the last reference,
-     * the onLast callback is called (e.g. to drop a shared resource).
-     * Errors in onLast are caught and logged (cleanup is best-effort).
-     */
-    static async release(key: string, onLast: () => Promise<void>): Promise<void> {
-        await this.acquireLock(key);
-        try {
-            const file = this.getRefFile(key);
-            let count = 0;
-            try { count = parseInt(fs.readFileSync(file, 'utf-8')); } catch {}
-            count -= 1;
-
-            if (count <= 0) {
-                try { fs.unlinkSync(file); } catch {}
-                try {
-                    await onLast();
-                } catch (err) {
-                    console.error('[GGTestSharedRef] Cleanup failed:', err);
-                }
-            } else {
-                fs.writeFileSync(file, count.toString());
-            }
-        } finally {
-            this.releaseLock(key);
-        }
-    }
-
-    /**
-     * Remove the ref counting temp directory for the current test run.
-     * Called by globalSetup teardown after all workers have finished.
-     */
-    static cleanup(): void {
-        const runId = process.env.GG_TEST_RUN_ID;
-        if (!runId) return;
-        const dir = path.join(os.tmpdir(), `gg-test-${runId}`);
-        try { fs.rmSync(dir, {recursive: true}); } catch {}
-    }
-}
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+/**
+ * Reference counting for shared test resources across workers.
+ *
+ * Used to coordinate shared resources (e.g. database schemas)
+ * that multiple workers use simultaneously. Handles file-system
+ * based locking so callers don't need their own locking mechanism.
+ *
+ * - acquire(key, onCreate): first caller runs onCreate, others wait and skip
+ * - release(key, onLast): last caller runs onLast (e.g. cleanup)
+ */
+export class GGTestSharedRef {
+
+    private static getRefDir(): string {
+        const runId = process.env.GG_TEST_RUN_ID;
+        if (!runId) {
+            throw new Error("GG_TEST_RUN_ID not set. Add globalSetup '@grest-ts/testkit-vitest/globalSetup' to vitest.config.ts.");
+        }
+        const dir = path.join(os.tmpdir(), `gg-test-${runId}`);
+        fs.mkdirSync(dir, {recursive: true});
+        return dir;
+    }
+
+    private static getRefFile(key: string): string {
+        return path.join(this.getRefDir(), `${key}.ref`);
+    }
+
+    private static getLockPath(key: string): string {
+        return path.join(this.getRefDir(), `${key}.lock`);
+    }
+
+    private static async acquireLock(key: string): Promise<void> {
+        const lockPath = this.getLockPath(key);
+        const timeout = 60000;
+        const start = Date.now();
+        while (true) {
+            try {
+                fs.mkdirSync(lockPath);
+                return;
+            } catch {
+                if (Date.now() - start > timeout) {
+                    throw new Error(`[GGTestSharedRef] Failed to acquire lock for '${key}' after ${timeout}ms`);
+                }
+                await new Promise(resolve => setTimeout(resolve, 50 + Math.random() * 50));
+            }
+        }
+    }
+
+    private static releaseLock(key: string): void {
+        try { fs.rmdirSync(this.getLockPath(key)); } catch {}
+    }
+
+    /**
+     * Acquire a shared reference. If this is the first reference,
+     * the onCreate callback is called (e.g. to create a shared resource).
+     * Other callers wait for the lock and skip onCreate.
+     */
+    static async acquire(key: string, onCreate: () => Promise<void>): Promise<void> {
+        await this.acquireLock(key);
+        try {
+            const file = this.getRefFile(key);
+            let count = 0;
+            try { count = parseInt(fs.readFileSync(file, 'utf-8')); } catch {}
+
+            if (count === 0) {
+                await onCreate();
+            }
+
+            fs.writeFileSync(file, (count + 1).toString());
+        } finally {
+            this.releaseLock(key);
+        }
+    }
+
+    /**
+     * Release a shared reference. If this is the last reference,
+     * the onLast callback is called (e.g. to drop a shared resource).
+     * Errors in onLast are caught and logged (cleanup is best-effort).
+     */
+    static async release(key: string, onLast: () => Promise<void>): Promise<void> {
+        await this.acquireLock(key);
+        try {
+            const file = this.getRefFile(key);
+            let count = 0;
+            try { count = parseInt(fs.readFileSync(file, 'utf-8')); } catch {}
+            count -= 1;
+
+            if (count <= 0) {
+                try { fs.unlinkSync(file); } catch {}
+                try {
+                    await onLast();
+                } catch (err) {
+                    console.error('[GGTestSharedRef] Cleanup failed:', err);
+                }
+            } else {
+                fs.writeFileSync(file, count.toString());
+            }
+        } finally {
+            this.releaseLock(key);
+        }
+    }
+
+    /**
+     * Remove the ref counting temp directory for the current test run.
+     * Called by globalSetup teardown after all workers have finished.
+     */
+    static cleanup(): void {
+        const runId = process.env.GG_TEST_RUN_ID;
+        if (!runId) return;
+        const dir = path.join(os.tmpdir(), `gg-test-${runId}`);
+        try { fs.rmSync(dir, {recursive: true}); } catch {}
+    }
+}

package/src/GGTestkitExtensionsDiscovery.ts

@@ -1,26 +1,26 @@
-import {GGExtensionDiscovery} from '@grest-ts/common';
-
-/**
- * Discovers testkit extensions by scanning node_modules for packages
- * that follow the convention of having a testkit/index-testkit.ts file.
- *
- * @deprecated Use GGExtensionDiscovery from @grest-ts/common directly:
- * ```typescript
- * const discovery = new GGExtensionDiscovery('testkit');
- * await discovery.load();
- * ```
- */
-export class GGTestkitExtensionsDiscovery {
-
-    private static discovery = new GGExtensionDiscovery('testkit');
-
-    /**
-     * Discover and load all testkits.
-     * - Scans for testkit packages
-     * - Generates .d.ts file for IDE support
-     * - Dynamically imports testkits for runtime
-     */
-    public static async load(): Promise<void> {
-        await this.discovery.load();
-    }
-}
+import {GGExtensionDiscovery} from '@grest-ts/common';
+
+/**
+ * Discovers testkit extensions by scanning node_modules for packages
+ * that follow the convention of having a testkit/index-testkit.ts file.
+ *
+ * @deprecated Use GGExtensionDiscovery from @grest-ts/common directly:
+ * ```typescript
+ * const discovery = new GGExtensionDiscovery('testkit');
+ * await discovery.load();
+ * ```
+ */
+export class GGTestkitExtensionsDiscovery {
+
+    private static discovery = new GGExtensionDiscovery('testkit');
+
+    /**
+     * Discover and load all testkits.
+     * - Scans for testkit packages
+     * - Generates .d.ts file for IDE support
+     * - Dynamically imports testkits for runtime
+     */
+    public static async load(): Promise<void> {
+        await this.discovery.load();
+    }
+}

package/src/IGGLocalDiscoveryServer.ts

@@ -1,16 +1,16 @@
-/**
- * Interface for discovery server used by GGTestRunner.
- * Implemented by GGLocalDiscoveryServer in @grest-ts/discovery.
- * This interface allows @grest-ts/testkit to not depend on @grest-ts/discovery.
- */
-export interface IGGLocalDiscoveryServer {
-    start(): Promise<boolean>;
-    teardown(): Promise<void>;
-    getRoutingUrl(api: string): string;
-}
-
-export interface IServiceRoute {
-    api: string;
-    baseUrl: string;
-    pathPrefix: string;
-}
+/**
+ * Interface for discovery server used by GGTestRunner.
+ * Implemented by GGLocalDiscoveryServer in @grest-ts/discovery.
+ * This interface allows @grest-ts/testkit to not depend on @grest-ts/discovery.
+ */
+export interface IGGLocalDiscoveryServer {
+    start(): Promise<boolean>;
+    teardown(): Promise<void>;
+    getRoutingUrl(api: string): string;
+}
+
+export interface IServiceRoute {
+    api: string;
+    baseUrl: string;
+    pathPrefix: string;
+}