@grest-ts/testkit 0.0.5

package/src/GGTestRuntimeWorker.ts

@@ -0,0 +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>[];
+    }
+}

package/src/GGTestSharedRef.ts

@@ -0,0 +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 {}
+    }
+}

package/src/GGTestkitExtensionsDiscovery.ts

@@ -0,0 +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();
+    }
+}

package/src/IGGLocalDiscoveryServer.ts

@@ -0,0 +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;
+}

package/src/callOn/GGCallOnSelector.ts

@@ -0,0 +1,61 @@
+/**
+ * Selector extension that adds targeted callOn to selectors.
+ *
+ * This allows explicitly targeting specific runtimes when multiple
+ * different runtime classes have the same service registered.
+ *
+ * @example
+ * const f = GGTest.startWorker({chain: ChainRuntime, weather: WeatherOnlyRuntime});
+ *
+ * // Both have WeatherService - explicitly target one:
+ * await f.chain.callOn(WeatherService).getWeather("Test").toMatchObject({...})
+ * await f.weather.callOn(WeatherService).getWeather("Test").toMatchObject({...})
+ */
+
+import {GGContext} from "@grest-ts/context";
+import {GGTestSelector, GGTestSelectorExtension} from "../testers/GGTestSelector";
+import {RuntimeConstructor} from "../testers/RuntimeSelector";
+import {callOnTargeted, GGTestCallOn} from "./callOn";
+import type {GGTestRuntime} from "../GGTestRuntime";
+
+/**
+ * Type for the callable callOn extension.
+ * Can be called as a function to invoke targeted callOn.
+ */
+export interface GGCallOnSelectorCallable {
+    <T>(target: T, ctx?: GGContext): GGTestCallOn<T>;
+}
+
+/**
+ * Extension that adds .callOn() as a callable to Selectors.
+ * Uses the selector's runtimes to target specific instances.
+ *
+ * Returns a callable that can be used directly: f.chain.callOn(WeatherService)
+ */
+export class GGCallOnSelector extends GGTestSelectorExtension {
+
+    public static readonly PROPERTY_NAME = "callOn";
+
+    constructor(runtimes: GGTestRuntime[]) {
+        super(runtimes);
+        // Return a callable function instead of this instance
+        const callable = <T>(target: T, ctx?: GGContext): GGTestCallOn<T> => {
+            return callOnTargeted(target, runtimes, ctx);
+        };
+        return callable as unknown as this;
+    }
+}
+
+// Declaration merging to add 'callOn' to SelectorExtensions
+declare module "@grest-ts/testkit" {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    interface SelectorExtensions<T extends RuntimeConstructor[]> {
+        callOn: GGCallOnSelectorCallable;
+    }
+}
+
+// Ensure RuntimeConstructor import is recognized (for declaration merging above)
+export type _RuntimeConstructorRef = RuntimeConstructor;
+
+// Register the extension
+GGTestSelector.addExtension(GGCallOnSelector);

package/src/callOn/GGContractClass.implement.ts

@@ -0,0 +1,43 @@
+/**
+ * Patches GGContractClass.implement() to auto-register contract instances in GGLocator.
+ *
+ * This enables callOn(ContractClass) to work without each protocol (HTTP, WebSocket, etc.)
+ * needing to manually register the contract instance.
+ */
+
+import {GGContractClass} from "@grest-ts/schema";
+import {GGLocator, GGLocatorKey} from "@grest-ts/locator";
+
+// Store the original implement method
+const originalImplement = GGContractClass.prototype.implement;
+
+export const LOCATOR_KEY_PREFIX_FOR_CONTRACT = "@contract:"
+
+/**
+ * Patched implement() that registers the returned client in GGLocator.
+ */
+GGContractClass.prototype.implement = function (
+    this: GGContractClass<any>,
+    instance: any,
+    options?: any
+) {
+    const contractName = this.name;
+
+    // Get the client from original implement
+    const client = originalImplement.call(this, instance, options);
+
+    // Register in GGLocator for callOn(Contract) access
+    const scope = GGLocator.tryGetScope();
+    if (scope) {
+        const key = new GGLocatorKey<typeof client>(LOCATOR_KEY_PREFIX_FOR_CONTRACT + contractName);
+        if (scope.has(key)) {
+            throw new Error(
+                `Contract '${contractName}' is already registered in this scope. ` +
+                `If you need multiple instances, use different contract names.`
+            );
+        }
+        scope.set(key, client);
+    }
+
+    return client;
+};

package/src/callOn/GGTestActionForLocatorOnCall.ts

@@ -0,0 +1,134 @@
+/**
+ * Test action for invoking methods via GGLocator lookup.
+ *
+ * Used for:
+ * - @testable services (key: @testable:ClassName)
+ * - Direct contract calls (key: @contract:ContractName)
+ * - Custom GGLocatorKey lookups
+ *
+ * Extends GGTestAction to support .with() for mocks/spies and
+ * response expectations like .toMatchObject(), .toEqual().
+ */
+
+import {GGTestAction, GGTestActionConfig, tActionRawData} from "../testers/GGTestAction";
+import {GG_TEST_RUNNER} from "../GGTestRunner";
+import {SerializedContext, TestableInvokeResult, TestableIPC} from "./TestableIPC";
+import {GGTestError} from "../utils/GGTestError";
+import {GGContext} from "@grest-ts/context";
+import type {GGTestRuntime} from "../GGTestRuntime";
+
+/**
+ * Serialize a GGContext to a plain object for IPC transfer.
+ * Flattens the context hierarchy into a single object.
+ */
+function serializeContext(ctx: GGContext): SerializedContext {
+    const result: SerializedContext = {};
+    // Access the private values map via type assertion
+    const ctxAny = ctx as any;
+    if (ctxAny.values instanceof Map) {
+        for (const [key, value] of ctxAny.values) {
+            result[key] = value;
+        }
+    }
+    // Also serialize parent context values (child values take precedence)
+    if (ctxAny.parent) {
+        const parentValues = serializeContext(ctxAny.parent);
+        return {...parentValues, ...result};
+    }
+    return result;
+}
+
+/**
+ * Action for invoking a method via GGLocator lookup over IPC.
+ *
+ * @typeParam T - The expected return type of the method
+ */
+export class GGTestActionForLocatorOnCall<T> extends GGTestAction<T> {
+
+    private readonly keyName: string;
+    private readonly methodName: string;
+    private readonly args: any[];
+    private readonly targetRuntimes?: GGTestRuntime[];
+
+    constructor(ctx: GGContext, keyName: string, methodName: string, args: any[], targetRuntimes?: GGTestRuntime[]) {
+        const config: GGTestActionConfig = {
+            noResponse: false,
+            logData: {
+                message: `[${keyName}.${methodName}]`,
+                request: args.length > 0 ? args : undefined
+            }
+        };
+        super(ctx, config);
+        this.keyName = keyName;
+        this.methodName = methodName;
+        this.args = args;
+        this.targetRuntimes = targetRuntimes;
+    }
+
+    // -------------------------------------------------
+    // Action execution
+    // -------------------------------------------------
+
+    protected async executeAction(): Promise<tActionRawData> {
+        const runner = GG_TEST_RUNNER.get();
+
+        // Use target runtimes if provided, otherwise all runtimes
+        const searchRuntimes = this.targetRuntimes ?? runner.getAllRuntimes();
+
+        // Find runtimes that have this key registered
+        const candidates = searchRuntimes.filter(r => r.hasLocatorKey(this.keyName));
+
+        if (candidates.length === 0) {
+            // No runtime has this key - provide helpful error
+            const allRuntimes = runner.getAllRuntimes();
+            if (allRuntimes.length === 0) {
+                throw new GGTestError({
+                    test: `No runtimes available to invoke ${this.keyName}.${this.methodName}`,
+                    expected: "At least one runtime to be started",
+                    received: "No runtimes found"
+                });
+            }
+            throw new GGTestError({
+                test: `Instance '${this.keyName}' not found in any runtime`,
+                expected: `A @testable instance registered with key '${this.keyName}'`,
+                received: `Key not registered in any of ${allRuntimes.length} runtime(s): ${allRuntimes.map(r => r.name).join(', ')}`
+            });
+        }
+
+        if (candidates.length > 1) {
+            // Check if all candidates are the same runtime class - if so, just use first one
+            const uniqueClassNames = new Set(candidates.map(r => r.className));
+            if (uniqueClassNames.size > 1) {
+                // Different runtime classes have this key - actual ambiguity
+                throw new GGTestError({
+                    test: `Multiple different runtimes have '${this.keyName}' registered`,
+                    expected: `Key '${this.keyName}' to be unique across different runtime classes, or use explicit runtime targeting`,
+                    received: `Found in ${candidates.length} runtimes with different classes: ${[...uniqueClassNames].join(', ')}`
+                });
+            }
+            // Same runtime class - just use first instance (they're identical)
+        }
+
+        // Exactly one runtime has this key - send IPC directly
+        const runtime = candidates[0];
+        const context = this.ctx ? serializeContext(this.ctx) : undefined;
+
+        const result: TestableInvokeResult = await runtime.sendCommand(TestableIPC.invoke, {
+            keyName: this.keyName,
+            methodName: this.methodName,
+            args: this.args,
+            context
+        });
+
+        if (result.success) {
+            return result.result as tActionRawData;
+        }
+
+        throw new GGTestError({
+            test: `Error invoking ${this.keyName}.${this.methodName}`,
+            expected: "Method to execute successfully",
+            received: result.error || "Unknown error",
+            extra: result.stack
+        });
+    }
+}

package/src/callOn/TestableIPC.ts

@@ -0,0 +1,81 @@
+/**
+ * IPC protocol definitions for GGLocator-based service invocation.
+ *
+ * Defines the messages exchanged between test runner and runtime worker
+ * for invoking methods on registered instances (@testable, @contract, etc.).
+ */
+
+import {IPCClient, IPCServer} from "@grest-ts/ipc";
+
+/**
+ * Serialized context data for IPC transfer.
+ * Contains flattened key-value pairs from GGContext.
+ */
+export type SerializedContext = Record<string, any>;
+
+/**
+ * Payload for invoking a method on a registered instance.
+ */
+export interface TestableInvokePayload {
+    /** The GGLocatorKey name (e.g., "@testable:ServiceB", "@contract:ChainApi", or custom key) */
+    keyName: string;
+    /** The method name to invoke */
+    methodName: string;
+    /** Arguments to pass to the method (as array) */
+    args: any[];
+    /** Serialized GGContext data to restore on the worker side */
+    context?: SerializedContext;
+}
+
+/**
+ * Result from invoking a testable method.
+ */
+export interface TestableInvokeResult {
+    /** Whether the invocation succeeded */
+    success: boolean;
+    /** The return value from the method (if success) */
+    result?: any;
+    /** Error message (if failed) */
+    error?: string;
+    /** Error stack trace (if failed) */
+    stack?: string;
+}
+
+/**
+ * Payload for registering locator keys from a runtime.
+ */
+export interface KeyRegistrationPayload {
+    /** Runtime ID sending the registration */
+    runtimeId: string;
+    /** All GGLocatorKey names registered in this runtime */
+    keys: string[];
+}
+
+/**
+ * IPC endpoints for testable service invocation.
+ */
+export const TestableIPC = {
+    /**
+     * Messages FROM test server TO worker.
+     */
+    client: {
+        /**
+         * Invoke a method on a testable service instance.
+         */
+        invoke: IPCClient.defineRequest<TestableInvokePayload, TestableInvokeResult>("testable/invoke"),
+    },
+
+    /**
+     * Messages FROM worker TO test server.
+     */
+    server: {
+        /**
+         * Register all locator keys available in a runtime.
+         * Sent from worker to test runner after compose completes.
+         */
+        registerKeys: IPCServer.defineRequest<KeyRegistrationPayload, void>("testable/register-keys"),
+    },
+
+    // Legacy alias for backwards compatibility
+    invoke: IPCClient.defineRequest<TestableInvokePayload, TestableInvokeResult>("testable/invoke"),
+};