@asenajs/asena 0.7.0 → 0.8.0

package/dist/lib/test/factory/deepMock.js

@@ -0,0 +1,105 @@
+import { mock } from 'bun:test';
+/**
+ * Keys that must NOT resolve to a mock function on a deep mock node.
+ *
+ * `then`/`catch`/`finally`: if property access returned a function, the node
+ * would be treated as a thenable and `await deepMock` would never resolve.
+ * `toJSON`: keeps JSON.stringify from invoking an auto-generated mock.
+ */
+const IGNORED_KEYS = new Set(['then', 'catch', 'finally', 'toJSON']);
+/**
+ * Creates a leaf mock: a REAL Bun mock function (no Proxy wrapper)
+ *
+ * Leaves must stay raw because Bun's expect() matchers and mock configuration
+ * methods (mockReturnValue, mockResolvedValue...) brand-check their target -
+ * a Proxy-wrapped mock fails "Expected value must be a mock function". The
+ * default implementation returns a memoized deep node so call chains continue.
+ *
+ * @param path - Access path of this mock, used as the function name for debugging
+ * @returns Bun mock function
+ *
+ * @internal
+ */
+function createDeepMockLeaf(path) {
+    let callResult;
+    const leaf = mock(() => {
+        callResult ??= createDeepMockNode(`${path}()`);
+        return callResult;
+    });
+    Object.defineProperty(leaf, 'name', { value: path, configurable: true });
+    return leaf;
+}
+/**
+ * Creates a deep mock node
+ *
+ * A node is a Proxy whose target is a Bun mock function: the node is callable
+ * (returning a memoized child node) and any unknown property resolves to a
+ * memoized raw leaf mock.
+ *
+ * @param path - Access path of this node, used as the function name for debugging
+ * @returns Proxy-wrapped mock function
+ *
+ * @internal
+ */
+function createDeepMockNode(path) {
+    let callResult;
+    const fn = mock(() => {
+        callResult ??= createDeepMockNode(`${path}()`);
+        return callResult;
+    });
+    Object.defineProperty(fn, 'name', { value: path, configurable: true });
+    const children = new Map();
+    return new Proxy(fn, {
+        get(target, key) {
+            // Pass through everything that exists on the mock function itself
+            // (mock state, Function.prototype members). Methods are bound to the
+            // raw target so native brand checks keep working through the Proxy.
+            if (Reflect.has(target, key)) {
+                const value = Reflect.get(target, key, target);
+                return typeof value === 'function' ? value.bind(target) : value;
+            }
+            if (IGNORED_KEYS.has(key)) {
+                return undefined;
+            }
+            // Well-known symbols (Symbol.iterator, Symbol.toPrimitive, inspect
+            // symbols...) fall back to engine defaults instead of becoming mocks
+            if (typeof key === 'symbol') {
+                return undefined;
+            }
+            // Memoized per key so repeated access returns the SAME mock function
+            // and call counts accumulate across accesses
+            if (!children.has(key)) {
+                children.set(key, createDeepMockLeaf(`${path}.${String(key)}`));
+            }
+            return children.get(key);
+        },
+    });
+}
+/**
+ * Creates a deep mock object backed by native Proxy
+ *
+ * Any property access returns a memoized Bun mock function, and calling one
+ * returns another deep mock node - so arbitrary call chains work without any
+ * upfront shape definition. Used by mockComponent to evaluate @Inject expression
+ * transformations (e.g. the ulak() helper) without a running application.
+ *
+ * @returns Deep mock root node
+ *
+ * @example
+ * ```typescript
+ * const deepMock = createDeepMock();
+ *
+ * // Any chain works out of the box
+ * const channel = deepMock.namespace('/chat');
+ * await channel.broadcast({ text: 'hello' });
+ *
+ * expect(channel.broadcast).toHaveBeenCalledWith({ text: 'hello' });
+ *
+ * // Mocks are configurable like any Bun mock
+ * channel.getSocketCount.mockReturnValue(5);
+ * ```
+ */
+export function createDeepMock() {
+    return createDeepMockNode('deepMock');
+}
+//# sourceMappingURL=deepMock.js.map

package/dist/lib/test/factory/deepMock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepMock.js","sourceRoot":"","sources":["../../../../lib/test/factory/deepMock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAEhC;;;;;;GAMG;AACH,MAAM,YAAY,GAAG,IAAI,GAAG,CAAc,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;AAElF;;;;;;;;;;;;GAYG;AACH,SAAS,kBAAkB,CAAC,IAAY;IACtC,IAAI,UAAe,CAAC;IAEpB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE;QACrB,UAAU,KAAK,kBAAkB,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC;QAE/C,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;IAEzE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,kBAAkB,CAAC,IAAY;IACtC,IAAI,UAAe,CAAC;IAEpB,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE;QACnB,UAAU,KAAK,kBAAkB,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC;QAE/C,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;IAEvE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAC;IAE7C,OAAO,IAAI,KAAK,CAAC,EAAE,EAAE;QACnB,GAAG,CAAC,MAAM,EAAE,GAAG;YACb,kEAAkE;YAClE,qEAAqE;YACrE,oEAAoE;YACpE,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;gBAC7B,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;gBAE/C,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;YAClE,CAAC;YAED,IAAI,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC1B,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,mEAAmE;YACnE,qEAAqE;YACrE,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAC5B,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,qEAAqE;YACrE,6CAA6C;YAC7C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBACvB,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,kBAAkB,CAAC,GAAG,IAAI,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;YAClE,CAAC;YAED,OAAO,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,kBAAkB,CAAC,UAAU,CAAC,CAAC;AACxC,CAAC"}

package/dist/lib/test/factory/ulakStub.d.ts

@@ -0,0 +1,44 @@
+import type { Mock } from 'bun:test';
+import type { Ulak } from '../../server/messaging';
+/**
+ * A Ulak.NameSpace stub whose methods are all Bun mock functions
+ *
+ * Extends Ulak.NameSpace so any method added to the interface in the future
+ * breaks this file's compilation instead of silently drifting out of sync.
+ */
+export interface TestUlakNameSpace<T extends string = string> extends Ulak.NameSpace<T> {
+    broadcast: Mock<(data: any) => Promise<void>>;
+    to: Mock<(room: string, data: any) => Promise<void>>;
+    toSocket: Mock<(socketId: string, data: any) => Promise<void>>;
+    toMany: Mock<(rooms: string[], data: any) => Promise<void>>;
+    getSocketCount: Mock<() => number>;
+}
+/**
+ * Creates a typed Ulak namespace stub for tests
+ *
+ * Use it as an explicit override for @Inject(ulak(...)) fields when you want
+ * a fully typed mock instead of the automatic deep mock generated by
+ * mockComponent.
+ *
+ * @param path - The namespace path the stub reports (defaults to '/')
+ * @returns Ulak.NameSpace implementation with all methods mocked
+ *
+ * @example
+ * ```typescript
+ * import { mockComponent, createTestUlakStub } from '@asenajs/asena/test';
+ *
+ * const statsChannel = createTestUlakStub('/ws/public/stats');
+ *
+ * const { instance } = mockComponent(UserService, {
+ *   overrides: { statsChannel },
+ * });
+ *
+ * await instance.createAnonUser('John');
+ *
+ * expect(statsChannel.broadcast).toHaveBeenCalledWith({
+ *   action: 'update',
+ *   data: { newUser: 1 },
+ * });
+ * ```
+ */
+export declare function createTestUlakStub<T extends string = string>(path?: T): TestUlakNameSpace<T>;

package/dist/lib/test/factory/ulakStub.js

@@ -0,0 +1,40 @@
+import { mock } from 'bun:test';
+/**
+ * Creates a typed Ulak namespace stub for tests
+ *
+ * Use it as an explicit override for @Inject(ulak(...)) fields when you want
+ * a fully typed mock instead of the automatic deep mock generated by
+ * mockComponent.
+ *
+ * @param path - The namespace path the stub reports (defaults to '/')
+ * @returns Ulak.NameSpace implementation with all methods mocked
+ *
+ * @example
+ * ```typescript
+ * import { mockComponent, createTestUlakStub } from '@asenajs/asena/test';
+ *
+ * const statsChannel = createTestUlakStub('/ws/public/stats');
+ *
+ * const { instance } = mockComponent(UserService, {
+ *   overrides: { statsChannel },
+ * });
+ *
+ * await instance.createAnonUser('John');
+ *
+ * expect(statsChannel.broadcast).toHaveBeenCalledWith({
+ *   action: 'update',
+ *   data: { newUser: 1 },
+ * });
+ * ```
+ */
+export function createTestUlakStub(path = '/') {
+    return {
+        path,
+        broadcast: mock(async () => undefined),
+        to: mock(async () => undefined),
+        toSocket: mock(async () => undefined),
+        toMany: mock(async () => undefined),
+        getSocketCount: mock(() => 0),
+    };
+}
+//# sourceMappingURL=ulakStub.js.map

package/dist/lib/test/factory/ulakStub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ulakStub.js","sourceRoot":"","sources":["../../../../lib/test/factory/ulakStub.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAkBhC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,kBAAkB,CAA4B,OAAU,GAAQ;IAC9E,OAAO;QACL,IAAI;QACJ,SAAS,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,SAAS,CAAC;QACtC,EAAE,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,SAAS,CAAC;QAC/B,QAAQ,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,SAAS,CAAC;QACrC,MAAM,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,SAAS,CAAC;QACnC,cAAc,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;KAC9B,CAAC;AACJ,CAAC"}

package/dist/lib/test/harness/createTestApp.d.ts

@@ -0,0 +1,33 @@
+import type { AsenaAdapter } from '../../adapter';
+import type { TestApp, TestAppOptions } from './types';
+/**
+ * Boots a full Asena application for testing - the equivalent of Spring's `@SpringBootTest`.
+ *
+ * Everything runs for real: the IoC container, all bootstrap phases, the adapter and its
+ * routing pipeline. Only the components you name are registered, and any of them can be
+ * swapped for a double through `overrides`.
+ *
+ * @param options - Adapter, components and optional overrides
+ * @returns A started app with a fluent HTTP client attached
+ *
+ * @example
+ * ```typescript
+ * const [adapter] = createHonoAdapter({ logger: silentLogger });
+ * const app = await createTestApp({
+ *   adapter,
+ *   components: [UserController, UserService],
+ *   overrides: { UserService: { findById: mock(async () => ({ id: '1', name: 'Ada' })) } },
+ * });
+ *
+ * await app.get('/users/1').expectStatus(200).expectJson({ id: '1', name: 'Ada' });
+ *
+ * await app.stop();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Automatic cleanup, and no TCP port taken at all
+ * await using app = await createTestApp({ adapter, components, dispatch: 'socket' });
+ * ```
+ */
+export declare function createTestApp<A extends AsenaAdapter<any, any> = AsenaAdapter<any, any>>(options: TestAppOptions<A>): Promise<TestApp>;

package/dist/lib/test/harness/createTestApp.js

@@ -0,0 +1,105 @@
+import { unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { AsenaServerFactory } from '../../server/AsenaServerFactory';
+import { TestHttpCall } from '../http/TestHttpCall';
+import { silentLogger } from './silentLogger';
+// Monotonic, not random: workflow scripts and test runners may run many apps per process
+// and a collision would surface as a confusing EADDRINUSE on a socket file
+let socketCounter = 0;
+function nextSocketPath() {
+    socketCounter += 1;
+    return join(tmpdir(), `asena-test-${process.pid}-${socketCounter}.sock`);
+}
+/**
+ * Boots a full Asena application for testing - the equivalent of Spring's `@SpringBootTest`.
+ *
+ * Everything runs for real: the IoC container, all bootstrap phases, the adapter and its
+ * routing pipeline. Only the components you name are registered, and any of them can be
+ * swapped for a double through `overrides`.
+ *
+ * @param options - Adapter, components and optional overrides
+ * @returns A started app with a fluent HTTP client attached
+ *
+ * @example
+ * ```typescript
+ * const [adapter] = createHonoAdapter({ logger: silentLogger });
+ * const app = await createTestApp({
+ *   adapter,
+ *   components: [UserController, UserService],
+ *   overrides: { UserService: { findById: mock(async () => ({ id: '1', name: 'Ada' })) } },
+ * });
+ *
+ * await app.get('/users/1').expectStatus(200).expectJson({ id: '1', name: 'Ada' });
+ *
+ * await app.stop();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Automatic cleanup, and no TCP port taken at all
+ * await using app = await createTestApp({ adapter, components, dispatch: 'socket' });
+ * ```
+ */
+export async function createTestApp(options) {
+    const { adapter, components, overrides, logger = silentLogger, dispatch = 'server' } = options;
+    const socketPath = dispatch === 'socket' ? nextSocketPath() : undefined;
+    const server = await AsenaServerFactory.create({
+        adapter,
+        logger,
+        components,
+        overrides,
+        // Port 0 lets Bun assign a free ephemeral port, which removes the random-port race
+        port: options.port ?? 0,
+    });
+    await server.start(socketPath ? { unix: socketPath } : undefined);
+    const port = server.httpServer?.port ?? 0;
+    const baseUrl = socketPath ? 'http://localhost' : `http://localhost:${port}`;
+    const call = (path, init, method) => {
+        const requestInit = { ...init };
+        if (method) {
+            requestInit.method = method;
+        }
+        if (socketPath) {
+            // Bun routes the request over the socket while still parsing the URL for path/query
+            requestInit.unix = socketPath;
+        }
+        return new TestHttpCall(`${baseUrl}${path}`, requestInit);
+    };
+    let stopped = false;
+    const app = {
+        server,
+        container: server.coreContainer.container,
+        port,
+        baseUrl,
+        socketPath,
+        resolve: async (name) => (await server.coreContainer.container.resolve(name)),
+        wsUrl: (path) => (socketPath ? `ws+unix://${socketPath}:${path}` : `ws://localhost:${port}${path}`),
+        request: (path, init) => call(path, init),
+        get: (path, init) => call(path, init, 'GET'),
+        post: (path, init) => call(path, init, 'POST'),
+        put: (path, init) => call(path, init, 'PUT'),
+        patch: (path, init) => call(path, init, 'PATCH'),
+        delete: (path, init) => call(path, init, 'DELETE'),
+        head: (path, init) => call(path, init, 'HEAD'),
+        options: (path, init) => call(path, init, 'OPTIONS'),
+        stop: async () => {
+            if (stopped) {
+                return;
+            }
+            stopped = true;
+            await server.stop();
+            if (socketPath) {
+                // Bun removes the socket file on a clean stop; this only matters after a crash
+                await unlink(socketPath).catch(() => {
+                    // Already gone - nothing to clean up
+                });
+            }
+        },
+        [Symbol.asyncDispose]: async () => {
+            await app.stop();
+        },
+    };
+    return app;
+}
+//# sourceMappingURL=createTestApp.js.map

package/dist/lib/test/harness/createTestApp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTestApp.js","sourceRoot":"","sources":["../../../../lib/test/harness/createTestApp.ts"],"names":[],"mappings":"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"}

package/dist/lib/test/harness/createWebTest.d.ts

@@ -0,0 +1,28 @@
+import type { AsenaAdapter } from '../../adapter';
+import type { WebTestOptions, WebTestResult } from './types';
+/**
+ * Boots only the web layer of an application - the equivalent of Spring's `@WebMvcTest`.
+ *
+ * The controllers, their middlewares and their validators run for real. Every other
+ * dependency they inject is replaced by an auto-generated mock shaped like the real class,
+ * so a controller test never drags in a database or an HTTP client.
+ *
+ * Core services (the container, the logger, `ulak(...)`, the event emitter, ...) are always
+ * real - they are wired during bootstrap, before user components exist.
+ *
+ * @param options - Adapter, controllers and optional explicit overrides
+ * @returns The started app plus every double in play, keyed by service name
+ *
+ * @example
+ * ```typescript
+ * const { app, mocks } = await createWebTest({ adapter, controllers: [UserController] });
+ *
+ * mocks.UserService.findById.mockResolvedValue({ id: '1', name: 'Ada' });
+ *
+ * await app.get('/users/1').expectStatus(200).expectJson({ id: '1', name: 'Ada' });
+ * expect(mocks.UserService.findById).toHaveBeenCalledWith('1');
+ *
+ * await app.stop();
+ * ```
+ */
+export declare function createWebTest<A extends AsenaAdapter<any, any> = AsenaAdapter<any, any>>(options: WebTestOptions<A>): Promise<WebTestResult>;

package/dist/lib/test/harness/createWebTest.js

@@ -0,0 +1,127 @@
+import { ComponentConstants, ComponentType, ICoreServiceNames } from '../../ioc';
+import { getOwnTypedMetadata, getTypedMetadata } from '../../utils';
+import { createMockFromClass } from '../factory/mockFactory';
+import { discoverInjectedFieldsFromClass } from '../metadata/discovery';
+import { createTestApp } from './createTestApp';
+import { silentLogger } from './silentLogger';
+/**
+ * The registered container name for a component
+ *
+ * @internal
+ */
+function componentName(Class) {
+    return getTypedMetadata(ComponentConstants.NameKey, Class) || Class.name;
+}
+/**
+ * Collects the classes the web layer cannot function without.
+ *
+ * Middlewares, validators and static-serve configs are resolved **by name from the
+ * container** at start-up (PrepareMiddlewareService / PrepareValidatorService) and throw
+ * when missing, so a slice test has to register them for real rather than mock them.
+ *
+ * @internal
+ */
+function collectWebLayer(controllers) {
+    const webLayer = new Set(controllers);
+    for (const controller of controllers) {
+        for (const middleware of getTypedMetadata(ComponentConstants.MiddlewaresKey, controller) || []) {
+            webLayer.add(middleware);
+        }
+        const routes = getOwnTypedMetadata(ComponentConstants.RouteKey, controller) || {};
+        for (const params of Object.values(routes)) {
+            for (const middleware of params.middlewares || []) {
+                webLayer.add(middleware);
+            }
+            if (params.validator) {
+                webLayer.add(params.validator);
+            }
+            if (params.staticServe) {
+                webLayer.add(params.staticServe);
+            }
+        }
+    }
+    return webLayer;
+}
+/**
+ * Boots only the web layer of an application - the equivalent of Spring's `@WebMvcTest`.
+ *
+ * The controllers, their middlewares and their validators run for real. Every other
+ * dependency they inject is replaced by an auto-generated mock shaped like the real class,
+ * so a controller test never drags in a database or an HTTP client.
+ *
+ * Core services (the container, the logger, `ulak(...)`, the event emitter, ...) are always
+ * real - they are wired during bootstrap, before user components exist.
+ *
+ * @param options - Adapter, controllers and optional explicit overrides
+ * @returns The started app plus every double in play, keyed by service name
+ *
+ * @example
+ * ```typescript
+ * const { app, mocks } = await createWebTest({ adapter, controllers: [UserController] });
+ *
+ * mocks.UserService.findById.mockResolvedValue({ id: '1', name: 'Ada' });
+ *
+ * await app.get('/users/1').expectStatus(200).expectJson({ id: '1', name: 'Ada' });
+ * expect(mocks.UserService.findById).toHaveBeenCalledWith('1');
+ *
+ * await app.stop();
+ * ```
+ */
+export async function createWebTest(options) {
+    const { adapter, controllers, components = [], overrides = {}, logger = silentLogger, port, dispatch } = options;
+    const controllerList = Array.isArray(controllers) ? controllers : [controllers];
+    if (!controllerList.length) {
+        throw new Error('createWebTest requires at least one @Controller class.');
+    }
+    for (const controller of controllerList) {
+        if (typeof controller !== 'function' || !getTypedMetadata(ComponentType.CONTROLLER, controller)) {
+            throw new Error(`createWebTest expects @Controller classes, but received '${controller?.name ?? typeof controller}'. ` +
+                'Pass services and middlewares through `components` instead.');
+        }
+    }
+    const realComponents = collectWebLayer(controllerList);
+    for (const component of components) {
+        realComponents.add(component);
+    }
+    const realNames = new Set();
+    for (const component of realComponents) {
+        realNames.add(componentName(component));
+    }
+    const coreServiceNames = new Set(Object.values(ICoreServiceNames));
+    const autoMocks = {};
+    for (const component of realComponents) {
+        for (const field of discoverInjectedFieldsFromClass(component)) {
+            const { serviceName, serviceClass, fieldName } = field;
+            // Core services are wired during bootstrap and are always real - mocking them would
+            // also trip the factory's core-key guard. ulak(...) lands here.
+            if (coreServiceNames.has(serviceName)) {
+                continue;
+            }
+            // Already satisfied - either registered for real or replaced by the caller
+            if (realNames.has(serviceName) || Object.hasOwn(overrides, serviceName)) {
+                continue;
+            }
+            // One shared mock per service, so two controllers injecting it see the same double
+            if (Object.hasOwn(autoMocks, serviceName)) {
+                continue;
+            }
+            if (!serviceClass) {
+                logger.warn(`createWebTest: '${serviceName}' (field '${fieldName}' on ${component.name}) was injected by name, ` +
+                    'so its method shape is unknown and the mock will be an empty object. ' +
+                    'Pass an explicit override if the test needs its methods.');
+            }
+            autoMocks[serviceName] = createMockFromClass(serviceClass);
+        }
+    }
+    const app = await createTestApp({
+        adapter,
+        logger,
+        port,
+        dispatch,
+        components: [...realComponents],
+        // Explicit overrides win over the generated ones
+        overrides: { ...autoMocks, ...overrides },
+    });
+    return { app, mocks: { ...autoMocks, ...overrides } };
+}
+//# sourceMappingURL=createWebTest.js.map

package/dist/lib/test/harness/createWebTest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createWebTest.js","sourceRoot":"","sources":["../../../../lib/test/harness/createWebTest.ts"],"names":[],"mappings":"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"}

package/dist/lib/test/harness/silentLogger.d.ts

@@ -0,0 +1,27 @@
+import type { ServerLogger } from '../../logger';
+export declare const silentLogger: ServerLogger;
+/**
+ * A single captured log line.
+ */
+export interface CapturedLogEntry {
+    level: 'info' | 'warn' | 'error' | 'profile';
+    message: string;
+    meta?: any;
+}
+/**
+ * Creates a silent logger that also records every call, so tests can assert on warnings.
+ *
+ * @returns The logger plus the array it appends to (live, not a copy)
+ *
+ * @example
+ * ```typescript
+ * const { logger, entries } = createCapturingLogger();
+ * const { app } = await createWebTest({ adapter, controllers: [UserController], logger });
+ *
+ * expect(entries.some((e) => e.level === 'warn' && e.message.includes('cannot be auto-mocked'))).toBe(true);
+ * ```
+ */
+export declare function createCapturingLogger(): {
+    logger: ServerLogger;
+    entries: CapturedLogEntry[];
+};

package/dist/lib/test/harness/silentLogger.js

@@ -0,0 +1,54 @@
+/**
+ * A ServerLogger that discards everything.
+ *
+ * The default logger for test apps: booting a server prints the banner, the adapter name,
+ * a route table and a "server running" line, none of which belong in test output.
+ *
+ * @example
+ * ```typescript
+ * const [adapter] = createHonoAdapter({ logger: silentLogger });
+ * ```
+ */
+const noop = () => {
+    // Intentionally empty - the whole point is to keep test output clean
+};
+export const silentLogger = {
+    info: noop,
+    warn: noop,
+    error: noop,
+    profile: noop,
+};
+/**
+ * Creates a silent logger that also records every call, so tests can assert on warnings.
+ *
+ * @returns The logger plus the array it appends to (live, not a copy)
+ *
+ * @example
+ * ```typescript
+ * const { logger, entries } = createCapturingLogger();
+ * const { app } = await createWebTest({ adapter, controllers: [UserController], logger });
+ *
+ * expect(entries.some((e) => e.level === 'warn' && e.message.includes('cannot be auto-mocked'))).toBe(true);
+ * ```
+ */
+export function createCapturingLogger() {
+    const entries = [];
+    return {
+        entries,
+        logger: {
+            info: (message, meta) => {
+                entries.push({ level: 'info', message, meta });
+            },
+            warn: (message, meta) => {
+                entries.push({ level: 'warn', message, meta });
+            },
+            error: (message, meta) => {
+                entries.push({ level: 'error', message, meta });
+            },
+            profile: (message) => {
+                entries.push({ level: 'profile', message });
+            },
+        },
+    };
+}
+//# sourceMappingURL=silentLogger.js.map

package/dist/lib/test/harness/silentLogger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"silentLogger.js","sourceRoot":"","sources":["../../../../lib/test/harness/silentLogger.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,IAAI,GAAG,GAAS,EAAE;IACtB,qEAAqE;AACvE,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAiB;IACxC,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,IAAI;IACV,KAAK,EAAE,IAAI;IACX,OAAO,EAAE,IAAI;CACd,CAAC;AAWF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,OAAO,GAAuB,EAAE,CAAC;IAEvC,OAAO;QACL,OAAO;QACP,MAAM,EAAE;YACN,IAAI,EAAE,CAAC,OAAe,EAAE,IAAU,EAAE,EAAE;gBACpC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACjD,CAAC;YACD,IAAI,EAAE,CAAC,OAAe,EAAE,IAAU,EAAE,EAAE;gBACpC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACjD,CAAC;YACD,KAAK,EAAE,CAAC,OAAe,EAAE,IAAU,EAAE,EAAE;gBACrC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YAClD,CAAC;YACD,OAAO,EAAE,CAAC,OAAe,EAAE,EAAE;gBAC3B,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC;YAC9C,CAAC;SACF;KACF,CAAC;AACJ,CAAC"}