@grest-ts/testkit 0.0.5

package/src/runner/InlineRunner.ts

@@ -0,0 +1,47 @@
+import type {RuntimeRunner} from "./RuntimeRunner";
+import {GGTestRuntimeWorker} from "../GGTestRuntimeWorker";
+import {GGTestEnvConfig} from "../GGTestRuntime";
+import {GGLocatorScope} from "@grest-ts/locator";
+
+export class InlineRunner implements RuntimeRunner {
+
+    private controlClient?: GGTestRuntimeWorker;
+
+    constructor(
+        private readonly config: GGTestEnvConfig,
+        private readonly runtimeFactory?: () => any
+    ) {
+    }
+
+    async start(): Promise<void> {
+        // Use setTimeout + enterBlank() to create a fully isolated async context.
+        // This gives the inline runtime its own context tree where GGLog.init()
+        // creates an independent log context, similar to how Worker/Isolated modes
+        // naturally get separate contexts by running in different threads/processes.
+        const factory = this.runtimeFactory;
+        await new Promise<void>((resolve, reject) => {
+            setTimeout(async () => {
+                try {
+                    // Create blank context - inline runtime should not inherit test context
+                    new GGLocatorScope("GGInlineRunner").enter();
+                    this.controlClient = new GGTestRuntimeWorker(this.config);
+                    // Pass factory to avoid dynamic import() which causes duplicate
+                    // module loading in Vite/vitest environments
+                    await this.controlClient.start(factory);
+                    resolve();
+                } catch (err) {
+                    reject(err);
+                }
+            }, 0);
+        });
+    }
+
+    async stopRuntime(): Promise<void> {
+        await this.controlClient?.stopRuntime();
+    }
+
+    async shutdown(): Promise<void> {
+        await this.controlClient?.shutdown();
+        this.controlClient = undefined;
+    }
+}

package/src/runner/IsolatedRunner.ts

@@ -0,0 +1,179 @@
+import type {RuntimeRunner} from "./RuntimeRunner";
+import {type ChildProcess, spawn} from "child_process";
+import {GGLog} from "@grest-ts/logger";
+import {GGTestEnvConfig} from "../GGTestRuntime";
+
+const PROCESS_READY = "IsolatedRunner:READY"
+const GG_ISOLATED_CONFIG = "GG_ISOLATED_CONFIG";
+
+export class IsolatedRunner implements RuntimeRunner {
+    private process?: ChildProcess;
+
+    private static isolatedLoaderPath: string | undefined;
+
+    /**
+     * Set the path to the isolated-loader.mjs file.
+     * Called by @grest-ts/testkit-vitest to inject the path.
+     */
+    public static setIsolatedLoaderPath(path: string): void {
+        this.isolatedLoaderPath = path;
+    }
+
+    constructor(private config: GGTestEnvConfig) {
+    }
+
+    async start(): Promise<void> {
+        if (!IsolatedRunner.isolatedLoaderPath) {
+            throw new Error(
+                "Isolated loader path not set!\n" +
+                "Make sure to import '@grest-ts/testkit-vitest' in your vitest setup."
+            );
+        }
+
+        GGLog.debug(this, 'Starting isolated process for: ' + this.config.executablePath);
+
+        this.process = spawn('npx', ['tsx', IsolatedRunner.isolatedLoaderPath!, this.config.executablePath], {
+            env: {
+                ...process.env,
+                [GG_ISOLATED_CONFIG]: JSON.stringify(this.config)
+            },
+            stdio: ['pipe', 'pipe', 'pipe'], // pipe all streams so we can forward them properly
+            shell: true // Required for Windows to find npx
+        });
+
+        // Forward stderr to console.error so vitest can capture and sequence it
+        this.process.stderr?.setEncoding('utf8');
+        this.process.stderr?.on('data', (data: string) => {
+            const lines = data.split('\n');
+            for (const line of lines) {
+                if (line) console.error(line);
+            }
+        });
+
+        // Wait for process to signal ready via stdout
+        await new Promise<void>((resolve, reject) => {
+            if (!this.process) {
+                reject(new Error('Process failed to start'));
+                return;
+            }
+
+            const timeout = setTimeout(() => {
+                this.process?.kill('SIGKILL');
+                reject(new Error(`Process did not send READY signal within 10 seconds`));
+            }, 10000);
+
+            // Watch stdout for READY signal and forward all output using console.log
+            // so vitest can capture and sequence it properly with test output
+            this.process.stdout?.setEncoding('utf8');
+            let ready = false;
+            const onData = (data: string) => {
+                const lines = data.split('\n');
+                for (const line of lines) {
+                    if (line) console.log(line);
+                }
+                if (!ready && data.includes(PROCESS_READY)) {
+                    clearTimeout(timeout);
+                    GGLog.debug(this, 'Process ready');
+                    ready = true;
+                    resolve();
+                }
+            };
+            this.process.stdout?.on('data', onData);
+
+            this.process.once('error', (err) => {
+                clearTimeout(timeout);
+                reject(err);
+            });
+
+            this.process.once('exit', (code) => {
+                if (code !== 0 && code !== null) {
+                    clearTimeout(timeout);
+                    reject(new Error(`Process exited with code ${code} before sending READY signal`));
+                }
+            });
+        });
+    }
+
+    async stopRuntime(): Promise<void> {
+        if (!this.process) {
+            return;
+        }
+
+        GGLog.debug(this, 'Stopping runtime in process...');
+
+        const RUNTIME_STOPPED = 'IsolatedRunner:RUNTIME_STOPPED';
+
+        return new Promise<void>((resolve, reject) => {
+            if (!this.process) {
+                resolve();
+                return;
+            }
+
+            const timeout = setTimeout(() => {
+                GGLog.error(this, 'Timeout waiting for runtime to stop');
+                reject(new Error('Timeout waiting for runtime to stop'));
+            }, 5000);
+
+            // Listen for RUNTIME_STOPPED signal in stdout
+            const onData = (data: string) => {
+                if (data.includes(RUNTIME_STOPPED)) {
+                    clearTimeout(timeout);
+                    this.process?.stdout?.off('data', onData);
+                    GGLog.debug(this, 'Runtime stopped in process');
+                    resolve();
+                }
+            };
+            this.process.stdout?.on('data', onData);
+
+            // Send stop runtime command via stdin
+            try {
+                this.process.stdin?.write('STOP_RUNTIME\n');
+                GGLog.debug(this, 'Sent stop runtime command via stdin');
+            } catch (error) {
+                clearTimeout(timeout);
+                GGLog.error(this, 'Error sending stop runtime command', error);
+                reject(error);
+            }
+        });
+    }
+
+    async shutdown(): Promise<void> {
+        if (!this.process) {
+            return;
+        }
+
+        GGLog.debug(this, 'Shutting down process...');
+
+        return new Promise<void>((resolve) => {
+            if (!this.process) {
+                resolve();
+                return;
+            }
+
+            this.process.once('exit', () => {
+                clearTimeout(forceKillTimeout);
+                this.process = undefined;
+                GGLog.debug(this, 'Process shut down');
+                resolve();
+            });
+
+            // Send shutdown message via stdin (works cross-platform, unlike SIGTERM on Windows)
+            try {
+                this.process.stdin?.write('SHUTDOWN\n');
+                this.process.stdin?.end();
+                GGLog.debug(this, 'Sent shutdown command via stdin');
+            } catch (error) {
+                GGLog.error(this, 'Error sending shutdown command', error);
+            }
+
+            // Force kill after 2 seconds if still running
+            const forceKillTimeout = setTimeout(() => {
+                if (this.process && !this.process.killed) {
+                    GGLog.debug(this, 'Process did not exit gracefully, force killing');
+                    this.process.kill('SIGKILL');
+                    this.process = undefined;
+                }
+            }, 2000);
+        });
+    }
+}

package/src/runner/RuntimeRunner.ts

@@ -0,0 +1,15 @@
+export interface RuntimeRunner {
+    start(): Promise<void>;
+
+    /**
+     * Stop the GGRuntime (teardown services) but keep the worker/IPC alive.
+     * This allows log retrieval after the runtime has stopped.
+     */
+    stopRuntime(): Promise<void>;
+
+    /**
+     * Fully shutdown the worker, including IPC disconnection.
+     * After this, no commands can be sent.
+     */
+    shutdown(): Promise<void>;
+}

package/src/runner/WorkerRunner.ts

@@ -0,0 +1,179 @@
+import type {RuntimeRunner} from "./RuntimeRunner";
+import {Worker} from "worker_threads";
+import {GGLog} from "@grest-ts/logger";
+import {GGTestEnvConfig} from "../GGTestRuntime";
+
+export class WorkerRunner implements RuntimeRunner {
+    private worker?: Worker;
+
+    private static workerLoaderPath: string | undefined;
+
+    /**
+     * Set the path to the worker-loader.mjs file.
+     * Called by @grest-ts/testkit-vitest to inject the path.
+     */
+    public static setWorkerLoaderPath(path: string): void {
+        this.workerLoaderPath = path;
+    }
+
+    constructor(private readonly config: GGTestEnvConfig) {
+    }
+
+    async start(): Promise<void> {
+        GGLog.debug(this, 'Starting worker: ' + this.config.executablePath);
+
+        if (!WorkerRunner.workerLoaderPath) {
+            throw new Error(
+                "Worker loader path not set!\n" +
+                "Make sure to import '@grest-ts/testkit-vitest' in your vitest setup."
+            );
+        }
+        const workerLoaderPath = WorkerRunner.workerLoaderPath;
+
+        this.worker = new Worker(workerLoaderPath, {
+            workerData: this.config,
+            stdout: true,
+            stderr: true
+        });
+
+        // Forward worker stdout to parent's console using console.log
+        // so vitest can capture and sequence it properly with test output
+        this.worker.stdout.on('data', (data: Buffer) => {
+            const str = data.toString();
+            // Split by newlines and log each line (trimming trailing newline)
+            const lines = str.split('\n');
+            for (const line of lines) {
+                if (line) console.log(line);
+            }
+        });
+
+        // Forward worker stderr to parent's console
+        this.worker.stderr.on('data', (data: Buffer) => {
+            const str = data.toString();
+            const lines = str.split('\n');
+            for (const line of lines) {
+                if (line) console.error(line);
+            }
+        });
+
+        // Wait for worker to signal ready
+        try {
+            await new Promise<void>((resolve, reject) => {
+                if (!this.worker) {
+                    reject(new Error('Worker failed to start'));
+                    return;
+                }
+
+                const timeout = setTimeout(() => {
+                    // CRITICAL: Terminate worker on timeout to prevent leak
+                    this.worker?.terminate();
+                    reject(new Error('Worker did not start within 10 seconds'));
+                }, 10000);
+
+                const messageHandler = (msg: any) => {
+                    if (msg.type === 'ready') {
+                        clearTimeout(timeout);
+                        this.worker?.off('message', messageHandler);
+                        // Monitor for unexpected worker exit after successful startup
+                        this.worker?.on('exit', (code) => {
+                            GGLog.error(this, `Worker exited unexpectedly with code ${code}`);
+                        });
+                        GGLog.debug(this, 'Worker ready');
+                        resolve();
+                    } else if (msg.type === 'error') {
+                        clearTimeout(timeout);
+                        this.worker?.off('message', messageHandler);
+                        this.worker?.terminate();
+                        reject(new Error(`Runtime worker startup failed! ${msg.error}`));
+                    }
+                };
+
+                this.worker.on('message', messageHandler);
+
+                this.worker.once('error', (err) => {
+                    clearTimeout(timeout);
+                    this.worker?.terminate();
+                    reject(err);
+                });
+
+                this.worker.once('exit', (code) => {
+                    if (code !== 0) {
+                        clearTimeout(timeout);
+                        reject(new Error(`Worker exited with code ${code}`));
+                    }
+                });
+            });
+        } catch (error) {
+            // Ensure worker is cleaned up on any error
+            this.worker = undefined;
+            throw error;
+        }
+    }
+
+    async stopRuntime(): Promise<void> {
+        if (!this.worker) {
+            return;
+        }
+
+        GGLog.debug(this, 'Stopping runtime in worker...');
+
+        return new Promise<void>((resolve, reject) => {
+            if (!this.worker) {
+                resolve();
+                return;
+            }
+
+            const timeout = setTimeout(() => {
+                GGLog.error(this, 'Timeout waiting for runtime to stop');
+                reject(new Error('Timeout waiting for runtime to stop'));
+            }, 5000);
+
+            const messageHandler = (msg: any) => {
+                if (msg.type === 'runtimeStopped') {
+                    clearTimeout(timeout);
+                    this.worker?.off('message', messageHandler);
+                    GGLog.debug(this, 'Runtime stopped in worker');
+                    resolve();
+                }
+            };
+
+            this.worker.on('message', messageHandler);
+            this.worker.postMessage({type: 'stopRuntime'});
+        });
+    }
+
+    async shutdown(): Promise<void> {
+        if (!this.worker) {
+            return;
+        }
+
+        GGLog.debug(this, 'Shutting down worker...');
+
+        return new Promise<void>((resolve) => {
+            if (!this.worker) {
+                resolve();
+                return;
+            }
+
+            this.worker.once('exit', () => {
+                clearTimeout(forceTerminateTimeout);
+                this.worker = undefined;
+                GGLog.debug(this, 'Worker shut down');
+                resolve();
+            });
+
+            // Send shutdown message for graceful shutdown
+            this.worker.postMessage({type: 'shutdown'});
+
+            // Force terminate after 2 seconds if graceful shutdown doesn't work
+            const forceTerminateTimeout = setTimeout(() => {
+                if (this.worker) {
+                    GGLog.debug(this, 'Force terminating worker (timeout)');
+                    this.worker.terminate();
+                    this.worker = undefined;
+                    resolve();
+                }
+            }, 2000);
+        });
+    }
+}

package/src/runner/isolated-loader.mjs

@@ -0,0 +1,91 @@
+/**
+ * Isolated process loader for ES modules
+ * This file is the entry point for isolated test processes
+ *
+ * Usage: npx tsx isolated-loader.mjs <runtime-source-url>
+ * Environment: GG_ISOLATED_CONFIG must be set with JSON config
+ */
+import {register} from 'tsx/esm/api';
+import {pathToFileURL} from 'url';
+
+// Register tsx to handle TypeScript with ESM
+register();
+
+// Get the runtime source URL from command line args (can be file:// URL or path)
+let runtimeSourceUrl = process.argv[2];
+if (!runtimeSourceUrl) {
+    console.error('Usage: npx tsx isolated-loader.mjs <runtime-source-url>');
+    process.exit(1);
+}
+
+// Convert to file:// URL if it's a path
+if (!runtimeSourceUrl.startsWith('file:')) {
+    runtimeSourceUrl = pathToFileURL(runtimeSourceUrl).href;
+}
+
+const GG_ISOLATED_CONFIG = "GG_ISOLATED_CONFIG";
+const PROCESS_READY = "IsolatedRunner:READY";
+
+// Get config from environment
+const configJson = process.env[GG_ISOLATED_CONFIG];
+if (!configJson) {
+    console.error('GG_ISOLATED_CONFIG not set');
+    process.exit(1);
+}
+
+// Import runtime and testkit dependencies
+const {GGRuntime} = await import('@grest-ts/runtime');
+const {GGTestRuntimeWorker} = await import('@grest-ts/testkit');
+const {GGLog} = await import('@grest-ts/logger');
+
+const config = JSON.parse(configJson);
+
+// Override cli() to intercept runtime startup in isolated mode
+
+GGRuntime.cli = async function(moduleUrl) {
+    // Still set SOURCE_MODULE_URL for testkit compatibility
+    this.SOURCE_MODULE_URL = moduleUrl;
+
+    // Start the runtime via test worker instead of normal startup
+    const controlClient = new GGTestRuntimeWorker(config);
+
+    try {
+        await controlClient.start(() => new this());
+
+        // Signal to parent process that we're ready
+        console.log(PROCESS_READY);
+
+        const stopRuntime = async () => {
+            // Stop the GGRuntime but keep process alive for log retrieval
+            await controlClient.stopRuntime();
+            console.log('IsolatedRunner:RUNTIME_STOPPED');
+        };
+
+        const shutdown = async () => {
+            // Fully shutdown process
+            await controlClient.shutdown();
+            process.exit(0);
+        };
+
+        // Listen for commands via stdin
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (data) => {
+            const message = data.toString().trim();
+            if (message === 'STOP_RUNTIME') {
+                GGLog.debug({name: 'IsolatedLoader'}, 'Received stop runtime command');
+                stopRuntime();
+            } else if (message === 'SHUTDOWN') {
+                GGLog.debug({name: 'IsolatedLoader'}, 'Received shutdown command');
+                shutdown();
+            }
+        });
+        process.on('SIGTERM', shutdown);
+        process.on('SIGINT', shutdown);
+    } catch (err) {
+        GGLog.error({name: 'IsolatedLoader'}, 'Failed to start isolated runtime', err);
+        process.exit(1);
+    }
+};
+
+// Import the runtime source - this will call the overridden cli()
+await import(runtimeSourceUrl);

package/src/runner/worker-loader.mjs

@@ -0,0 +1,49 @@
+/**
+ * Worker loader for ES modules
+ * This file is loaded by worker threads to execute test runtimes
+ *
+ * workerData is GGTestEnvConfig: { executablePath, testRouterPort, testId, runtimeId, initialCommands }
+ */
+import {register} from 'tsx/esm/api';
+import {parentPort, workerData} from 'worker_threads';
+
+// Register tsx to handle TypeScript with ESM
+register();
+
+// Catch unhandled errors in worker thread
+process.on('uncaughtException', (err) => {
+    console.error(`[WorkerThread ${workerData?.runtimeId}] Uncaught exception:`, err);
+});
+process.on('unhandledRejection', (reason) => {
+    console.error(`[WorkerThread ${workerData?.runtimeId}] Unhandled rejection:`, reason);
+});
+
+// workerData is GGTestEnvConfig directly
+const config = workerData;
+
+// Import control client from @grest-ts/testkit
+const {GGTestRuntimeWorker} = await import('@grest-ts/testkit');
+
+// Create control client
+const controlClient = new GGTestRuntimeWorker(config);
+
+// Start the runtime
+try {
+    await controlClient.start();
+    parentPort.postMessage({type: 'ready'});
+} catch (err) {
+    parentPort.postMessage({type: 'error', error: err.stack || err.message});
+}
+
+// Handle messages from parent
+parentPort.on('message', async (msg) => {
+    if (msg.type === 'stopRuntime') {
+        // Stop the GGRuntime but keep worker alive for log retrieval
+        await controlClient.stopRuntime();
+        parentPort.postMessage({type: 'runtimeStopped'});
+    } else if (msg.type === 'shutdown') {
+        // Fully shutdown worker
+        await controlClient.shutdown();
+        process.exit(0);
+    }
+});