@velajs/testing 0.4.0 → 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.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 {};

package/dist/websocket-node/index.js

@@ -0,0 +1,109 @@
+/**
+ * `@velajs/testing/websocket-node`
+ *
+ * Node transport adapter for `module.ws(path).connect()`. Importing this module
+ * (for its side effect) registers a WebSocket connector that:
+ *   1. builds the app's Hono instance and a `@hono/node-ws` upgrade factory,
+ *   2. registers every `@WebSocketGateway` via `@velajs/vela/websocket-node`,
+ *   3. serves it on an ephemeral loopback port, and
+ *   4. opens a real client `WebSocket` against it.
+ *
+ * `@hono/node-ws` and `@hono/node-server` are OPTIONAL peers, imported
+ * dynamically — this module loads without them and only errs at `connect()`
+ * time with an actionable message. Their types are declared locally so the
+ * package typechecks without the peers installed. Cloudflare Durable-Object
+ * WebSockets are exercised via `@velajs/cloudflare` + the workerd pool, not
+ * this adapter.
+ */ import { TestWsConnection } from "../ws/test-ws-connection.js";
+import { registerWsConnector } from "../ws/test-ws-request.js";
+// One backing HTTP server per module; gateways are registered exactly once.
+const serversByModule = new WeakMap();
+async function importOptional(specifier) {
+    try {
+        return await import(specifier);
+    } catch (error) {
+        throw new Error(`[@velajs/testing/websocket-node] "${specifier}" is required for WebSocket ` + 'connect() on Node but is not installed. Install the optional peers: ' + '`npm i -D @hono/node-ws @hono/node-server`.', {
+            cause: error
+        });
+    }
+}
+async function ensureServer(module) {
+    const existing = serversByModule.get(module);
+    if (existing) return existing;
+    const started = (async ()=>{
+        const { serve } = await importOptional('@hono/node-server');
+        const { createNodeWebSocket } = await importOptional('@hono/node-ws');
+        const { registerWebSocketGateways } = await importOptional('@velajs/vela/websocket-node');
+        const app = await module.createApplication();
+        const hono = app.getHonoApp();
+        const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({
+            app: hono
+        });
+        registerWebSocketGateways(app, upgradeWebSocket);
+        const { server, port } = await new Promise((resolve)=>{
+            const s = serve({
+                fetch: hono.fetch,
+                port: 0
+            }, (info)=>{
+                resolve({
+                    server: s,
+                    port: info.port
+                });
+            });
+        });
+        injectWebSocket(server);
+        // Never let the test server keep the process alive; the runtime reclaims it
+        // on exit. Tests don't need an explicit server teardown hook this way.
+        server.unref?.();
+        return {
+            port
+        };
+    })();
+    serversByModule.set(module, started);
+    return started;
+}
+async function openClient(url, headers) {
+    const headerEntries = [
+        ...headers.entries()
+    ];
+    // The standard WebSocket client cannot set arbitrary upgrade headers. When
+    // headers are needed (e.g. auth cookies), fall back to the `ws` package which
+    // supports them; otherwise use the runtime's global WebSocket.
+    if (headerEntries.length > 0) {
+        const wsSpecifier = 'ws';
+        try {
+            const wsModule = await import(wsSpecifier);
+            return new wsModule.default(url, undefined, {
+                headers: Object.fromEntries(headerEntries)
+            });
+        } catch  {
+        // `ws` not installed — proceed with the global client (headers dropped).
+        }
+    }
+    if (typeof WebSocket === 'undefined') {
+        throw new Error('[@velajs/testing/websocket-node] No global WebSocket. Use Node >=22 or ' + 'install the `ws` package.');
+    }
+    return new WebSocket(url);
+}
+registerWsConnector(async (module, path, headers)=>{
+    const { port } = await ensureServer(module);
+    const url = `ws://127.0.0.1:${port}${path}`;
+    const ws = await openClient(url, headers);
+    await new Promise((resolve, reject)=>{
+        const cleanup = ()=>{
+            ws.removeEventListener('open', onOpen);
+            ws.removeEventListener('error', onError);
+        };
+        const onOpen = ()=>{
+            cleanup();
+            resolve();
+        };
+        const onError = (event)=>{
+            cleanup();
+            reject(new Error(`WebSocket failed to open: ${String(event)}`));
+        };
+        ws.addEventListener('open', onOpen);
+        ws.addEventListener('error', onError);
+    });
+    return new TestWsConnection(ws);
+});

package/dist/ws/test-ws-connection.d.ts

@@ -0,0 +1,41 @@
+/**
+ * TestWsConnection
+ *
+ * Wraps a live `WebSocket` with queue-based wait/assert helpers. Transport is
+ * supplied by the caller — the core harness never opens a socket itself (see
+ * `@velajs/testing/websocket-node`).
+ *
+ * @example
+ * ```ts
+ * const ws = await module.ws('/ws/chat').connect();
+ * ws.send('hi');
+ * await ws.assertMessage('echo:hi');
+ * ws.close();
+ * ```
+ */
+export declare class TestWsConnection {
+    private readonly ws;
+    private readonly cleanup?;
+    private readonly messageQueue;
+    private messageWaiters;
+    private closeEvent;
+    private closeWaiters;
+    constructor(ws: WebSocket, cleanup?: (() => void | Promise<void>) | undefined);
+    /** The raw `WebSocket`. */
+    get raw(): WebSocket;
+    /** Send a message. */
+    send(data: string | ArrayBufferLike | ArrayBufferView): void;
+    /** Close the connection. */
+    close(code?: number, reason?: string): void;
+    /** Wait for the next message (rejects after `timeout` ms). */
+    waitForMessage(timeout?: number): Promise<string | ArrayBuffer>;
+    /** Wait for the connection to close (rejects after `timeout` ms). */
+    waitForClose(timeout?: number): Promise<{
+        code?: number;
+        reason?: string;
+    }>;
+    /** Assert the next message equals `expected`. */
+    assertMessage(expected: string, timeout?: number): Promise<void>;
+    /** Assert the connection closes, optionally with `expectedCode`. */
+    assertClosed(expectedCode?: number, timeout?: number): Promise<void>;
+}