@asenajs/asena 0.7.1 → 0.8.1

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"}

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

@@ -0,0 +1,147 @@
+import type { AsenaAdapter } from '../../adapter';
+import type { Container } from '../../ioc';
+import type { ServerLogger } from '../../logger';
+import type { AsenaServer } from '../../server/AsenaServer';
+import type { Class } from '../../server/types';
+import type { TestHttpCall } from '../http/TestHttpCall';
+/**
+ * How the test app accepts requests.
+ *
+ * - `server` - listens on a TCP port (default). Matches production exactly.
+ * - `socket` - listens on a unix domain socket instead. Still the adapter's real routing
+ *   pipeline, but occupies no port, so parallel suites cannot collide. Requires an adapter
+ *   that honours `AsenaStartOptions.unix`.
+ */
+export type DispatchMode = 'server' | 'socket';
+/**
+ * Options for {@link createTestApp}
+ */
+export interface TestAppOptions<A extends AsenaAdapter<any, any> = AsenaAdapter<any, any>> {
+    /**
+     * The adapter instance to boot, e.g. `createHonoAdapter({ logger: silentLogger })[0]`
+     */
+    adapter: A;
+    /**
+     * Components to register. Passing this list skips filesystem scanning entirely.
+     */
+    components: Class[];
+    /**
+     * Replace registered components with test doubles, keyed by service name (`@MockBean`).
+     *
+     * Override services, not controllers: a plain object mock carries no `@Controller`
+     * metadata, so an overridden controller's routes would never be registered.
+     */
+    overrides?: Record<string, object>;
+    /**
+     * Logger for the booted server
+     *
+     * @default silentLogger
+     */
+    logger?: ServerLogger;
+    /**
+     * Port to bind. Ignored in `socket` dispatch.
+     *
+     * @default 0 - Bun picks a free ephemeral port, which removes the port race entirely
+     */
+    port?: number;
+    /**
+     * @default 'server'
+     */
+    dispatch?: DispatchMode;
+}
+/**
+ * A booted test application
+ */
+export interface TestApp {
+    /**
+     * The running server
+     */
+    readonly server: AsenaServer<any>;
+    /**
+     * The user component container
+     */
+    readonly container: Container;
+    /**
+     * The bound TCP port. `0` in `socket` dispatch, where no port is used.
+     */
+    readonly port: number;
+    /**
+     * Base URL for HTTP calls. In `socket` dispatch the host is a placeholder - routing
+     * happens over {@link socketPath}.
+     */
+    readonly baseUrl: string;
+    /**
+     * Path of the unix socket, when running in `socket` dispatch
+     */
+    readonly socketPath?: string;
+    /**
+     * Resolves a component from the container
+     *
+     * @param name - Registered service name
+     */
+    resolve<T>(name: string): Promise<T>;
+    /**
+     * Builds a WebSocket URL for the given path, correct for the active dispatch mode
+     *
+     * @param path - Route path, e.g. `/ws/chat`
+     */
+    wsUrl(path: string): string;
+    /**
+     * Starts a request with an explicit method in `init`
+     *
+     * @param path - Path relative to the app root
+     * @param init - Standard fetch init
+     */
+    request(path: string, init?: RequestInit): TestHttpCall;
+    get(path: string, init?: RequestInit): TestHttpCall;
+    post(path: string, init?: RequestInit): TestHttpCall;
+    put(path: string, init?: RequestInit): TestHttpCall;
+    patch(path: string, init?: RequestInit): TestHttpCall;
+    delete(path: string, init?: RequestInit): TestHttpCall;
+    head(path: string, init?: RequestInit): TestHttpCall;
+    options(path: string, init?: RequestInit): TestHttpCall;
+    /**
+     * Stops the server and removes the unix socket if one was created. Idempotent.
+     */
+    stop(): Promise<void>;
+    /**
+     * Enables `await using app = await createTestApp(...)`
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Options for {@link createWebTest}
+ */
+export interface WebTestOptions<A extends AsenaAdapter<any, any> = AsenaAdapter<any, any>> {
+    adapter: A;
+    /**
+     * Controller(s) under test
+     */
+    controllers: Class | Class[];
+    /**
+     * Extra components to register for real, alongside the controllers' middlewares and
+     * validators (which are always real, since the framework resolves them by name)
+     */
+    components?: Class[];
+    /**
+     * Explicit doubles, keyed by service name. These win over the generated auto-mocks.
+     */
+    overrides?: Record<string, object>;
+    logger?: ServerLogger;
+    port?: number;
+    dispatch?: DispatchMode;
+}
+/**
+ * Result of {@link createWebTest}
+ */
+export interface WebTestResult {
+    app: TestApp;
+    /**
+     * Every double in play - both auto-generated mocks and the explicit `overrides` - keyed
+     * by **service name** (not field name, unlike `mockComponent`).
+     *
+     * One shared mock per service, so two controllers injecting the same service see the
+     * same double.
+     */
+    mocks: Record<string, any>;
+}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../lib/test/harness/types.ts"],"names":[],"mappings":""}

package/dist/lib/test/http/TestHttpCall.d.ts

@@ -0,0 +1,78 @@
+import { TestHttpResponse } from './TestHttpResponse';
+/**
+ * A pending HTTP call with a fluent assertion chain.
+ *
+ * Nothing is sent until the call is awaited. Assertions queue up in the order they were
+ * chained and run against the buffered response; the send is memoized, so awaiting the
+ * same call twice does not issue a second request.
+ *
+ * @example
+ * ```typescript
+ * await app.get('/users/1').expectStatus(200).expectJson({ id: '1', name: 'Ada' });
+ *
+ * const res = await app.post('/users', { body: JSON.stringify({ name: 'Ada' }) }).expectStatus(201);
+ * expect(res.json().id).toBeString();
+ * ```
+ */
+export declare class TestHttpCall implements PromiseLike<TestHttpResponse> {
+    private readonly assertions;
+    private pending?;
+    private readonly url;
+    private readonly init?;
+    constructor(url: string, init?: RequestInit);
+    /**
+     * Asserts the response status code
+     *
+     * @param expected - Expected status
+     * @returns this, for chaining
+     */
+    expectStatus(expected: number): this;
+    /**
+     * Asserts a response header
+     *
+     * @param name - Header name (case-insensitive)
+     * @param expected - Exact value, or a pattern to match
+     * @returns this, for chaining
+     */
+    expectHeader(name: string, expected: string | RegExp): this;
+    /**
+     * Asserts the whole JSON body deep-equals the expected value
+     *
+     * @param expected - Expected body
+     * @returns this, for chaining
+     */
+    expectJson<T>(expected: T): this;
+    /**
+     * Asserts the JSON body contains at least the given properties
+     *
+     * @param partial - Subset the body must match
+     * @returns this, for chaining
+     */
+    expectJsonContains(partial: object): this;
+    /**
+     * Asserts the raw text body
+     *
+     * @param expected - Exact body, or a pattern to match
+     * @returns this, for chaining
+     */
+    expectBody(expected: string | RegExp): this;
+    /**
+     * Escape hatch for assertions the chain does not cover
+     *
+     * @param assertion - Runs against the buffered response, may be async
+     * @returns this, for chaining
+     *
+     * @example
+     * ```typescript
+     * await app.get('/users').expect((res) => {
+     *   expect(res.json<User[]>()).toHaveLength(3);
+     * });
+     * ```
+     */
+    expect(assertion: (response: TestHttpResponse) => void | Promise<void>): this;
+    then<TResult1 = TestHttpResponse, TResult2 = never>(onfulfilled?: ((value: TestHttpResponse) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    private enqueue;
+    private send;
+    private run;
+    private describeRequest;
+}

package/dist/lib/test/http/TestHttpCall.js

@@ -0,0 +1,149 @@
+import { expect } from 'bun:test';
+import { TestHttpResponse, truncate } from './TestHttpResponse';
+/**
+ * A pending HTTP call with a fluent assertion chain.
+ *
+ * Nothing is sent until the call is awaited. Assertions queue up in the order they were
+ * chained and run against the buffered response; the send is memoized, so awaiting the
+ * same call twice does not issue a second request.
+ *
+ * @example
+ * ```typescript
+ * await app.get('/users/1').expectStatus(200).expectJson({ id: '1', name: 'Ada' });
+ *
+ * const res = await app.post('/users', { body: JSON.stringify({ name: 'Ada' }) }).expectStatus(201);
+ * expect(res.json().id).toBeString();
+ * ```
+ */
+export class TestHttpCall {
+    assertions = [];
+    pending;
+    url;
+    init;
+    constructor(url, init) {
+        this.url = url;
+        this.init = init;
+    }
+    /**
+     * Asserts the response status code
+     *
+     * @param expected - Expected status
+     * @returns this, for chaining
+     */
+    expectStatus(expected) {
+        // Deliberately not `expect(status).toBe(n)`: a bare number mismatch is the least
+        // useful failure in an HTTP test. The body almost always explains why.
+        return this.enqueue((response) => {
+            if (response.status !== expected) {
+                throw new Error(`Expected status ${expected} but received ${response.status} for ${this.describeRequest()}\n` +
+                    `Body: ${truncate(response.text())}`);
+            }
+        });
+    }
+    /**
+     * Asserts a response header
+     *
+     * @param name - Header name (case-insensitive)
+     * @param expected - Exact value, or a pattern to match
+     * @returns this, for chaining
+     */
+    expectHeader(name, expected) {
+        return this.enqueue((response) => {
+            const actual = response.headers.get(name);
+            if (actual === null) {
+                const received = [];
+                response.headers.forEach((_value, key) => received.push(key));
+                throw new Error(`Expected header '${name}' to be present for ${this.describeRequest()}, but it was not sent.\n` +
+                    `Received headers: ${received.join(', ') || '<none>'}`);
+            }
+            if (expected instanceof RegExp) {
+                expect(actual).toMatch(expected);
+            }
+            else {
+                expect(actual).toBe(expected);
+            }
+        });
+    }
+    /**
+     * Asserts the whole JSON body deep-equals the expected value
+     *
+     * @param expected - Expected body
+     * @returns this, for chaining
+     */
+    expectJson(expected) {
+        return this.enqueue((response) => {
+            expect(response.json()).toEqual(expected);
+        });
+    }
+    /**
+     * Asserts the JSON body contains at least the given properties
+     *
+     * @param partial - Subset the body must match
+     * @returns this, for chaining
+     */
+    expectJsonContains(partial) {
+        return this.enqueue((response) => {
+            expect(response.json()).toMatchObject(partial);
+        });
+    }
+    /**
+     * Asserts the raw text body
+     *
+     * @param expected - Exact body, or a pattern to match
+     * @returns this, for chaining
+     */
+    expectBody(expected) {
+        return this.enqueue((response) => {
+            if (expected instanceof RegExp) {
+                expect(response.text()).toMatch(expected);
+            }
+            else {
+                expect(response.text()).toBe(expected);
+            }
+        });
+    }
+    /**
+     * Escape hatch for assertions the chain does not cover
+     *
+     * @param assertion - Runs against the buffered response, may be async
+     * @returns this, for chaining
+     *
+     * @example
+     * ```typescript
+     * await app.get('/users').expect((res) => {
+     *   expect(res.json<User[]>()).toHaveLength(3);
+     * });
+     * ```
+     */
+    expect(assertion) {
+        return this.enqueue(assertion);
+    }
+    then(onfulfilled, onrejected) {
+        return this.send().then(onfulfilled, onrejected);
+    }
+    enqueue(assertion) {
+        if (this.pending !== undefined) {
+            throw new Error('Cannot add assertions to a TestHttpCall that has already been sent. ' +
+                'Chain every expect* call before awaiting the request.');
+        }
+        this.assertions.push(assertion);
+        return this;
+    }
+    send() {
+        if (this.pending === undefined) {
+            this.pending = this.run();
+        }
+        return this.pending;
+    }
+    async run() {
+        const response = await TestHttpResponse.from(await fetch(this.url, this.init));
+        for (const assertion of this.assertions) {
+            await assertion(response);
+        }
+        return response;
+    }
+    describeRequest() {
+        return `${(this.init?.method ?? 'GET').toUpperCase()} ${this.url}`;
+    }
+}
+//# sourceMappingURL=TestHttpCall.js.map

package/dist/lib/test/http/TestHttpCall.js.map

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

package/dist/lib/test/http/TestHttpResponse.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A response whose body has already been read.
+ *
+ * `Response` bodies can only be consumed once, which makes them awkward to assert against
+ * more than one way. This buffers the body at construction so `text()` and `json()` are
+ * synchronous and repeatable.
+ */
+export declare class TestHttpResponse {
+    /**
+     * The underlying fetch Response. Its body stream is already consumed.
+     */
+    readonly raw: Response;
+    private readonly body;
+    private constructor();
+    /**
+     * Buffers a fetch Response into a TestHttpResponse
+     *
+     * @param raw - Response to consume
+     * @returns The buffered response
+     */
+    static from(raw: Response): Promise<TestHttpResponse>;
+    get status(): number;
+    get headers(): Headers;
+    /**
+     * The response body as text
+     *
+     * @returns Body string
+     */
+    text(): string;
+    /**
+     * The response body parsed as JSON
+     *
+     * @returns Parsed body
+     * @throws When the body is not valid JSON - the message includes the raw body
+     */
+    json<T = any>(): T;
+}
+/**
+ * Shortens a body for error messages so a large HTML page cannot bury the failure
+ *
+ * @param value - Body text
+ * @returns Truncated text
+ *
+ * @internal
+ */
+export declare function truncate(value: string, limit?: number): string;