@celerity-sdk/testing 0.8.0

package/dist/index.d.ts

@@ -0,0 +1,323 @@
+import { Type, Provider, InjectionToken, HttpRequest, HttpResponse, WebSocketMessage, ConsumerEventInput, EventResult, ScheduleEventInput } from '@celerity-sdk/types';
+import { TestingApplication, Container, HandlerRegistry } from '@celerity-sdk/core';
+export { mockConsumerEvent, mockRequest, mockScheduleEvent, mockWebSocketMessage } from '@celerity-sdk/core';
+
+/**
+ * Parsed resource token info extracted from a Symbol description
+ * like "celerity:datastore:usersDatastore".
+ */
+type ResourceTokenInfo = {
+    token: symbol;
+    type: string;
+    name: string;
+};
+/**
+ * Walks the module graph for the given root module and extracts all resource
+ * layer tokens from provider, controller, and guard constructor parameters.
+ *
+ * This discovers which resources the module (and its imports) depend on
+ * without instantiating anything.
+ */
+declare function discoverResourceTokens(rootModule: Type): ResourceTokenInfo[];
+
+type MockFn = (...args: any[]) => any;
+type MockFnCreator = () => MockFn;
+/**
+ * Creates a mock object for a resource type with all interface methods stubbed.
+ * Returns null for resource types that cannot be meaningfully mocked (e.g. sqlDatabase).
+ */
+declare function createResourceMock(resourceType: string, mockFn?: MockFnCreator): Record<string, MockFn> | null;
+/**
+ * Creates mock objects for all discovered resource tokens.
+ * Returns a map of token → mock object. Tokens for unmockable resource types
+ * (like sqlDatabase) are omitted.
+ */
+declare function createMocksForTokens(tokens: ResourceTokenInfo[], mockFn?: MockFnCreator): Map<symbol, Record<string, MockFn>>;
+
+type CreateTestAppOptions = {
+    /** The module under test. Its providers, controllers, guards, and imports are bootstrapped. */
+    module: Type;
+    /** When true, creates real resource clients from env vars. When false (default), creates mocks. */
+    integration?: boolean;
+    /** Additional providers to register in the test module. */
+    providers?: Array<Type | (Provider & {
+        provide: InjectionToken;
+    })>;
+    /** Additional controllers to register. */
+    controllers?: Type[];
+    /** Additional guards to register. */
+    guards?: Type[];
+    /** Explicit overrides registered last — takes precedence over auto-discovery. */
+    overrides?: Record<symbol, unknown>;
+    /** Path to the blueprint file. Auto-detected if omitted. */
+    blueprintPath?: string;
+};
+/**
+ * TestApp wraps TestingApplication with mock access and lifecycle management.
+ */
+declare class TestApp {
+    private mocks;
+    private closeables;
+    private inner;
+    constructor(inner: TestingApplication, mocks: Map<symbol, Record<string, MockFn>>, closeables: Array<{
+        close?(): void | Promise<void>;
+    }>);
+    injectHttp(request: HttpRequest): Promise<HttpResponse>;
+    injectWebSocket(route: string, message: WebSocketMessage): Promise<void>;
+    injectConsumer(handlerTag: string, event: ConsumerEventInput): Promise<EventResult>;
+    injectSchedule(handlerTag: string, event: ScheduleEventInput): Promise<EventResult>;
+    injectCustom(name: string, payload?: unknown): Promise<unknown>;
+    getContainer(): Container;
+    getRegistry(): HandlerRegistry;
+    /** Retrieve the auto-generated mock for a resource token. */
+    getMock<T>(token: symbol): T;
+    /** Get the mock Datastore for a named resource (e.g., "usersDatastore"). */
+    getDatastoreMock(name: string): Record<string, MockFn>;
+    /** Get the mock Topic for a named resource. */
+    getTopicMock(name: string): Record<string, MockFn>;
+    /** Get the mock Queue for a named resource. */
+    getQueueMock(name: string): Record<string, MockFn>;
+    /** Get the mock Cache for a named resource. */
+    getCacheMock(name: string): Record<string, MockFn>;
+    /** Get the mock Bucket for a named resource. */
+    getBucketMock(name: string): Record<string, MockFn>;
+    /** Get the mock Config namespace for a named resource. */
+    getConfigMock(name: string): Record<string, MockFn>;
+    /** Close all real resource clients (integration mode). No-op in unit mode. */
+    close(): Promise<void>;
+}
+/**
+ * Create a test application for unit or integration testing.
+ *
+ * - `integration: false` (default): Auto-discovers resource dependencies from the
+ *   module graph and creates mock objects for each. Access mocks via `app.getDatastoreMock()`, etc.
+ *
+ * - `integration: true`: Creates real resource clients from env vars provided by
+ *   `celerity dev test`. Physical resource names are resolved from the blueprint.
+ *
+ * In both modes, custom providers/controllers/guards can be added, and explicit
+ * overrides take precedence over auto-discovered resources.
+ */
+declare function createTestApp(options: CreateTestAppOptions): Promise<TestApp>;
+
+type GenerateTestTokenOptions = {
+    /** Subject claim (required by the dev auth server). Default: "test-user" */
+    sub?: string;
+    /** Arbitrary claims spread into the JWT payload (roles, permissions, org_id, etc.). */
+    claims?: Record<string, unknown>;
+    /** Token lifetime as a Go-style duration string. Default: "1h" */
+    expiresIn?: string;
+};
+/**
+ * Generate an RS256-signed JWT by calling the local dev auth server.
+ *
+ * The dev auth server runs as a sidecar in `celerity dev test` / `celerity dev run`
+ * and is accessible via the `CELERITY_DEV_AUTH_BASE_URL` env var.
+ *
+ * @returns The signed access token string.
+ * @throws If the dev auth server is unreachable or returns an error.
+ */
+declare function generateTestToken(options?: GenerateTestTokenOptions): Promise<string>;
+
+/**
+ * Asserting HTTP client for API tests against a running application.
+ * Reads `CELERITY_TEST_BASE_URL` (default http://localhost:8081).
+ */
+type TestResponse<TBody = unknown> = {
+    status: number;
+    headers: Headers;
+    body: TBody;
+    text: string;
+};
+type ExpectFn = (body: unknown) => void;
+declare class TestRequest<TBody = unknown> {
+    private baseUrl;
+    private method;
+    private path;
+    private _headers;
+    private _body?;
+    private _expectations;
+    constructor(baseUrl: string, method: string, path: string);
+    /** Set an authorization bearer token. */
+    auth(token: string): this;
+    /** Set a request header. */
+    set(key: string, value: string): this;
+    /** Set the request JSON body. */
+    send(body: unknown): this;
+    /** Add an expectation. Overloaded: status code, body object/fn, or header. */
+    expect(statusOrBodyOrFn: number | unknown | ExpectFn): this;
+    expect(header: string, value: string | RegExp): this;
+    /** Execute the request and run all expectations. Returns the response. */
+    end(): Promise<TestResponse<TBody>>;
+    private assertExpectation;
+    private assertHeader;
+    /** Implements PromiseLike so the request chain can be awaited directly. */
+    then<T>(// intentional thenable for fluent await syntax
+    resolve: (value: TestResponse<TBody>) => T | PromiseLike<T>, reject?: (reason: unknown) => T | PromiseLike<T>): Promise<T>;
+}
+declare class TestHttpClient {
+    private baseUrl;
+    constructor(baseUrl: string);
+    get<TBody = Record<string, unknown>>(path: string): TestRequest<TBody>;
+    post<TBody = Record<string, unknown>>(path: string): TestRequest<TBody>;
+    put<TBody = Record<string, unknown>>(path: string): TestRequest<TBody>;
+    patch<TBody = Record<string, unknown>>(path: string): TestRequest<TBody>;
+    delete<TBody = Record<string, unknown>>(path: string): TestRequest<TBody>;
+}
+/**
+ * Create a test HTTP client for API tests.
+ * Reads `CELERITY_TEST_BASE_URL` env var (default: http://localhost:8081).
+ */
+declare function createTestClient(options?: {
+    baseUrl?: string;
+}): TestHttpClient;
+
+/**
+ * Polls a predicate function until it returns true or the timeout expires.
+ *
+ * @param predicate - Function that returns true when the condition is met.
+ * @param options - Timeout (ms, default 5000) and poll interval (ms, default 100).
+ */
+declare function waitFor(predicate: () => Promise<boolean> | boolean, options?: {
+    timeout?: number;
+    interval?: number;
+}): Promise<void>;
+
+/**
+ * Sequential WebSocket test client for Celerity applications.
+ *
+ * Wraps `@celerity-sdk/ws-client` to provide an `await`-based message flow.
+ * All runtime protocol concerns (heartbeat, capabilities negotiation, ack,
+ * dedup) are handled by the underlying client — only application messages
+ * surface to tests.
+ *
+ * Configuration is derived from the blueprint and `celerity dev test` env vars.
+ */
+
+type Unsubscribe = () => void;
+/** Structural type for the subset of CelerityWsClient used by TestWsClient. */
+type WsClient = {
+    on(event: string, handler: (...args: never[]) => void): Unsubscribe;
+    connect(): Promise<void>;
+    send(route: string, data: unknown): string;
+    disconnect(): Promise<void>;
+    destroy(): void;
+    state: string;
+};
+type CreateTestWsClientOptions = {
+    /** Override the WebSocket URL. Derived from CELERITY_TEST_BASE_URL + blueprint basePath if omitted. */
+    url?: string;
+    /** Token for auth. String = use directly. Object = options for generateTestToken(). Omit to skip auth entirely. */
+    token?: string | GenerateTestTokenOptions | null;
+    /** Path to the blueprint file (auto-detected if omitted). */
+    blueprintPath?: string;
+    /** Additional config passed through to createWsClient. */
+    clientConfig?: Record<string, unknown>;
+};
+type ReceivedMessage = {
+    route: string;
+    data: unknown;
+};
+/**
+ * Create a sequential WebSocket test client.
+ *
+ * Config is derived from the blueprint (base path, route key, auth strategy)
+ * and `CELERITY_TEST_BASE_URL`. Pass `token: null` to skip authentication
+ * (useful for testing unauthenticated rejection).
+ *
+ * @example
+ * ```typescript
+ * const ws = await createTestWsClient();
+ * await ws.connect();
+ *
+ * ws.send("notifications", { action: "subscribe", channels: ["alerts"] });
+ * const msg = await ws.nextMessage();
+ * expect(msg.data).toEqual({ subscribed: ["alerts"] });
+ *
+ * await ws.disconnect();
+ * ```
+ *
+ * @example Skip auth for testing unauthenticated scenarios:
+ * ```typescript
+ * const ws = await createTestWsClient({ token: null });
+ * ```
+ */
+declare function createTestWsClient(options?: CreateTestWsClientOptions): Promise<TestWsClient>;
+/**
+ * Test-oriented WebSocket client with sequential `await`-based message flow.
+ *
+ * The underlying `CelerityWsClient` handles all runtime protocol messages
+ * (heartbeat, capabilities, auth, ack, dedup) transparently.
+ * Only application-level messages are surfaced via `nextMessage()`.
+ */
+declare class TestWsClient {
+    private inner;
+    private messageBuffer;
+    private waiters;
+    private cleanups;
+    private connectionError;
+    constructor(inner: WsClient);
+    /**
+     * Connect and complete the full handshake (including auth if configured).
+     *
+     * After connect resolves, `nextMessage()` will receive application messages.
+     * If auth fails or connection is rejected, the promise rejects with the error.
+     */
+    connect(): Promise<void>;
+    /** Send a routed application message. Returns the message ID. */
+    send(route: string, data: unknown): string;
+    /**
+     * Wait for the next application message from the server.
+     *
+     * If a message is already buffered, resolves immediately.
+     * Otherwise blocks until a message arrives, the connection closes, or timeout expires.
+     *
+     * @param timeout - Maximum wait time in ms. Default: 5000.
+     */
+    nextMessage(timeout?: number): Promise<ReceivedMessage>;
+    /** Disconnect and clean up all listeners and pending waiters. */
+    disconnect(): Promise<void>;
+    /** Force destroy without waiting for close handshake. */
+    destroy(): void;
+    /** Current connection state. */
+    get state(): string;
+    /** Access the underlying CelerityWsClient for advanced usage. */
+    get raw(): WsClient;
+    private cleanup;
+    private rejectAllWaiters;
+}
+
+/**
+ * Physical resource info extracted from the blueprint.
+ */
+type BlueprintResource = {
+    resourceId: string;
+    type: string;
+    physicalName: string;
+};
+/**
+ * Parse the app blueprint and extract resource definitions with their
+ * physical names (spec.name). This maps resource IDs used in decorators
+ * (e.g., "usersDatastore") to the actual infrastructure names (e.g., "users").
+ */
+declare function loadBlueprintResources(blueprintPath?: string): Map<string, BlueprintResource>;
+/**
+ * WebSocket configuration extracted from the blueprint's API resource.
+ */
+type WebSocketConfig = {
+    /** The base path for WebSocket connections (e.g., "/ws"). */
+    basePath: string;
+    /** The route key used for message routing (e.g., "action"). */
+    routeKey: string;
+    /** The auth strategy: "authMessage" or "connect". */
+    authStrategy: "authMessage" | "connect";
+};
+/**
+ * Extract WebSocket configuration from the first celerity/api resource
+ * in the blueprint that has WebSocket protocol configured.
+ *
+ * Returns null if no WebSocket configuration is found.
+ */
+declare function loadWebSocketConfig(blueprintPath?: string): WebSocketConfig | null;
+
+export { type BlueprintResource, type CreateTestAppOptions, type CreateTestWsClientOptions, type GenerateTestTokenOptions, type MockFn, type MockFnCreator, type ReceivedMessage, type ResourceTokenInfo, TestApp, TestHttpClient, TestRequest, type TestResponse, TestWsClient, type WebSocketConfig, createMocksForTokens, createResourceMock, createTestApp, createTestClient, createTestWsClient, discoverResourceTokens, generateTestToken, loadBlueprintResources, loadWebSocketConfig, waitFor };