@grest-ts/testkit 0.0.5

package/src/testers/GGTestAction.ts

@@ -0,0 +1,333 @@
+import {IGGTestWith} from "./IGGTestWith";
+import {IGGTestInterceptor} from "./IGGTestInterceptor";
+import {GGLog} from "@grest-ts/logger";
+import {LOG_COLORS} from "@grest-ts/logger-console";
+import {captureStackSourceFile} from "../utils/captureStack";
+import {GGContext} from "@grest-ts/context";
+import {GG_TRACE} from "@grest-ts/trace";
+import {Raw} from "@grest-ts/schema";
+import {DeepPartial} from "@grest-ts/common";
+import {GGExpectations} from "../utils/GGExpectations";
+
+interface WaitForInterceptor {
+    interceptor: IGGTestInterceptor;
+    timeout: number;
+}
+
+/**
+ * Configuration for a test action's logging behavior.
+ */
+export interface GGTestActionConfig {
+    /** If true, the action has no response to log (e.g., fire-and-forget WebSocket message) */
+    noResponse: boolean;
+    /** Data used for logging the action */
+    logData: {
+        /** Description shown in logs, e.g., "[POST /api/users]" or "[Config MyConfig.timeout]" */
+        message: string;
+        /** Optional context to display (e.g., auth, language) */
+        context?: any;
+        /** Optional request payload to log when executing */
+        request?: any
+    };
+}
+
+/**
+ * Base class for test actions that can be awaited and chained with expectations.
+ *
+ * Test actions are PromiseLike objects that execute when awaited. They support
+ * attaching interceptors (mocks, log expectations, spies) that are validated
+ * during execution.
+ *
+ * @example
+ * // Simple action - just await to execute
+ * const user = await client.getUser(123);
+ *
+ * // With sync expectation - mock must be called during the action
+ * await client.createUser({name: "Alice"})
+ *     .with(mockEmailService.sendWelcome.toBeCalledOnce());
+ *
+ * // With async expectation - waits for event after action completes
+ * await client.triggerAsyncJob()
+ *     .waitFor(t.logs.expect("Job completed"), 10000);
+ *
+ * @typeParam T - The type returned when the action completes
+ */
+export abstract class GGTestAction<T> implements Promise<T> {
+
+    readonly [Symbol.toStringTag]: string = "GGTestAction";
+
+    protected readonly ctx: GGContext;
+    private readonly config: GGTestActionConfig;
+    protected readonly interceptors: IGGTestInterceptor[] = [];
+    protected readonly _waitForInterceptors: WaitForInterceptor[] = [];
+    private readonly definedInSourceFile: string;
+
+    protected readonly responseExpectations: GGExpectations<any> = new GGExpectations()
+
+    constructor(ctx: GGContext, config: GGTestActionConfig) {
+        if (ctx === undefined) throw new Error("No ctx provided!")
+        this.ctx = ctx;
+        this.config = config;
+        this.definedInSourceFile = captureStackSourceFile();
+        new GGContext("Test").run(() => {
+            GG_TRACE.init();
+            const separator = "-".repeat(100);
+            GGLog.info(this, separator)
+            GGLog.info(this,
+                this.logMsg("new", this.config.logData.message)
+                + (this.config.logData.context ? "\n" + LOG_COLORS.bgOrange + LOG_COLORS.black
+                    + "Context: " + LOG_COLORS.reset + LOG_COLORS.orange + JSON.stringify(this.config.logData.context) + LOG_COLORS.reset : "")
+                + "\n" + this.definedInSourceFile
+            );
+        });
+
+    }
+
+    public toEqual(expectedData: Raw<T>): this {
+        this.responseExpectations.toEqual(expectedData as T);
+        return this;
+    }
+
+    public toMatchObject(expectedData: DeepPartial<Raw<T>>): this {
+        this.responseExpectations.toMatchObject(expectedData as T);
+        return this;
+    }
+
+    public toBeUndefined(): this {
+        this.responseExpectations.toBeUndefined();
+        return this;
+    }
+
+    public toHaveLength(length: number): this {
+        this.responseExpectations.toHaveLength(length);
+        return this;
+    }
+
+    public arrayToContain<Item extends T extends Array<infer R> ? R : never>(...items: Partial<Raw<Item>>[]): this {
+        this.responseExpectations.arrayToContain(...items);
+        return this;
+    }
+
+    public arrayToContainEqual<Item extends T extends Array<infer R> ? R : never>(...items: Partial<Raw<Item>>[]): this {
+        this.responseExpectations.arrayToContainEqual(...items);
+        return this;
+    }
+
+    /**
+     * Attach expectations that must be satisfied during action execution.
+     *
+     * Interceptors are registered before the action runs and validated immediately after.
+     * If an expectation fails (e.g., mock not called), the test fails before checking
+     * the action's response - this surfaces the root cause of failures first.
+     *
+     * @example
+     * await client.createOrder({items: [...]})
+     *     .with(mockInventory.reserve.toBeCalledOnce())
+     *     .with(mockPayment.charge.toMatchObject({amount: 100}));
+     */
+    public with(...expectations: IGGTestWith[]): this {
+        for (const expectation of expectations) {
+            // Check if this expectation requires async processing
+            if (expectation.requiresWaitFor?.()) {
+                throw new Error(
+                    `This interceptor cannot be used with .with() because it handles async events ` +
+                    `that occur after the HTTP response.\n\n` +
+                    `SQS message processing happens asynchronously - the message is delivered to the ` +
+                    `subscriber queue after the HTTP request completes.\n\n` +
+                    `To verify SQS events, use one of these approaches:\n` +
+                    `  1. Use .waitFor() with log verification:\n` +
+                    `     .waitFor(t.worker.logs.expect(/expected log message/))\n\n` +
+                    `  2. Use .waitFor() with the SQS interceptor (waits for async processing):\n` +
+                    `     .waitFor(SqsResource.spy.toMatchObject({...}))\n`
+                );
+            }
+            this.interceptors.push(expectation.createInterceptor());
+        }
+        return this;
+    }
+
+    /**
+     * Attach an expectation that may be satisfied after the action completes.
+     *
+     * Use this for async side effects - when the action triggers something that
+     * happens later (e.g., background job, delayed log, async notification).
+     * The test will poll until the expectation is satisfied or timeout is reached.
+     *
+     * @param expectation - The expectation to wait for
+     * @param timeout - Max time to wait in ms (default: 5000)
+     *
+     * @example
+     * // Action returns immediately, but logs after 100ms
+     * await client.triggerBackgroundJob({id: 123})
+     *     .waitFor(t.logs.expect("Job 123 completed"), 10000);
+     */
+    public waitFor(expectation: IGGTestWith, timeout: number = 5000): this {
+        const interceptor = expectation.createInterceptor();
+        this.interceptors.push(interceptor);
+        this._waitForInterceptors.push({
+            interceptor,
+            timeout
+        });
+        return this;
+    }
+
+    public then<TResult1 = T, TResult2 = never>(
+        onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null,
+        onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
+    ): Promise<TResult1 | TResult2> {
+        return this.execute().then(onfulfilled, onrejected);
+    }
+
+    public catch<TResult = never>(
+        onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null
+    ): Promise<T | TResult> {
+        return this.execute().catch(onrejected);
+    }
+
+    public finally(onfinally?: (() => void) | null): Promise<T> {
+        return this.execute().finally(onfinally);
+    }
+
+    protected async execute(): Promise<T> {
+        return this.ctx.run(async () => {
+            GG_TRACE.init();
+            GGLog.info(this,
+                this.logMsg("execute", this.config.logData.message),
+                this.config.logData.request
+            )
+            let rawResult: tActionRawData = undefined;
+            try {
+                await Promise.all(this.interceptors.map(i => i.register()));
+                rawResult = await this.executeAction()
+                await new Promise(resolve => setTimeout(resolve, 25));
+            } finally {
+                await Promise.all(this.interceptors.map(i => i.unregister()));
+            }
+
+            const waitForSet = new Set(this._waitForInterceptors.map(w => w.interceptor));
+
+            // Validate non-wait interceptors immediately
+            for (const interceptor of this.interceptors) {
+                if (!waitForSet.has(interceptor)) {
+                    await interceptor.validate();
+                }
+            }
+
+            // Check for validation errors from non-wait interceptors
+            for (const interceptor of this.interceptors) {
+                if (!waitForSet.has(interceptor)) {
+                    const error = interceptor.getMockValidationError();
+                    if (error) {
+                        throw error;
+                    }
+                }
+            }
+
+            let result: any = undefined;
+            if (!this.config.noResponse) {
+                result = await this.processRawResponse(rawResult);
+                this.responseExpectations.check(result);
+            }
+
+            if (this._waitForInterceptors.length > 0) {
+                await this._waitForAllInterceptors();
+            }
+
+            // Validate wait interceptors after waiting
+            for (const {interceptor} of this._waitForInterceptors) {
+                await interceptor.validate();
+                const error = interceptor.getMockValidationError();
+                if (error) {
+                    throw error;
+                }
+            }
+
+            GGLog.info(this,
+                this.logMsg("finished", this.config.logData.message),
+                this.config.noResponse ? "Result: (void)" : rawResult
+            )
+
+            return result;
+        });
+    }
+
+    /**
+     * Execute the core action (e.g., make HTTP request, send WebSocket message).
+     * Subclasses implement this with their specific action logic.
+     *
+     * @returns The raw response data (before parsing/transformation)
+     */
+    protected abstract executeAction(): Promise<tActionRawData>;
+
+    /**
+     * Process and validate the raw response from executeAction().
+     * Called AFTER mock validation, so mock errors surface first.
+     *
+     * Subclasses implement this to:
+     * - Parse the raw response into the expected type T
+     * - Check response expectations (e.g., toMatchObject, toEqual)
+     *
+     * @param result - Raw response from executeAction()
+     * @returns The parsed/validated result of type T
+     */
+    protected processRawResponse(result: tActionRawData): Promise<T> {
+        return result;
+    }
+
+    private async _waitForAllInterceptors(): Promise<void> {
+        const pending = new Map(
+            this._waitForInterceptors.map(w => [w.interceptor, w.timeout])
+        );
+
+        const checkInterval = 20;
+        const actionEndTime = Date.now();
+
+        return new Promise((resolve, reject) => {
+            const check = () => {
+                const elapsed = Date.now() - actionEndTime;
+
+                for (const [interceptor, timeout] of pending) {
+                    if (interceptor.isCalled()) {
+                        pending.delete(interceptor);
+                    } else if (elapsed > timeout) {
+                        reject(new Error(
+                            `[Test Failed] Timeout waiting for interceptor after ${timeout}ms`
+                        ));
+                        return;
+                    }
+                }
+
+                if (pending.size === 0) {
+                    resolve();
+                    return;
+                }
+
+                setTimeout(check, checkInterval);
+            };
+
+            check();
+        });
+    }
+
+    private logMsg(type: "new" | "execute" | "finished", msg: string): string {
+        let pref = "";
+        let color: string = "";
+        if (type === "new") {
+            pref = "New test action "
+            color = LOG_COLORS.reset + LOG_COLORS.bgBlack + LOG_COLORS.white
+        } else if (type === "execute") {
+            pref = "Executing test action to "
+            color = LOG_COLORS.reset + LOG_COLORS.bgGray + LOG_COLORS.black
+        } else if (type === "finished") {
+            pref = "Finished test action to "
+            color = LOG_COLORS.reset + LOG_COLORS.bgGray + LOG_COLORS.black
+        }
+        return color + pref + msg + LOG_COLORS.reset;
+    }
+}
+
+/**
+ * Branded type for raw action response data.
+ * Used to distinguish raw responses from parsed results in the type system.
+ */
+export type tActionRawData = any & { tActionRawData: never }

package/src/testers/GGTestComponent.ts

@@ -0,0 +1,16 @@
+import type {GGTestRunner} from "../GGTestRunner";
+
+/**
+ * Interface for test components that can be registered with GGTestRunner.
+ * Components must accept GGTestRunner as their constructor argument.
+ */
+export interface GGTestComponent {
+    start?(): Promise<void>;
+    afterEach?(): Promise<void>;
+    teardown?(): Promise<void>;
+}
+
+/**
+ * Constructor type for components. All components must accept GGTestRunner as constructor argument.
+ */
+export type GGTestComponentType<T extends GGTestComponent> = new (runner: GGTestRunner) => T;

package/src/testers/GGTestSelector.ts

@@ -0,0 +1,223 @@
+import {RuntimeConstructor, RuntimeResult, Selector, SelectorExtensions, ObjectResult, StartResult, RuntimeInput} from "./RuntimeSelector";
+import {GGTestRuntime} from "../GGTestRuntime";
+import type {GGTestRunner} from "../GGTestRunner";
+
+/**
+ * Internal implementation class for Selector.
+ * Works with GGTestRuntime instances directly.
+ */
+export class GGTestSelector<T extends RuntimeConstructor[]> {
+
+    private static readonly extensions = new Map<string, typeof GGTestSelectorExtension>();
+
+    public readonly runtimes: GGTestRuntime[];
+    private readonly extensionCache = new Map<string, unknown>();
+
+    constructor(runtimes: GGTestRuntime[]) {
+        this.runtimes = runtimes;
+    }
+
+    public get length(): number {
+        return this.runtimes.length;
+    }
+
+    public static addExtension(factory: typeof GGTestSelectorExtension & { PROPERTY_NAME: string }): void {
+        if (this.extensions.has(factory.PROPERTY_NAME)) {
+            throw new Error("Extension with name '" + factory.PROPERTY_NAME + "' is already registered!")
+        }
+        this.extensions.set(factory.PROPERTY_NAME, factory);
+    }
+
+    public static hasExtension(name: string): boolean {
+        return this.extensions.has(name);
+    }
+
+    public getExtension<K extends keyof SelectorExtensions<T>>(name: K): SelectorExtensions<T>[K] {
+        const cached = this.extensionCache.get(name as string);
+        if (cached !== undefined) {
+            return cached as SelectorExtensions<T>[K];
+        }
+
+        const extension = GGTestSelector.extensions.get(name);
+        if (!extension) {
+            throw new Error(`Extension '${String(name)}' is not registered. ` +
+                `Make sure the module providing this extension is imported.`);
+        }
+
+        const extensionInstance = new extension(this.runtimes);
+        this.extensionCache.set(name as string, extensionInstance);
+        return extensionInstance as SelectorExtensions<T>[K];
+    }
+
+    /**
+     * Stop all runtimes in this selector.
+     */
+    public async stop(): Promise<void> {
+        for (const runtime of this.runtimes) {
+            await runtime.stop();
+        }
+    }
+
+    /**
+     * Shutdown all runtimes in this selector.
+     */
+    public async shutdown(): Promise<void> {
+        for (const runtime of this.runtimes) {
+            await runtime.shutdown();
+        }
+    }
+}
+
+export class GGTestSelectorExtension {
+
+    protected readonly runner: GGTestRunner
+
+    constructor(protected readonly runtimes: GGTestRuntime[]) {
+        this.runner = this.runtimes[0]?.runner
+    }
+
+    protected async forEachParallel(callback: (runtime: GGTestRuntime) => Promise<void>): Promise<void> {
+        const results = await Promise.allSettled(
+            this.runtimes.map(runtime => callback(runtime))
+        );
+        const errors = results
+            .filter((r): r is PromiseRejectedResult => r.status === 'rejected')
+            .map(r => r.reason);
+
+        if (errors.length > 0) {
+            throw new AggregateError(errors, `${errors.length} runtime(s) failed`);
+        }
+    }
+}
+
+/**
+ * Create a proxied Selector that supports:
+ * - Indexed access: selector[0]
+ * - Extension access: selector.config, selector.logs
+ * - Lifecycle methods: selector.stop(), selector.shutdown()
+ * - Standard properties: selector.runtimes, selector.length
+ */
+export function createSelector<T extends RuntimeConstructor[]>(runtimes: GGTestRuntime[]): Selector<T> {
+    const impl = new GGTestSelector<T>(runtimes);
+
+    return new Proxy(impl as unknown as Selector<T>, {
+        get(target, prop) {
+            const implTarget = target as unknown as GGTestSelector<T>;
+
+            // Handle numeric index access: selector[0]
+            if (typeof prop === 'string' && /^\d+$/.test(prop)) {
+                const index = parseInt(prop, 10);
+                if (index >= 0 && index < implTarget.runtimes.length) {
+                    return createSelector([implTarget.runtimes[index]]);
+                }
+                return undefined;
+            }
+
+            // Handle extension access: selector.config, selector.logs, etc.
+            if (typeof prop === 'string' && GGTestSelector.hasExtension(prop)) {
+                return implTarget.getExtension(prop as keyof SelectorExtensions<T>);
+            }
+
+            // Handle methods and properties from impl
+            return Reflect.get(implTarget, prop);
+        }
+    }) as Selector<T>;
+}
+
+// ============================================================================
+// Factory functions for different input shapes
+// ============================================================================
+
+/**
+ * Create result based on input shape.
+ * - Single runtime → Selector
+ * - Array of runtimes → Selector
+ * - Object → ObjectResult with named selectors
+ */
+export function createStartResult<T extends RuntimeInput>(
+    input: T,
+    runtimes: GGTestRuntime[]
+): StartResult<T> {
+    // Object input: { main: MainRuntime, sub: SubRuntime }
+    if (isObjectInput(input)) {
+        return createObjectResult(input, runtimes) as StartResult<T>;
+    }
+
+    // Array or single runtime → Selector
+    return createSelector(runtimes) as StartResult<T>;
+}
+
+/**
+ * Check if input is an object (not a constructor or array).
+ */
+function isObjectInput(input: RuntimeInput): input is Record<string, RuntimeConstructor | RuntimeConstructor[]> {
+    return typeof input === 'object' && !Array.isArray(input) && !('NAME' in input);
+}
+
+/**
+ * Create ObjectResult for object input.
+ */
+function createObjectResult<T extends Record<string, RuntimeConstructor | RuntimeConstructor[]>>(
+    input: T,
+    runtimes: GGTestRuntime[]
+): ObjectResult<T> {
+    const result: Record<string, Selector<any>> = {};
+
+    // Group runtimes by the key they were registered under
+    // We need to track which runtimes belong to which key
+    for (const [key, value] of Object.entries(input)) {
+        const constructors = Array.isArray(value) ? value : [value];
+        const names = constructors.map(c => c.NAME);
+        const keyRuntimes = runtimes.filter(r => names.includes(r.name));
+        result[key] = createSelector(keyRuntimes);
+    }
+
+    // Add stop/shutdown that affects all runtimes
+    (result as any).stop = async () => {
+        for (const runtime of runtimes) {
+            await runtime.stop();
+        }
+    };
+
+    (result as any).shutdown = async () => {
+        for (const runtime of runtimes) {
+            await runtime.shutdown();
+        }
+    };
+
+    return result as ObjectResult<T>;
+}
+
+// ============================================================================
+// Legacy factory (for backwards compatibility)
+// ============================================================================
+
+/**
+ * @deprecated Use createStartResult instead.
+ * Create a RuntimeResult for accessing runtimes via get() method.
+ */
+export function createRuntimeSelector<T extends RuntimeConstructor[]>(runtimes: GGTestRuntime[]): RuntimeResult<T> {
+    return {
+        get(runtimeConstructor: RuntimeConstructor): Selector<any> {
+            const name = runtimeConstructor.NAME;
+            const filtered = runtimes.filter(r => r.name === name);
+            return createSelector(filtered);
+        },
+
+        all(): Selector<any> {
+            return createSelector(runtimes);
+        },
+
+        async stop(): Promise<void> {
+            for (const runtime of runtimes) {
+                await runtime.stop();
+            }
+        },
+
+        async shutdown(): Promise<void> {
+            for (const runtime of runtimes) {
+                await runtime.shutdown();
+            }
+        }
+    } as RuntimeResult<T>;
+}

package/src/testers/IGGTestInterceptor.ts

@@ -0,0 +1,11 @@
+export interface IGGTestInterceptor {
+    register(): void | Promise<void>;
+
+    unregister(): void | Promise<void>;
+
+    validate(): void | Promise<void>;
+
+    getMockValidationError(): Error | undefined;
+
+    isCalled(): boolean;
+}

package/src/testers/IGGTestWith.ts

@@ -0,0 +1,15 @@
+import {IGGTestInterceptor} from "./IGGTestInterceptor";
+
+export interface IGGTestWith {
+    createInterceptor(): IGGTestInterceptor;
+
+    /**
+     * Returns true if this expectation requires async processing and must be used with `.waitFor()`.
+     * When true, using with `.with()` will throw an error guiding the developer to use `.waitFor()`.
+     *
+     * Example: SQS message processing is async (happens after HTTP response), so SQS
+     * interceptors require `.waitFor()`.
+     */
+    requiresWaitFor?(): boolean;
+}
+