@grest-ts/testkit 0.0.5

package/src/callOn/callOn.ts

@@ -0,0 +1,224 @@
+/**
+ * Unified callOn function for invoking methods on runtime instances.
+ *
+ * Works with:
+ * - @testable classes: Direct service invocation via IPC
+ * - GGLocatorKey: Direct instance lookup via IPC
+ * - GGContractClass: Contract implementation lookup via IPC
+ * - Contract holders (HTTP APIs, etc.): Delegated to their own factory
+ *
+ * @example
+ * // Call @testable service
+ * await callOn(MyService).doSomething("hello")
+ *
+ * // Call HTTP API (goes through HTTP transport)
+ * await callOn(ChainApi).quickWeatherCheck({city: "NYC"})
+ *
+ * // Call contract directly (skips HTTP, uses IPC)
+ * await callOn(ChainApiContract).quickWeatherCheck({city: "NYC"})
+ *
+ * // With context
+ * await callOn(MyService, ctx).doSomething("hello")
+ */
+
+import {GGLocatorKey} from "@grest-ts/locator";
+import {GGTestActionForLocatorOnCall} from "./GGTestActionForLocatorOnCall";
+import {LOCATOR_KEY_PREFIX_FOR_TESTABLE} from "@grest-ts/testkit-runtime";
+import {GGContractApiDefinition, GGContractClass, GGContractMethod} from "@grest-ts/schema";
+import {GGContext} from "@grest-ts/context";
+import {LOCATOR_KEY_PREFIX_FOR_CONTRACT} from "./GGContractClass.implement";
+import type {GGTestRuntime} from "../GGTestRuntime";
+
+// ============================================================================
+// Factory symbol for protocol-specific callOn support
+// ============================================================================
+
+/**
+ * Symbol used by contract holders (HTTP APIs, WebSocket APIs, etc.) to provide
+ * their own callOn proxy. This allows protocols to control how calls are made
+ * without callOn needing to know about specific protocols.
+ *
+ * The factory can return anything - there's no constraint on the return type.
+ * Each protocol fully controls what methods and types are available.
+ */
+export const CALL_ON_FACTORY = Symbol.for("gg:callOnFactory");
+
+/**
+ * Marker interface for targets that provide their own callOn proxy.
+ * The factory can return any type - protocols have full control.
+ */
+export interface GGCallOnFactory {
+    [CALL_ON_FACTORY](ctx?: GGContext): unknown;
+}
+
+// ============================================================================
+// Type definitions
+// ============================================================================
+
+/**
+ * Maps a class's async methods to GGLocatorLookupTestAction calls.
+ * Used for @testable classes and GGLocatorKey lookups.
+ */
+export type LocatorLookupAccess<T> = {
+    [K in keyof T]: T[K] extends (...args: infer A) => Promise<infer R>
+        ? (...args: A) => GGTestActionForLocatorOnCall<R>
+        : never
+};
+
+/**
+ * Maps contract methods to GGLocatorLookupTestAction calls.
+ * Used for direct GGContractClass lookups via IPC.
+ */
+export type ContractLocatorAccess<TContract> = {
+    [K in keyof TContract]: TContract[K] extends GGContractMethod<infer Input, infer Output>
+        ? Input extends undefined ? () => GGTestActionForLocatorOnCall<Output> : (data: Input) => GGTestActionForLocatorOnCall<Output>
+        : never
+};
+
+export type GGTestCallOnCollection<T> = { [K in keyof T]: GGTestCallOn<T[K]> }
+
+/**
+ * Resolves the return type for callOn(target):
+ * - Factory targets → extract factory's return type (protocol controls everything)
+ * - GGContractClass → ContractLocatorAccess (IPC)
+ * - Constructor/GGLocatorKey → LocatorLookupAccess (IPC)
+ * - Plain objects → recurse into properties
+ */
+export type GGTestCallOn<T> =
+    T extends { [CALL_ON_FACTORY]: (ctx?: GGContext) => infer R } ? R
+        : T extends GGContractClass<infer TContract> ? ContractLocatorAccess<TContract>
+            : T extends GGLocatorKey<infer Instance> ? LocatorLookupAccess<Instance>
+                : T extends new (...args: any[]) => infer Instance ? LocatorLookupAccess<Instance>
+                    : T extends object ? { [K in keyof T]: GGTestCallOn<T[K]> }
+                        : never;
+
+// ============================================================================
+// The callOn function
+// ============================================================================
+
+/**
+ * Check if target implements the CALL_ON_FACTORY interface.
+ */
+function hasCallOnFactory(target: unknown): target is GGCallOnFactory {
+    return target != null && typeof (target as any)[CALL_ON_FACTORY] === 'function';
+}
+
+/**
+ * Check if target is a simple class (constructor function).
+ */
+function isSimpleClass(value: unknown): value is new (...args: any[]) => any {
+    return typeof value === 'function' && value.prototype !== undefined && value.prototype.constructor === value;
+}
+
+/**
+ * Invoke methods on runtime instances via a unified interface.
+ *
+ * Resolution order:
+ * 1. Factory symbol (HTTP APIs, WebSocket APIs provide their own)
+ * 2. GGContractClass → IPC lookup via @contract: prefix
+ * 3. GGLocatorKey → IPC lookup via key name
+ * 4. Simple class → IPC lookup via @testable: prefix
+ *
+ * @example
+ * await callOn(MyService, ctx).doSomething("hello")
+ * await callOn(ChainApi, ctx).quickWeatherCheck({city: "NYC"})
+ * await callOn(ChainApiContract, ctx).quickWeatherCheck({city: "NYC"})
+ */
+export function callOn<T extends GGCallOnFactory>(target: T, ctx?: GGContext): GGTestCallOn<T>;
+export function callOn<T extends GGContractApiDefinition>(target: GGContractClass<T>, ctx?: GGContext): ContractLocatorAccess<T>;
+export function callOn<T>(target: GGLocatorKey<T>, ctx?: GGContext): LocatorLookupAccess<T>;
+export function callOn<T extends new (...args: any[]) => any>(target: T, ctx?: GGContext): LocatorLookupAccess<InstanceType<T>>;
+export function callOn<T extends object>(target: T, ctx?: GGContext): GGTestCallOn<T>;
+export function callOn(target: any, ctx?: GGContext): any {
+    ctx ??= new GGContext("Test")
+
+    if (hasCallOnFactory(target)) {
+        return target[CALL_ON_FACTORY](ctx);
+    }
+
+    const keyName = resolveKeyName(target);
+    return createCallOnProxy(keyName, ctx);
+}
+
+// ============================================================================
+// Helper functions for key resolution
+// ============================================================================
+
+/**
+ * Resolve a target to its locator key name.
+ * Handles GGContractClass, GGLocatorKey, and simple classes.
+ */
+function resolveKeyName(target: any): string {
+    if (target instanceof GGContractClass) {
+        return LOCATOR_KEY_PREFIX_FOR_CONTRACT + target.name;
+    }
+    if (target instanceof GGLocatorKey) {
+        return target.name;
+    }
+    if (isSimpleClass(target)) {
+        return LOCATOR_KEY_PREFIX_FOR_TESTABLE + target.name;
+    }
+    throw new Error(`Unknown callOn target: ${target?.name ?? target?.constructor?.name ?? typeof target}`);
+}
+
+/**
+ * Create a proxy that intercepts method calls and returns GGTestActionForLocatorOnCall.
+ */
+function createCallOnProxy(keyName: string, ctx: GGContext, targetRuntimes?: GGTestRuntime[]): any {
+    return new Proxy({}, {
+        get(_, methodName: string) {
+            return (...args: any[]) => new GGTestActionForLocatorOnCall<any>(ctx, keyName, methodName, args, targetRuntimes);
+        }
+    });
+}
+
+// ============================================================================
+// Targeted callOn - for explicit runtime selection
+// ============================================================================
+
+/**
+ * Invoke methods on runtime instances, targeting specific runtimes.
+ * Use this when you need to explicitly select which runtime to call
+ * when multiple different runtime classes have the same service.
+ *
+ * @param target - The target to call (class, GGLocatorKey, or GGContractClass)
+ * @param runtimes - The specific runtimes to target
+ * @param ctx - Optional context for the call
+ *
+ * @example
+ * const f = GGTest.startWorker({chain: ChainRuntime, weather: WeatherOnlyRuntime});
+ * // Both have WeatherService - explicitly target one:
+ * await f.chain.callOn(WeatherService).getWeather("Test")
+ */
+export function callOnTargeted<T>(target: T, runtimes: GGTestRuntime[], ctx?: GGContext): GGTestCallOn<T>;
+export function callOnTargeted(target: any, runtimes: GGTestRuntime[], ctx?: GGContext): any {
+    ctx ??= new GGContext("Test");
+
+    // Factory targets don't support runtime targeting - they control their own routing
+    if (hasCallOnFactory(target)) {
+        return target[CALL_ON_FACTORY](ctx);
+    }
+
+    const keyName = resolveKeyName(target);
+    return createCallOnProxy(keyName, ctx, runtimes);
+}
+
+/**
+ * Process a collection of targets and create callOn proxies for each.
+ * It can be a recursive object where all "testable things" are replaced with callOn(X) handlers.
+ * {serviceA: ApiA, sub: { serviceB: ApiB}} -> {serviceA: callOn(ApiA), sub: { serviceB: callOn(ApiB)}}
+ */
+export function callOnCollection<T extends object | any[]>(target: T, ctx?: GGContext): GGTestCallOnCollection<T> {
+    const result: any = Array.isArray(target) ? [] : {};
+    for (const key in target) {
+        const value = target[key];
+        if (value != null) {
+            if (hasCallOnFactory(value) || value instanceof GGContractClass || value instanceof GGLocatorKey || isSimpleClass(value)) {
+                result[key] = callOn(value as any, ctx);
+            } else if (typeof value === 'object') {
+                result[key] = callOnCollection(value, ctx);
+            }
+        }
+    }
+    return result;
+}

package/src/callOn/registerOnCallHandler.ts

@@ -0,0 +1,123 @@
+/**
+ * Worker-side handler for GGLocator-based service invocation.
+ *
+ * Receives IPC requests from tests to invoke methods on registered instances
+ * (@testable, @contract, etc.) and returns the results.
+ */
+
+import {GGLocator, GGLocatorKey} from "@grest-ts/locator";
+import {GGLog} from "@grest-ts/logger";
+import {SerializedContext, TestableIPC, TestableInvokePayload, TestableInvokeResult} from "./TestableIPC";
+import {GGTestRuntimeWorker} from "../GGTestRuntimeWorker";
+import {GGContext} from "@grest-ts/context";
+
+/**
+ * Context for logging
+ */
+const LOG_CONTEXT = {name: "GGLocatorWorkerHandler"};
+
+/**
+ * Deserialize context data into a GGContext.
+ * Directly populates the internal values map.
+ */
+function deserializeContext(data: SerializedContext): GGContext {
+    const ctx = new GGContext("ipc-context");
+    // Access internal values map and populate directly
+    const ctxAny = ctx as any;
+    for (const [keyName, value] of Object.entries(data)) {
+        ctxAny.values.set(keyName, value);
+    }
+    return ctx;
+}
+
+/**
+ * Register the locator lookup handler on the worker.
+ * Called during worker initialization.
+ */
+export function registerOnCallHandler(worker: GGTestRuntimeWorker): void {
+    worker.onIpcRequest(TestableIPC.invoke, async (payload: TestableInvokePayload): Promise<TestableInvokeResult> => {
+        const {keyName, methodName, args, context} = payload;
+
+        GGLog.debug(LOG_CONTEXT, `Invoking ${keyName}.${methodName}`, {args, hasContext: !!context});
+
+        try {
+            // Look up the instance in the current scope
+            const scope = GGLocator.tryGetScope();
+            if (!scope) {
+                return {
+                    success: false,
+                    error: `No GGLocator scope available - is the runtime running?`
+                };
+            }
+
+            const key = new GGLocatorKey<any>(keyName);
+            const instance = scope.tryGet(key);
+
+            if (!instance) {
+                return {
+                    success: false,
+                    error: `Instance '${keyName}' not found in GGLocator. ` +
+                        `Make sure the class is decorated with @testable or registered during compose().`
+                };
+            }
+
+            // Check if method exists
+            const method = instance[methodName];
+            if (typeof method !== 'function') {
+                return {
+                    success: false,
+                    error: `Method '${methodName}' not found on instance '${keyName}'. ` +
+                        `Available methods: ${getMethodNames(instance).join(', ')}`
+                };
+            }
+
+            // Invoke the method, optionally within the provided context
+            let result: any;
+            if (context) {
+                const ctx = deserializeContext(context);
+                result = await ctx.run(() => method.apply(instance, args));
+            } else {
+                result = await method.apply(instance, args);
+            }
+
+            GGLog.debug(LOG_CONTEXT, `Invocation ${keyName}.${methodName} completed`, {result});
+
+            return {
+                success: true,
+                result
+            };
+        } catch (error: any) {
+            GGLog.error(LOG_CONTEXT, `Error invoking ${keyName}.${methodName}`, error);
+
+            return {
+                success: false,
+                error: error.message || String(error),
+                stack: error.stack
+            };
+        }
+    });
+}
+
+/**
+ * Get method names from an instance for error messages.
+ */
+function getMethodNames(instance: any): string[] {
+    const names: string[] = [];
+    let proto = Object.getPrototypeOf(instance);
+
+    while (proto && proto !== Object.prototype) {
+        const propNames = Object.getOwnPropertyNames(proto)
+            .filter(name => {
+                if (name === 'constructor') return false;
+                try {
+                    return typeof proto[name] === 'function';
+                } catch {
+                    return false;
+                }
+            });
+        names.push(...propNames);
+        proto = Object.getPrototypeOf(proto);
+    }
+
+    return [...new Set(names)].sort();
+}

package/src/index-node.ts

@@ -0,0 +1,64 @@
+/**
+ * @grest-ts/testkit - Component testing library
+ */
+
+// Core test framework
+import path from "path";
+import {fileURLToPath} from "url";
+import {WorkerRunner} from "./runner/WorkerRunner";
+import {IsolatedRunner} from "./runner/IsolatedRunner";
+
+export * from './GGTest'
+export * from './GGTestRunner'
+export * from './IGGLocalDiscoveryServer'
+export * from './GGTestRuntime'
+export * from './testers/GGTestComponent'
+export * from './mockable/GGMockable'
+export * from './mockable/GGMockableCall'
+export * from './mockable/mockable'
+export * from './GGTestContext'
+
+// Mockable component server (import triggers factory registration)
+export * from './mockable/GGMockableInterceptorsServer'
+
+// Testable - direct service invocation from tests
+export * from './callOn/callOn'
+export * from './callOn/GGTestActionForLocatorOnCall'
+export * from './callOn/GGCallOnSelector'
+
+// Contract registration - patches GGContractClass.implement() to auto-register
+import './callOn/GGContractClass.implement'
+
+// Control channel for runtime config updates
+export * from './GGTestRuntimeWorker'
+
+// Test utilities - core infrastructure
+export * from './testers/IGGTestWith'
+export * from './testers/GGTestAction'
+export * from './testers/GGMockWith'
+export * from './testers/GGSpyWith'
+export * from './testers/GGCallInterceptor'
+export * from './utils/GGExpectations'
+export * from './utils/GGTestError'
+export {captureStackSourceFile} from './utils/captureStack'
+export * from './GGTestSharedRef'
+
+// Production bundle DCE verification
+export * from './GGBundleTest'
+
+// Mockable interceptor
+export * from './mockable/GGMockableInterceptor'
+
+// Selector system for runtime access
+export * from './testers/GGTestSelector'
+export * from './testers/RuntimeSelector'
+
+// Worker runner (path configured by @grest-ts/testkit-vitest)
+export * from './runner/WorkerRunner'
+
+export type * from "./testers/IGGTestWith";
+export type * from "./testers/IGGTestInterceptor";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+WorkerRunner.setWorkerLoaderPath(path.join(__dirname, 'runner', 'worker-loader.mjs'));
+IsolatedRunner.setIsolatedLoaderPath(path.join(__dirname, 'runner', 'isolated-loader.mjs'));

package/src/mockable/GGMockable.ts

@@ -0,0 +1,22 @@
+/**
+ * Marker interface for external API services that can be mocked in tests.
+ * When a class implements this interface, the test framework can intercept
+ * all method calls and provide mock responses.
+ *
+ * Examples: REST APIs, GraphQL clients, third-party SDKs
+ */
+export interface GGMockableExternalApi {
+    // Marker interface - no methods required
+}
+
+/**
+ * Marker interface for database/storage services that can be mocked in tests.
+ * When a class implements this interface, the test framework can intercept
+ * all method calls and provide mock responses.
+ *
+ * Examples: Database clients, cache services, file storage
+ */
+export interface GGMockableDatabaseApi {
+    // Marker interface - no methods required
+}
+

package/src/mockable/GGMockableCall.ts

@@ -0,0 +1,45 @@
+import {GG_TEST_RUNTIME_WORKER} from "../GGTestRuntimeWorker";
+import {CALL_THROUGH} from "./GGMockableInterceptorsServer";
+import {GGMockableIPC} from "./GGMockableIPC";
+
+const MOCKABLE_WRAPPED = Symbol('GGMockableWrapped');
+
+export function GGMockableCall(cls: any, methodName: string, nameMapping: string[]): void {
+    // Skip if already wrapped (happens in INLINE mode with multiple runtime instances)
+    if (cls.prototype[methodName]?.[MOCKABLE_WRAPPED]) {
+        return;
+    }
+
+    const originalMethod = cls.prototype[methodName];
+    const wrappedMethod = async function (this: any, ...inputArgs: any[]) {
+        const worker = GG_TEST_RUNTIME_WORKER.get();
+
+        const args: any = {}
+        for (let i = 0; i < inputArgs.length; i++) {
+            if (!nameMapping[i]) break;
+            args[nameMapping[i]] = inputArgs[i];
+        }
+
+        const result = await worker.ipcClient.sendFrameworkRequest(GGMockableIPC.testServer.call, {
+            className: cls.name,
+            methodName: methodName,
+            callArgs: args
+        });
+
+        if (result === CALL_THROUGH) {
+            const realResult = await originalMethod.apply(this, inputArgs);
+            await worker.ipcClient.sendFrameworkRequest(GGMockableIPC.testServer.spyResult, {
+                className: cls.name,
+                methodName: methodName,
+                callResult: realResult
+            });
+            return realResult;
+        } else {
+            return result;
+        }
+    };
+
+    // Mark as wrapped and assign to prototype
+    (wrappedMethod as any)[MOCKABLE_WRAPPED] = true;
+    cls.prototype[methodName] = wrappedMethod;
+}

package/src/mockable/GGMockableIPC.ts

@@ -0,0 +1,20 @@
+import {IPCServer} from "@grest-ts/ipc";
+
+export interface MockableCallPayload {
+    className: string;
+    methodName: string;
+    callArgs: any;
+}
+
+export interface MockableSpyResultPayload {
+    className: string;
+    methodName: string;
+    callResult: any;
+}
+
+export const GGMockableIPC = {
+    testServer: {
+        call: IPCServer.defineRequest<MockableCallPayload, any>("mockable/call"),
+        spyResult: IPCServer.defineRequest<MockableSpyResultPayload, any>("mockable/spy-result"),
+    }
+}

package/src/mockable/GGMockableInterceptor.ts

@@ -0,0 +1,44 @@
+import type {GGTestRunner} from "../GGTestRunner";
+import {GGCallInterceptor, GGCallInterceptorConfig} from "../testers/GGCallInterceptor";
+import {GGMockableInterceptorsServer} from "./GGMockableInterceptorsServer";
+
+export interface MockableInterceptorConfig extends GGCallInterceptorConfig {
+    className: string;
+    methodName: string;
+}
+
+/**
+ * Interceptor for mocking/spying on mockable class methods.
+ * Registers with GGMockableInterceptorsServer which handles the IPC communication.
+ *
+ * For spy mode, the flow is two-phase:
+ * 1. mockable/call → onRequest() validates input, returns undefined (CALL_THROUGH)
+ * 2. mockable/spy-result → onResponse() validates output
+ */
+export class GGMockableInterceptor extends GGCallInterceptor {
+
+    public readonly className: string;
+    public readonly methodName: string;
+
+    constructor(test: GGTestRunner, config: MockableInterceptorConfig) {
+        super(test, config);
+        this.className = config.className;
+        this.methodName = config.methodName;
+    }
+
+    public getKey(): string {
+        return `${this.className}.${this.methodName}`;
+    }
+
+    protected doRegister(): void {
+        this.test.getExtensionInstance(GGMockableInterceptorsServer).addInterceptor(this);
+    }
+
+    protected doUnregister(): void {
+        this.test.getExtensionInstance(GGMockableInterceptorsServer).deleteInterceptor(this);
+    }
+
+    protected parseResponseData(result: any): any {
+        return result;
+    }
+}

package/src/mockable/GGMockableInterceptorsServer.ts

@@ -0,0 +1,69 @@
+import type {GGMockableInterceptor} from "./GGMockableInterceptor";
+import {GGTestComponent} from "../testers/GGTestComponent";
+import {GGTestRunner} from "../GGTestRunner";
+import {GGMockableIPC} from "./GGMockableIPC";
+
+export const CALL_THROUGH = "__spyCallThrough|migo0am5g0htea";
+
+export class GGMockableInterceptorsServer implements GGTestComponent {
+
+    private readonly interceptors: Map<string, GGMockableInterceptor> = new Map();
+
+    constructor(runner: GGTestRunner) {
+        const server = runner.ipcServer;
+        server.onFrameworkMessage(GGMockableIPC.testServer.call, async (body) => {
+            const key = body.className + "." + body.methodName;
+            const handler = this.interceptors.get(key);
+
+            if (!handler) {
+                // No mock configured - call through to real implementation
+                // This allows testable() to invoke real methods on @mockable services
+                // throw new Error(
+                //     `Expected handler to be set for mockable '${key}'!\n` +
+                //     "Did you forget to call .with(...)?"
+                // );
+                return CALL_THROUGH;
+            }
+
+            // onRequest validates input and returns mock data (or undefined for spy)
+            const result = await handler.onRequest(body.callArgs);
+
+            if (handler.passThrough) {
+                // Spy mode - signal worker to call through
+                return CALL_THROUGH;
+            } else {
+                // Mock mode - return the mock data
+                return result;
+            }
+        });
+
+        server.onFrameworkMessage(GGMockableIPC.testServer.spyResult, async (body) => {
+            const key = body.className + "." + body.methodName;
+            const handler = this.interceptors.get(key);
+
+            if (!handler || !handler.passThrough) {
+                // No spy handler configured - just ignore the result
+                // This allows testable() to call through without requiring spyOn()
+                // throw new Error(`Expected spy handler for '${key}'`);
+                return;
+            }
+
+            // Validate the response from the real implementation
+            await handler.onResponse(body.callResult);
+        });
+    }
+
+    public addInterceptor(interceptor: GGMockableInterceptor) {
+        this.interceptors.set(interceptor.getKey(), interceptor);
+    }
+
+    public deleteInterceptor(interceptor: GGMockableInterceptor) {
+        this.interceptors.delete(interceptor.getKey());
+    }
+
+    public async teardown(): Promise<void> {
+        this.interceptors.clear();
+    }
+}
+
+GGTestRunner.registerExtension(GGMockableInterceptorsServer);

package/src/mockable/mockable.ts

@@ -0,0 +1,71 @@
+/**
+ * Mockable decorator and test helpers.
+ *
+ * The @mockable decorator is re-exported from mockable-runtime.ts for production use.
+ * mockBy() and spyOn() are test-only utilities that require the full testkit.
+ */
+
+// Test-only imports - these pull in testkit infrastructure
+import {GGMockableInterceptor} from "./GGMockableInterceptor";
+import {GGMockWith} from "../testers/GGMockWith";
+import {GGSpyWith} from "../testers/GGSpyWith";
+
+// ============================================================================
+// Type helpers for mockBy/spyOn
+// ============================================================================
+
+/**
+ * Type for mock access - maps class methods to GGMockWith
+ */
+type MockAccess<T> = {
+    [K in keyof T]: T[K] extends (...args: infer A) => Promise<infer R>
+        ? GGMockWith<A extends [infer Single] ? (Single extends object ? Single : Record<string, Single>) : Record<string, any>, Awaited<R>, never>
+        : never
+};
+
+/**
+ * Type for spy access - maps class methods to GGSpyWith
+ */
+type SpyAccess<T> = {
+    [K in keyof T]: T[K] extends (...args: infer A) => Promise<infer R>
+        ? GGSpyWith<A extends [infer Single] ? (Single extends object ? Single : Record<string, Single>) : Record<string, any>, Awaited<R>, never>
+        : never
+};
+
+/**
+ * Get mock access for a @mockable class.
+ * Use this to create mock expectations in tests.
+ *
+ * @example
+ * ```typescript
+ * .with(mockOf(AddressResolverService).resolveAddress
+ *     .toEqual({address: "123 Main St"})
+ *     .andReturn({lat: 40.7, lng: -74.0}))
+ * ```
+ */
+export function mockOf<T>(cls: new (...args: any[]) => T): MockAccess<T> {
+    return new Proxy({} as any, {
+        get(_, methodName: string) {
+            return new GGMockWith(GGMockableInterceptor, {className: cls.name, methodName})
+        }
+    });
+}
+
+/**
+ * Get spy access for a @mockable class.
+ * Use this to create spy expectations in tests - the real method will be called.
+ *
+ * @example
+ * ```typescript
+ * .with(spyOn(AddressResolverService).resolveAddress
+ *     .toEqual({address: "123 Main St"})
+ *     .responseToMatchObject({lat: 40.7}))
+ * ```
+ */
+export function spyOn<T>(cls: new (...args: any[]) => T): SpyAccess<T> {
+    return new Proxy({} as any, {
+        get(_, methodName: string) {
+            return new GGSpyWith(GGMockableInterceptor, {className: cls.name, methodName})
+        }
+    });
+}