@velajs/testing 0.2.1 → 0.5.0

package/dist/sse/test-sse-connection.js

@@ -0,0 +1,196 @@
+// Ported near-verbatim from @stratal/testing (MIT, © Temitayo Fadojutimi).
+// Web-standard only (ReadableStream + TextDecoder), so it is edge-pure.
+import { expect } from "vitest";
+/**
+ * TestSseConnection
+ *
+ * Reads a streaming `text/event-stream` response body and exposes queue-based
+ * wait/assert helpers over the parsed events.
+ *
+ * @example
+ * ```ts
+ * const sse = await module.sse('/stream/events').connect();
+ * await sse.assertEventData('ping');
+ * await sse.waitForEnd();
+ * ```
+ */ export class TestSseConnection {
+    response;
+    eventQueue = [];
+    eventWaiters = [];
+    streamEnded = false;
+    endWaiters = [];
+    constructor(response){
+        this.response = response;
+        this.startReading();
+    }
+    /** The raw `Response`. */ get raw() {
+        return this.response;
+    }
+    /** Wait for the next event (rejects after `timeout` ms). */ async waitForEvent(timeout = 5000) {
+        if (this.eventQueue.length > 0) {
+            return this.eventQueue.shift();
+        }
+        if (this.streamEnded) {
+            throw new Error('SSE: stream has ended, no more events');
+        }
+        return new Promise((resolve, reject)=>{
+            const waiter = (event)=>{
+                clearTimeout(timer);
+                resolve(event);
+            };
+            const timer = setTimeout(()=>{
+                const index = this.eventWaiters.indexOf(waiter);
+                if (index !== -1) this.eventWaiters.splice(index, 1);
+                reject(new Error(`SSE: no event received within ${timeout}ms`));
+            }, timeout);
+            this.eventWaiters.push(waiter);
+        });
+    }
+    /** Wait for the stream to end (rejects after `timeout` ms). */ async waitForEnd(timeout = 5000) {
+        if (this.streamEnded) return;
+        return new Promise((resolve, reject)=>{
+            const waiter = ()=>{
+                clearTimeout(timer);
+                resolve();
+            };
+            const timer = setTimeout(()=>{
+                const index = this.endWaiters.indexOf(waiter);
+                if (index !== -1) this.endWaiters.splice(index, 1);
+                reject(new Error(`SSE: stream did not end within ${timeout}ms`));
+            }, timeout);
+            this.endWaiters.push(waiter);
+        });
+    }
+    /** Collect all remaining events until the stream ends. */ async collectEvents(timeout = 5000) {
+        const events = [];
+        if (this.streamEnded) {
+            return [
+                ...this.eventQueue.splice(0)
+            ];
+        }
+        return new Promise((resolve, reject)=>{
+            const originalDispatch = this.dispatchEvent.bind(this);
+            this.dispatchEvent = (event)=>{
+                events.push(event);
+                originalDispatch(event);
+            };
+            const endWaiter = ()=>{
+                clearTimeout(timer);
+                this.dispatchEvent = originalDispatch;
+                resolve(events);
+            };
+            const timer = setTimeout(()=>{
+                this.dispatchEvent = originalDispatch;
+                const index = this.endWaiters.indexOf(endWaiter);
+                if (index !== -1) this.endWaiters.splice(index, 1);
+                reject(new Error(`SSE: stream did not end within ${timeout}ms`));
+            }, timeout);
+            events.push(...this.eventQueue.splice(0));
+            this.endWaiters.push(endWaiter);
+        });
+    }
+    /** Assert the next event matches the expected partial shape. */ async assertEvent(expected, timeout = 5000) {
+        const event = await this.waitForEvent(timeout);
+        expect(event).toMatchObject(expected);
+    }
+    /** Assert the next event's `data` equals `expected`. */ async assertEventData(expected, timeout = 5000) {
+        const event = await this.waitForEvent(timeout);
+        expect(event.data, `Expected SSE data "${expected}", got "${event.data}"`).toBe(expected);
+    }
+    /** Assert the next event's `data` is JSON equal to `expected`. */ async assertJsonEventData(expected, timeout = 5000) {
+        const event = await this.waitForEvent(timeout);
+        const parsed = JSON.parse(event.data);
+        expect(parsed).toEqual(expected);
+    }
+    startReading() {
+        const body = this.response.body;
+        if (!body) {
+            this.streamEnded = true;
+            return;
+        }
+        const reader = body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        const read = async ()=>{
+            try {
+                for(;;){
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        if (buffer.trim()) {
+                            const event = this.parseEvent(buffer);
+                            if (event) this.dispatchEvent(event);
+                        }
+                        this.endStream();
+                        return;
+                    }
+                    buffer += decoder.decode(value, {
+                        stream: true
+                    });
+                    const parts = buffer.split('\n\n');
+                    buffer = parts.pop();
+                    for (const part of parts){
+                        if (!part.trim()) continue;
+                        const event = this.parseEvent(part);
+                        if (event) this.dispatchEvent(event);
+                    }
+                }
+            } catch  {
+                this.endStream();
+            }
+        };
+        void read();
+    }
+    endStream() {
+        this.streamEnded = true;
+        for (const waiter of this.endWaiters){
+            waiter();
+        }
+        this.endWaiters = [];
+    }
+    parseEvent(raw) {
+        const lines = raw.split('\n');
+        const dataLines = [];
+        let event;
+        let id;
+        let retry;
+        for (const line of lines){
+            if (line.startsWith(':')) continue; // comment line
+            const colonIndex = line.indexOf(':');
+            if (colonIndex === -1) continue;
+            const field = line.slice(0, colonIndex);
+            const value = line[colonIndex + 1] === ' ' ? line.slice(colonIndex + 2) : line.slice(colonIndex + 1);
+            switch(field){
+                case 'data':
+                    dataLines.push(value);
+                    break;
+                case 'event':
+                    event = value;
+                    break;
+                case 'id':
+                    id = value;
+                    break;
+                case 'retry':
+                    {
+                        const parsed = parseInt(value, 10);
+                        if (!Number.isNaN(parsed)) retry = parsed;
+                        break;
+                    }
+            }
+        }
+        if (dataLines.length === 0) return null;
+        const result = {
+            data: dataLines.join('\n')
+        };
+        if (event !== undefined) result.event = event;
+        if (id !== undefined) result.id = id;
+        if (retry !== undefined) result.retry = retry;
+        return result;
+    }
+    dispatchEvent(event) {
+        if (this.eventWaiters.length > 0) {
+            this.eventWaiters.shift()(event);
+        } else {
+            this.eventQueue.push(event);
+        }
+    }
+}

package/dist/sse/test-sse-request.d.ts

@@ -0,0 +1,30 @@
+import type { ActingAsResolver, TestPrincipal, TestingModule } from '../testing-module.js';
+import { TestSseConnection } from './test-sse-connection.js';
+/**
+ * TestSseRequest
+ *
+ * Builder for a Server-Sent Events connection. `connect()` issues a GET through
+ * `module.fetch()`, asserts a `text/event-stream` 200, and wraps the streaming
+ * body in a {@link TestSseConnection}.
+ *
+ * @example
+ * ```ts
+ * const sse = await module.sse('/stream/events').connect();
+ * await sse.assertEvent({ event: 'message', data: 'hello' });
+ * ```
+ */
+export declare class TestSseRequest {
+    private readonly path;
+    private readonly module;
+    private readonly requestHeaders;
+    private principal;
+    private resolver;
+    constructor(path: string, module: TestingModule);
+    /** Merge additional headers onto the SSE request. */
+    withHeaders(headers: Record<string, string>): this;
+    /** Authenticate the connection (see {@link TestHttpRequest.actingAs}). */
+    actingAs(principal: TestPrincipal, resolver?: ActingAsResolver): this;
+    /** Open the stream and return a live {@link TestSseConnection}. */
+    connect(): Promise<TestSseConnection>;
+    private applyAuthentication;
+}

package/dist/sse/test-sse-request.js

@@ -0,0 +1,62 @@
+// Adapted from @stratal/testing (MIT, © Temitayo Fadojutimi). Auth uses the
+// generic resolver seam instead of a hard AuthService import.
+import { expect } from "vitest";
+import { TestSseConnection } from "./test-sse-connection.js";
+/**
+ * TestSseRequest
+ *
+ * Builder for a Server-Sent Events connection. `connect()` issues a GET through
+ * `module.fetch()`, asserts a `text/event-stream` 200, and wraps the streaming
+ * body in a {@link TestSseConnection}.
+ *
+ * @example
+ * ```ts
+ * const sse = await module.sse('/stream/events').connect();
+ * await sse.assertEvent({ event: 'message', data: 'hello' });
+ * ```
+ */ export class TestSseRequest {
+    path;
+    module;
+    requestHeaders = new Headers();
+    principal = null;
+    resolver = null;
+    constructor(path, module){
+        this.path = path;
+        this.module = module;
+    }
+    /** Merge additional headers onto the SSE request. */ withHeaders(headers) {
+        for (const [key, value] of Object.entries(headers)){
+            this.requestHeaders.set(key, value);
+        }
+        return this;
+    }
+    /** Authenticate the connection (see {@link TestHttpRequest.actingAs}). */ actingAs(principal, resolver) {
+        this.principal = principal;
+        this.resolver = resolver ?? null;
+        return this;
+    }
+    /** Open the stream and return a live {@link TestSseConnection}. */ async connect() {
+        await this.applyAuthentication();
+        this.requestHeaders.set('Accept', 'text/event-stream');
+        const url = new URL(this.path, 'http://localhost');
+        const request = new Request(url.toString(), {
+            headers: this.requestHeaders
+        });
+        const response = await this.module.fetch(request);
+        expect(response.status, `Expected status 200, got ${response.status}`).toBe(200);
+        const contentType = response.headers.get('content-type') ?? '';
+        expect(contentType.includes('text/event-stream'), `Expected content-type "text/event-stream", got "${contentType}"`).toBe(true);
+        return new TestSseConnection(response);
+    }
+    async applyAuthentication() {
+        if (!this.principal) return;
+        const resolver = this.resolver ?? this.module.getAuthResolver();
+        if (!resolver) {
+            throw new Error('actingAs() requires an auth resolver. Pass one explicitly or register ' + 'a default with module.setAuthResolver(resolver).');
+        }
+        const headers = await resolver(this.module, this.principal);
+        for (const [key, value] of headers.entries()){
+            this.requestHeaders.set(key, value);
+        }
+    }
+}

package/dist/testing-module.builder.js

@@ -1,5 +1,5 @@
-import { REQUEST_CONTEXT, Scope } from "@velajs/vela";
-import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE, ComponentManager, Container, MetadataRegistry, ModuleLoader, ModuleRef, RouteManager, VelaApplication, bindAppProviders } from "@velajs/vela/internal";
+import { DiscoveryService, REQUEST_CONTEXT, Scope } from "@velajs/vela";
+import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE, Container, MetadataRegistry, ModuleLoader, ModuleRef, RouteManager, VelaApplication, bindAppProviders } from "@velajs/vela/internal";
 import { TestingModule } from "./testing-module.js";
 export class OverrideBy {
     builder;
@@ -97,6 +97,17 @@ export class TestingModuleBuilder {
             ]
         });
         container.markGlobalToken(ModuleRef);
+        // Decorator-driven discovery — global so any provider can inject it, and so
+        // callOnApplicationBootstrap() reuses this instance instead of self-building
+        // one. Mirrors vela/src/factory/bootstrap.ts.
+        container.register({
+            provide: DiscoveryService,
+            useFactory: (c)=>new DiscoveryService(c),
+            inject: [
+                Container
+            ]
+        });
+        container.markGlobalToken(DiscoveryService);
         for (const t of [
             APP_GUARD,
             APP_PIPE,
@@ -126,27 +137,16 @@ export class TestingModuleBuilder {
             container.register(override.provider);
         }
         const routeManager = new RouteManager(container);
-        ComponentManager.init(container);
         const loader = new ModuleLoader(container, routeManager);
         loader.load(TestRootModule);
         // Force-apply overrides into every module bucket that already holds the
-        // token. Without this, controller constructor-injection (which passes
-        // requestingModuleId to findRegistration) finds the module's own
-        // registration first and never consults the root override. Re-registering
-        // with the module's id overwrites the bucket entry.
-        //
-        // Reaches into Container internals (the `providers` map) until vela
-        // exposes a public "force replace across all scopes" API. The shape is
-        // stable in vela 1.6.x; if this breaks under a future vela version, raise
-        // a vela API request before working around again.
-        const providersMap = container.providers;
+        // token (plus root). Without this, controller constructor-injection (which
+        // passes requestingModuleId to findRegistration) finds the module's own
+        // registration first and never consults the root override. The default
+        // 'all-existing' buckets replace every non-root bucket holding the token
+        // and re-register at root — the supported form of the old private loop.
         for (const override of this.overrides){
-            for (const [moduleId, bucket] of providersMap){
-                if (moduleId === '__root__') continue;
-                if (bucket.has(override.token)) {
-                    container.register(override.provider, moduleId);
-                }
-            }
+            container.replaceProvider(override.provider);
         }
         bindAppProviders(routeManager, container, loader);
         const app = new VelaApplication(container, routeManager);

package/dist/testing-module.d.ts

@@ -1,10 +1,87 @@
-import type { Token, VelaApplication } from '@velajs/vela';
+import { type Token, type Type, type VelaApplication } from '@velajs/vela';
 import type { Container } from '@velajs/vela/internal';
+import { type ISeeder } from '@velajs/vela/seeder';
+import type { TestDatabase } from './db/test-database.js';
+import { TestHttpClient } from './http/test-http-client.js';
+import { TestSseRequest } from './sse/test-sse-request.js';
+import { TestWsRequest } from './ws/test-ws-request.js';
+/** A test principal — an opaque object the auth resolver turns into headers. */
+export type TestPrincipal = Record<string, unknown>;
+/**
+ * Turns a principal into request headers (session cookie, bearer token, …).
+ * The signature `(module, principal) => Promise<Headers>` is a cross-package
+ * contract: sibling packages (e.g. `@velajs/better-auth/testing`) build a
+ * resolver against it. Kept generic so `@velajs/testing` needs no auth deps.
+ */
+export type ActingAsResolver = (module: TestingModule, principal: TestPrincipal) => Promise<Headers>;
+/**
+ * TestingModule
+ *
+ * The compiled test harness. Beyond `get`/`createApplication`/`close`, it adds
+ * Laravel-flavored ergonomics: a fluent HTTP client, SSE/WS builders, request-
+ * scope execution, seeding, and database assertion wrappers.
+ *
+ * @example
+ * ```ts
+ * const module = await Test.createTestingModule({ imports: [AppModule] }).compile();
+ * await module.http.post('/users').withBody({ name: 'A' }).send()
+ *   .then((r) => r.assertCreated());
+ * ```
+ */
 export declare class TestingModule {
     private readonly app;
     private readonly container;
+    private _http;
+    private honoApp;
+    private authResolver;
     constructor(app: VelaApplication, container: Container);
+    /** Resolve a provider from the root container. */
     get<T>(token: Token<T>): T;
+    /** Build (once) and return the underlying application. */
     createApplication(): Promise<VelaApplication>;
+    /** Lazy fluent HTTP client bound to this module. */
+    get http(): TestHttpClient;
+    /** Start an SSE connection builder for `path`. */
+    sse(path: string): TestSseRequest;
+    /** Start a WebSocket connection builder for `path` (needs a transport adapter). */
+    ws(path: string): TestWsRequest;
+    /**
+     * Drive a `Request` through the full Hono pipeline. The Hono app is built
+     * once and reused across requests.
+     */
+    fetch(request: Request, env?: unknown, ctx?: unknown): Promise<Response>;
+    /**
+     * Register a default auth resolver used by `actingAs(principal)` when no
+     * resolver is passed explicitly.
+     */
+    setAuthResolver(resolver: ActingAsResolver): this;
+    /** The default auth resolver, if one was registered. */
+    getAuthResolver(): ActingAsResolver | null;
+    /**
+     * Run `callback` inside a request-scoped child container seeded with a mock
+     * {@link RequestContext}, so REQUEST-scoped providers (and anything injecting
+     * `REQUEST_CONTEXT`) resolve. The child is disposed afterwards.
+     */
+    runInRequestScope<T>(callback: (container: Container) => T | Promise<T>): Promise<T>;
+    /**
+     * Run the given `@Seeder()` classes, each in its own request scope. Throws if
+     * a class is not a registered seeder. Requires `SeederModule` (or the seeders
+     * themselves) to be present in the module graph.
+     */
+    seed(...SeederClasses: Type<ISeeder>[]): Promise<void>;
+    /** Assert a row matching `where` exists in `table` (via a {@link TestDatabase}). */
+    assertDatabaseHas(db: TestDatabase, table: string, where: Record<string, unknown>): Promise<void>;
+    /** Assert no row matching `where` exists in `table`. */
+    assertDatabaseMissing(db: TestDatabase, table: string, where: Record<string, unknown>): Promise<void>;
+    /** Assert `table` has exactly `expected` rows. */
+    assertDatabaseCount(db: TestDatabase, table: string, expected: number): Promise<void>;
+    /** Dispose the application. */
     close(signal?: string): Promise<void>;
+    private ensureHono;
+    /**
+     * Build a minimal, functional {@link RequestContext} for out-of-band request
+     * scopes. Vela has no `createMockRouterContext`; a real (empty) Hono `Context`
+     * backs the `hono` field so nothing dangles.
+     */
+    private createMockRequestContext;
 }

package/dist/testing-module.js

@@ -1,18 +1,141 @@
-export class TestingModule {
+import { Context } from "hono";
+import { REQUEST_CONTEXT } from "@velajs/vela";
+import { SeederRegistry } from "@velajs/vela/seeder";
+import { expect } from "vitest";
+import { TestHttpClient } from "./http/test-http-client.js";
+import { TestSseRequest } from "./sse/test-sse-request.js";
+import { TestWsRequest } from "./ws/test-ws-request.js";
+/**
+ * TestingModule
+ *
+ * The compiled test harness. Beyond `get`/`createApplication`/`close`, it adds
+ * Laravel-flavored ergonomics: a fluent HTTP client, SSE/WS builders, request-
+ * scope execution, seeding, and database assertion wrappers.
+ *
+ * @example
+ * ```ts
+ * const module = await Test.createTestingModule({ imports: [AppModule] }).compile();
+ * await module.http.post('/users').withBody({ name: 'A' }).send()
+ *   .then((r) => r.assertCreated());
+ * ```
+ */ export class TestingModule {
     app;
     container;
+    _http = null;
+    honoApp = null;
+    authResolver = null;
     constructor(app, container){
         this.app = app;
         this.container = container;
     }
-    get(token) {
+    /** Resolve a provider from the root container. */ get(token) {
         return this.container.resolve(token);
     }
-    async createApplication() {
+    /** Build (once) and return the underlying application. */ async createApplication() {
         await this.app.initRoutes();
         return this.app;
     }
-    async close(signal) {
+    /** Lazy fluent HTTP client bound to this module. */ get http() {
+        this._http ??= new TestHttpClient(this);
+        return this._http;
+    }
+    /** Start an SSE connection builder for `path`. */ sse(path) {
+        return new TestSseRequest(path, this);
+    }
+    /** Start a WebSocket connection builder for `path` (needs a transport adapter). */ ws(path) {
+        return new TestWsRequest(path, this);
+    }
+    /**
+   * Drive a `Request` through the full Hono pipeline. The Hono app is built
+   * once and reused across requests.
+   */ async fetch(request, env, ctx) {
+        const hono = await this.ensureHono();
+        return hono.fetch(request, env, ctx);
+    }
+    /**
+   * Register a default auth resolver used by `actingAs(principal)` when no
+   * resolver is passed explicitly.
+   */ setAuthResolver(resolver) {
+        this.authResolver = resolver;
+        return this;
+    }
+    /** The default auth resolver, if one was registered. */ getAuthResolver() {
+        return this.authResolver;
+    }
+    /**
+   * Run `callback` inside a request-scoped child container seeded with a mock
+   * {@link RequestContext}, so REQUEST-scoped providers (and anything injecting
+   * `REQUEST_CONTEXT`) resolve. The child is disposed afterwards.
+   */ async runInRequestScope(callback) {
+        const child = this.container.createChild();
+        child.setRequestInstance(REQUEST_CONTEXT, this.createMockRequestContext());
+        try {
+            return await callback(child);
+        } finally{
+            await child.dispose();
+        }
+    }
+    /**
+   * Run the given `@Seeder()` classes, each in its own request scope. Throws if
+   * a class is not a registered seeder. Requires `SeederModule` (or the seeders
+   * themselves) to be present in the module graph.
+   */ async seed(...SeederClasses) {
+        const registry = this.container.resolve(SeederRegistry);
+        const known = new Set(registry.list().map((s)=>s.target));
+        for (const SeederClass of SeederClasses){
+            if (!known.has(SeederClass)) {
+                throw new Error(`Seeder "${SeederClass.name}" is not registered. Add it to a module's ` + 'providers or SeederModule.forRoot({ seeders: [...] }).');
+            }
+            await this.runInRequestScope(async (child)=>{
+                const instance = child.resolve(SeederClass);
+                await instance.run();
+            });
+        }
+    }
+    /** Assert a row matching `where` exists in `table` (via a {@link TestDatabase}). */ async assertDatabaseHas(db, table, where) {
+        const exists = await db.has(table, where);
+        expect(exists, `Expected ${table} to have a row matching ${JSON.stringify(where)}`).toBe(true);
+    }
+    /** Assert no row matching `where` exists in `table`. */ async assertDatabaseMissing(db, table, where) {
+        const exists = await db.has(table, where);
+        expect(exists, `Expected ${table} NOT to have a row matching ${JSON.stringify(where)}`).toBe(false);
+    }
+    /** Assert `table` has exactly `expected` rows. */ async assertDatabaseCount(db, table, expected) {
+        const actual = await db.count(table);
+        expect(actual, `Expected ${table} count ${expected}, got ${actual}`).toBe(expected);
+    }
+    /** Dispose the application. */ async close(signal) {
         await this.app.close(signal);
     }
+    async ensureHono() {
+        if (!this.honoApp) {
+            const app = await this.createApplication();
+            this.honoApp = app.getHonoApp();
+        }
+        return this.honoApp;
+    }
+    /**
+   * Build a minimal, functional {@link RequestContext} for out-of-band request
+   * scopes. Vela has no `createMockRouterContext`; a real (empty) Hono `Context`
+   * backs the `hono` field so nothing dangles.
+   */ createMockRequestContext() {
+        const bag = new Map();
+        const request = new Request('http://localhost/');
+        const hono = new Context(request);
+        return {
+            id: crypto.randomUUID(),
+            receivedAt: new Date(),
+            request,
+            hono,
+            set (key, value) {
+                bag.set(key, value);
+            },
+            get (key) {
+                return bag.get(key);
+            },
+            has (key) {
+                return bag.has(key);
+            }
+        };
+    }
 }

package/dist/websocket-node/index.d.ts

@@ -0,0 +1 @@
+export {};