@grest-ts/testkit 0.0.5

package/src/GGTestRunner.ts

@@ -0,0 +1,308 @@
+import {GGTestRuntime} from "./GGTestRuntime"
+import {GGLog} from "@grest-ts/logger"
+import {IPCClientRequest, IPCServer} from "@grest-ts/ipc";
+import {GGContext} from "@grest-ts/context";
+import {GG_TRACE} from "@grest-ts/trace";
+import {GGLocatorKey} from "@grest-ts/locator";
+import {GGTestComponent, GGTestComponentType} from "./testers/GGTestComponent";
+import {IGGLocalDiscoveryServer} from "./IGGLocalDiscoveryServer";
+import {TestableIPC} from "./callOn/TestableIPC";
+
+export const GG_TEST_RUNNER = new GGLocatorKey<GGTestRunner>("GGTestRunner");
+
+/**
+ * Interface for test lifecycle hooks.
+ * Registered via GGTest.registerHook() to run setup/teardown logic.
+ */
+export interface GGTestRunnerHook {
+    /** Key name for deduplication (e.g., config key name) */
+    keyName: string;
+    /** Runs in beforeAll - setup logic */
+    beforeAll: () => Promise<void>;
+    /** Runs in afterAll - cleanup logic */
+    afterAll: () => Promise<void>;
+}
+
+/**
+ * Symbol for resources that support test operations.
+ * Resources implement this to expose operations like clone().
+ */
+export const GG_TEST_RESOURCE = Symbol('GG_TEST_RESOURCE');
+
+/**
+ * Type for objects that expose test resource operations.
+ * Used by GGTest.with() to get available operations.
+ */
+export interface TestResource<T = any> {
+    [GG_TEST_RESOURCE]: T;
+}
+
+export interface GGTestConfig {
+    serviceStartupTimeout: number
+    verboseProxy: boolean
+}
+
+export class GGTestRunner {
+
+    /**
+     * Unique identifier for this test context.
+     * Used for test resource isolation (e.g., creating isolated DB schemas).
+     */
+    public readonly testId: string
+    public readonly ipcServer: IPCServer;
+    public readonly discoveryServer: IGGLocalDiscoveryServer
+    public readonly config: GGTestConfig = {
+        serviceStartupTimeout: 30000,
+        verboseProxy: false
+    }
+    private _started: boolean = false
+
+    /**
+     * Runtimes added in the describe block (before start).
+     * These are managed by beforeAll/afterAll.
+     */
+    private readonly globalRuntimes: GGTestRuntime[] = []
+
+    /**
+     * Runtimes added within test blocks (after start).
+     * These are managed by afterEach and cleared after each test.
+     */
+    private readonly inTestRuntimes: GGTestRuntime[] = []
+
+    /**
+     * Extension instances - extensions are some "describe block level components".
+     * Some examples EventsServer, HttpInterceptorsServer, MockableInterceptorsServer etc.
+     */
+    private readonly extensionInstances = new Map<GGTestComponentType<any>, GGTestComponent>();
+
+    private readonly hooks: Map<string, GGTestRunnerHook> = new Map()
+
+    constructor(ipcServer: IPCServer, discoveryServer: IGGLocalDiscoveryServer, userConfig?: Partial<GGTestConfig>) {
+        this.testId = "t" + Math.random().toString(36).substring(2, 8);
+        this.config = {...this.config, ...userConfig};
+        this.ipcServer = ipcServer;
+        this.discoveryServer = discoveryServer;
+
+        // Register IPC handler for key registration from workers
+        this.ipcServer.onFrameworkMessage(TestableIPC.server.registerKeys, async (payload) => {
+            const runtime = this.getRuntimeById(payload.runtimeId);
+            if (runtime) {
+                runtime.registerLocatorKeys(payload.keys);
+                GGLog.debug(this, `Registered ${payload.keys.length} keys for runtime ${payload.runtimeId}`);
+            } else {
+                GGLog.warn(this, `Received key registration for unknown runtime: ${payload.runtimeId}`);
+            }
+        });
+    }
+
+    // -----------------------------------------------
+    // Static component factory registry
+    // -----------------------------------------------
+
+    /**
+     * Extension factories - extensions are some "describe block level components".
+     * Some examples EventsServer, HttpInterceptorsServer, MockableInterceptorsServer etc.
+     */
+    private static extensionFactories: GGTestComponentType<any>[] = [];
+
+    /**
+     * Register a component type.
+     * Components must accept GGTestRunner as their constructor argument.
+     */
+    public static registerExtension<T extends GGTestComponent>(type: GGTestComponentType<T>): void {
+        this.extensionFactories.push(type);
+    }
+
+    // -----------------------------------------------
+    // Component registry
+    // -----------------------------------------------
+
+    /**
+     * Get a component by type. Creates it lazily if not yet instantiated.
+     */
+    public getExtensionInstance<T extends GGTestComponent>(type: GGTestComponentType<T>): T {
+        if (!this.extensionInstances.has(type)) {
+            const instance = new type(this);
+            this.extensionInstances.set(type, instance);
+        }
+        return this.extensionInstances.get(type) as T;
+    }
+
+
+    // -----------------------------------------------
+    // Instance methods
+    // -----------------------------------------------
+
+    /**
+     * Whether the test has started (services are running).
+     */
+    public get started(): boolean {
+        return this._started;
+    }
+
+    /**
+     * Register a test lifecycle hook.
+     * Hooks run beforeAll (during start) and afterAll (during teardown).
+     * Duplicate registrations with the same keyName are skipped.
+     */
+    public registerHook(hook: GGTestRunnerHook): void {
+        if (this.hooks.has(hook.keyName)) {
+            GGLog.debug(this, `Hook already registered for ${hook.keyName}, skipping duplicate`);
+            return;
+        }
+        this.hooks.set(hook.keyName, hook);
+    }
+
+    /**
+     * Send a command to ALL runtimes.
+     * Used by resource hooks (e.g., DB config) that apply globally.
+     */
+    public async sendCommand<Payload>(type: IPCClientRequest<Payload, any>, payload: Payload): Promise<void> {
+        const promises = this.globalRuntimes.map(runtime => runtime.sendCommand(type, payload));
+        await Promise.allSettled(promises)
+    }
+
+
+    /**
+     * Add a runtime to this test runner.
+     * Automatically routes to the appropriate list based on lifecycle stage.
+     */
+    public addRuntime(runtime: GGTestRuntime): void {
+        if (this._started) {
+            // Added within a test block - managed by afterEach
+            this.inTestRuntimes.push(runtime);
+        } else {
+            // Added in describe block - managed by beforeAll/afterAll
+            this.globalRuntimes.push(runtime);
+        }
+    }
+
+    /**
+     * Get all active runtimes (both global and in-test).
+     */
+    public getAllRuntimes(): GGTestRuntime[] {
+        return [...this.globalRuntimes, ...this.inTestRuntimes];
+    }
+
+    /**
+     * Find a runtime by its unique runtimeId.
+     */
+    public getRuntimeById(runtimeId: string): GGTestRuntime | undefined {
+        return this.globalRuntimes.find(r => r.runtimeId === runtimeId)
+            ?? this.inTestRuntimes.find(r => r.runtimeId === runtimeId);
+    }
+
+    public async start(): Promise<void> {
+        await new GGContext("Test").run(async () => {
+            GG_TRACE.init();
+            if (this._started) {
+                throw new Error("Already started!");
+            }
+
+            // 0. Initialize extension (testkits already loaded by vitest setup)
+            for (const type of GGTestRunner.extensionFactories) {
+                // Create extension instance, which registers its IPC handlers
+                this.extensionInstances.set(type, new type(this));
+            }
+
+            // 1. Execute all hook beforeAll handlers in parallel
+            const hookPromises = Array.from(this.hooks.entries()).map(async ([keyName, hook]) => {
+                const startTime = performance.now();
+                GGLog.debug(this, `Running beforeAll hook: ${keyName}`);
+                await hook.beforeAll();
+                const duration = (performance.now() - startTime).toFixed(0);
+                GGLog.debug(this, `Completed beforeAll hook: ${keyName} (${duration}ms)`);
+                return keyName;
+            });
+
+            const results = await Promise.allSettled(hookPromises);
+            const failures = results.filter((r): r is PromiseRejectedResult => r.status === 'rejected');
+            if (failures.length > 0) {
+                const errorMessages = failures.map(f => {
+                    const reason = f.reason;
+                    if (reason instanceof AggregateError) {
+                        const innerErrors = reason.errors?.map((e: any) => e?.message || String(e)).join(', ');
+                        return `AggregateError[${innerErrors}]`;
+                    }
+                    return reason?.message || String(reason);
+                }).join('; ');
+                throw new Error(`Failed to run beforeAll hooks: ${errorMessages}`);
+            }
+
+            // 2. Start router
+            await this.discoveryServer.start();
+
+            // 3. Start components
+            for (const [type, component] of this.extensionInstances) {
+                if (component.start) {
+                    GGLog.debug(this, `Starting component: ${type.name}`);
+                    await component.start();
+                }
+            }
+
+            // 4. Start runtimes (they will receive commands via env)
+            for (const runtime of this.globalRuntimes) {
+                await runtime.start()
+            }
+            this._started = true;
+        });
+    }
+
+    public async runAfterEachHooks(): Promise<void> {
+        for (const [, component] of this.extensionInstances) {
+            await component.afterEach?.();
+        }
+
+        GGLog.debug(this, 'Stopping in-test runtimes...');
+        for (const runtime of this.inTestRuntimes) {
+            await runtime.shutdown();
+        }
+        this.inTestRuntimes.length = 0;
+        GGLog.debug(this, 'All in-test runtimes stopped!');
+    }
+
+    public async teardown(): Promise<void> {
+        await new GGContext("Test").run(async () => {
+            GG_TRACE.init();
+            // Stop global runtimes (teardown services, keep IPC alive)
+            GGLog.debug(this, 'Stopping global runtimes...');
+            for (const runtime of this.globalRuntimes) {
+                await runtime.stop()
+            }
+
+            // Shutdown global runtimes (terminate workers/processes)
+            GGLog.debug(this, 'Shutting down global runtimes...');
+            for (const runtime of this.globalRuntimes) {
+                await runtime.shutdown()
+            }
+
+            GGLog.debug(this, 'Tearing down router...');
+            await this.discoveryServer.teardown();
+
+            // Teardown components
+            for (const [type, component] of this.extensionInstances) {
+                if (component.teardown) {
+                    GGLog.debug(this, `Tearing down component: ${type.name}`);
+                    await component.teardown();
+                }
+            }
+            this.extensionInstances.clear();
+
+            GGLog.debug(this, 'Router torn down');
+
+            // Run afterAll hooks
+            GGLog.debug(this, 'Running afterAll hooks...');
+            for (const [keyName, hook] of this.hooks) {
+                try {
+                    await hook.afterAll();
+                    GGLog.debug(this, `Completed afterAll hook: ${keyName}`);
+                } catch (error) {
+                    GGLog.error(this, `Failed afterAll hook ${keyName}:`, error);
+                }
+            }
+
+            this.globalRuntimes.length = 0
+            this.hooks.clear()
+        });
+    }
+}

package/src/GGTestRuntime.ts

@@ -0,0 +1,265 @@
+import {GGLog} from "@grest-ts/logger";
+import {withTimeout} from "@grest-ts/common";
+import {GGContext} from "@grest-ts/context";
+import {GG_TRACE} from "@grest-ts/trace";
+import {IPCClientRequest} from "@grest-ts/ipc";
+import type {RuntimeRunner} from "./runner/RuntimeRunner";
+import {InlineRunner} from "./runner/InlineRunner";
+import {WorkerRunner} from "./runner/WorkerRunner";
+import {IsolatedRunner} from "./runner/IsolatedRunner";
+import type {GGTestRunner} from "./GGTestRunner";
+
+/**
+ * Lifecycle state of a runtime instance.
+ */
+export enum GGTestRuntimeState {
+    /** Initial state, not yet started */
+    CREATED = 'created',
+    /** Running successfully */
+    STARTED = 'started',
+    /** Startup failed, but worker/IPC still alive for diagnostics */
+    FAILED = 'failed',
+    /** Runtime stopped, but worker/IPC still alive for log retrieval */
+    STOPPED = 'stopped',
+    /** Fully shut down, no IPC available */
+    SHUTDOWN = 'shutdown',
+}
+
+export interface GGTestEnvConfig {
+    executablePath: string;
+    className: string;
+    testRouterPort: number;
+    testId: string;
+    runtimeId: string;
+    initialCommands: GGTestCommand[];
+    /** When true, the runtime runs inline (same process). Affects module loading strategy. */
+    inline?: boolean;
+}
+
+export interface GGTestCommand<Payload = unknown> {
+    method: string;
+    payload: Payload;
+}
+
+export interface GGTestRuntimeConfig {
+    mode?: GGTestMode
+}
+
+export enum GGTestMode {
+    INLINE = 'INLINE',
+    WORKER = 'WORKER',
+    ISOLATED = 'ISOLATED'
+}
+
+export class GGTestRuntime {
+
+    public readonly runner: GGTestRunner;
+
+    /**
+     * Unique identifier for this runtime instance.
+     * Used for targeted communication (e.g., "checklist-0", "checklist-1").
+     */
+    public readonly runtimeId: string
+
+    /**
+     * The runtime name used for selector access (e.g., "checklist").
+     * This is the static NAME property from the runtime class.
+     */
+    public readonly name: string
+
+    /**
+     * The class name of the runtime (e.g., "ChecklistRuntime").
+     * Used for file matching and logging.
+     */
+    public readonly className: string
+
+    /**
+     * Lifecycle state of this runtime instance.
+     */
+    private _state: GGTestRuntimeState = GGTestRuntimeState.CREATED
+
+    public get state(): GGTestRuntimeState {
+        return this._state;
+    }
+
+    /**
+     * Locator keys registered by this runtime.
+     * Populated via IPC after compose completes.
+     */
+    private readonly registeredLocatorKeys: Set<string> = new Set()
+
+    /**
+     * Commands to be sent to this runtime on startup.
+     * Queued before start(), passed to worker via env.
+     */
+    private readonly initialCommands: GGTestCommand[] = []
+
+    private readonly executablePath: string;
+    private readonly config: GGTestRuntimeConfig;
+    private runtimeRunner?: RuntimeRunner
+    /** Factory to create the runtime without dynamic import (used by inline mode) */
+    public runtimeFactory?: () => any;
+
+    /** Counter for generating unique runtime IDs per name */
+    private static runtimeCounters: Map<string, number> = new Map();
+
+    public constructor(runner: GGTestRunner, executablePath: string, className: string, name: string, config?: GGTestRuntimeConfig) {
+        this.executablePath = executablePath;
+        this.className = className;
+        this.name = name;
+        this.runtimeId = GGTestRuntime.generateRuntimeId(name);
+        this.config = config ?? {}
+        this.config.mode ??= GGTestMode.WORKER
+        this.runner = runner
+        this.runner.addRuntime(this);
+    }
+
+    private static generateRuntimeId(name: string): string {
+        const count = GGTestRuntime.runtimeCounters.get(name) ?? 0;
+        GGTestRuntime.runtimeCounters.set(name, count + 1);
+        return `${name}-${count}`;
+    }
+
+    public async start(): Promise<this> {
+        if (this._state !== GGTestRuntimeState.CREATED) {
+            throw new Error("Can only start runtimes if they are in CREATED state! Current state: " + this._state);
+        }
+        await new GGContext("Test").run(async () => {
+            GG_TRACE.init();
+            GGLog.debug(this, 'Launching ' + this.className + ' in ' + this.config.mode + ' mode...')
+
+            const config: GGTestEnvConfig = {
+                executablePath: this.executablePath,
+                className: this.className,
+                testRouterPort: this.runner.ipcServer.getPort(),
+                testId: this.runner.testId,
+                runtimeId: this.runtimeId,
+                initialCommands: this.initialCommands
+            }
+            switch (this.config.mode) {
+                case GGTestMode.INLINE:
+                    config.inline = true;
+                    this.runtimeRunner = new InlineRunner(config, this.runtimeFactory);
+                    break;
+                case GGTestMode.WORKER:
+                    this.runtimeRunner = new WorkerRunner(config);
+                    break;
+                case GGTestMode.ISOLATED:
+                    this.runtimeRunner = new IsolatedRunner(config);
+                    break;
+                default:
+                    throw new Error(`Unknown test mode: ${this.config.mode}`);
+            }
+
+            const startupTimeout = 30000;
+            try {
+                await withTimeout(
+                    this.runtimeRunner.start(),
+                    startupTimeout,
+                    'Service ' + this.className + ' failed to start within ' + startupTimeout + 'ms'
+                );
+                this._state = GGTestRuntimeState.STARTED;
+                GGLog.debug(this, this.className + ' started successfully')
+            } catch (error) {
+                // Mark as failed but keep runner alive for diagnostics (e.g., log retrieval)
+                this._state = GGTestRuntimeState.FAILED;
+                throw error;
+            }
+        });
+        return this
+    }
+
+    /**
+     * Stop the GGRuntime (teardown services) but keep worker/IPC alive.
+     * This allows log retrieval after the runtime has stopped.
+     * Idempotent - safe to call multiple times.
+     */
+    public async stop(): Promise<void> {
+        await new GGContext("Test").run(async () => {
+            GG_TRACE.init();
+            if (this._state === GGTestRuntimeState.STOPPED || this._state === GGTestRuntimeState.SHUTDOWN) {
+                // Already stopped or shutdown, nothing to do
+                return;
+            }
+            if (this._state === GGTestRuntimeState.FAILED) {
+                // Already failed, just mark as stopped
+                this._state = GGTestRuntimeState.STOPPED;
+                return;
+            }
+            if (this._state === GGTestRuntimeState.CREATED) {
+                // Never started (e.g., another runtime or hook failed first), nothing to stop
+                this._state = GGTestRuntimeState.STOPPED;
+                return;
+            }
+            if (this._state !== GGTestRuntimeState.STARTED) {
+                throw new Error("Can only stop runtimes in STARTED state! Current state: " + this._state);
+            }
+            GGLog.debug(this, 'Stopping ' + this.className + '...')
+            try {
+                await this.runtimeRunner?.stopRuntime()
+            } catch (error) {
+                GGLog.error(this, 'Error stopping ' + this.className, error)
+            }
+            this._state = GGTestRuntimeState.STOPPED;
+            GGLog.debug(this, this.className + ' stopped')
+        });
+    }
+
+    /**
+     * Fully shutdown the runtime and worker. IPC will be disconnected.
+     * After this, no commands can be sent.
+     */
+    public async shutdown(): Promise<void> {
+        await new GGContext("Test").run(async () => {
+            GG_TRACE.init();
+            if (this._state === GGTestRuntimeState.SHUTDOWN) {
+                return; // Already shutdown
+            }
+            GGLog.debug(this, 'Shutting down ' + this.className + '...')
+            try {
+                await this.runtimeRunner?.shutdown()
+            } catch (error) {
+                GGLog.error(this, 'Error shutting down ' + this.className, error)
+            }
+            this.runtimeRunner = undefined
+            this._state = GGTestRuntimeState.SHUTDOWN;
+            GGLog.debug(this, this.className + ' shut down')
+        });
+    }
+
+    public async sendCommand<Payload, Result>(type: IPCClientRequest<Payload, Result>, payload: Payload): Promise<Result> {
+        switch (this._state) {
+            case GGTestRuntimeState.CREATED:
+                this.initialCommands.push({method: type, payload: payload});
+                return undefined as Result;
+            case GGTestRuntimeState.STARTED:
+            case GGTestRuntimeState.FAILED:
+            case GGTestRuntimeState.STOPPED:
+                // IPC still available in these states
+                return await this.runner.ipcServer.sendFrameworkMessage(this.runtimeId, type, payload);
+            case GGTestRuntimeState.SHUTDOWN:
+                throw new Error(`Cannot send command to shut down runtime ${this.className}`);
+        }
+    }
+
+    // -----------
+    // Key registration (for callOn routing)
+    // -----------
+
+    /**
+     * Register multiple locator keys at once.
+     */
+    public registerLocatorKeys(keys: string[]): void {
+        for (const key of keys) {
+            this.registeredLocatorKeys.add(key);
+        }
+    }
+
+    /**
+     * Check if this runtime has a specific locator key.
+     */
+    public hasLocatorKey(key: string): boolean {
+        return this.registeredLocatorKeys.has(key);
+    }
+
+}