@velajs/testing 0.2.1 → 0.5.0

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>;
+}

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

@@ -0,0 +1,105 @@
+// Ported from @stratal/testing (MIT, © Temitayo Fadojutimi). Web-standard
+// `WebSocket` wrapper; the optional `cleanup` hook lets a transport adapter
+// (e.g. websocket-node) tear down its server when the socket closes.
+import { expect } from "vitest";
+/**
+ * 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 class TestWsConnection {
+    ws;
+    cleanup;
+    messageQueue = [];
+    messageWaiters = [];
+    closeEvent = null;
+    closeWaiters = [];
+    constructor(ws, cleanup){
+        this.ws = ws;
+        this.cleanup = cleanup;
+        this.ws.addEventListener('message', (event)=>{
+            const data = event.data;
+            if (this.messageWaiters.length > 0) {
+                this.messageWaiters.shift()(data);
+            } else {
+                this.messageQueue.push(data);
+            }
+        });
+        this.ws.addEventListener('close', (event)=>{
+            this.closeEvent = {
+                code: event.code,
+                reason: event.reason
+            };
+            for (const waiter of this.closeWaiters){
+                waiter(this.closeEvent);
+            }
+            this.closeWaiters = [];
+            void this.cleanup?.();
+        });
+    }
+    /** The raw `WebSocket`. */ get raw() {
+        return this.ws;
+    }
+    /** Send a message. */ send(data) {
+        // The runtime WebSocket.send accepts all of these; the cast bridges the
+        // slight type differences between DOM/undici and Bun's WebSocket typings.
+        this.ws.send(data);
+    }
+    /** Close the connection. */ close(code, reason) {
+        this.ws.close(code, reason);
+    }
+    /** Wait for the next message (rejects after `timeout` ms). */ async waitForMessage(timeout = 5000) {
+        if (this.messageQueue.length > 0) {
+            return this.messageQueue.shift();
+        }
+        return new Promise((resolve, reject)=>{
+            const waiter = (data)=>{
+                clearTimeout(timer);
+                resolve(data);
+            };
+            const timer = setTimeout(()=>{
+                const index = this.messageWaiters.indexOf(waiter);
+                if (index !== -1) this.messageWaiters.splice(index, 1);
+                reject(new Error(`WebSocket: no message received within ${timeout}ms`));
+            }, timeout);
+            this.messageWaiters.push(waiter);
+        });
+    }
+    /** Wait for the connection to close (rejects after `timeout` ms). */ async waitForClose(timeout = 5000) {
+        if (this.closeEvent) {
+            return this.closeEvent;
+        }
+        return new Promise((resolve, reject)=>{
+            const waiter = (event)=>{
+                clearTimeout(timer);
+                resolve(event);
+            };
+            const timer = setTimeout(()=>{
+                const index = this.closeWaiters.indexOf(waiter);
+                if (index !== -1) this.closeWaiters.splice(index, 1);
+                reject(new Error(`WebSocket: connection did not close within ${timeout}ms`));
+            }, timeout);
+            this.closeWaiters.push(waiter);
+        });
+    }
+    /** Assert the next message equals `expected`. */ async assertMessage(expected, timeout = 5000) {
+        const data = await this.waitForMessage(timeout);
+        const message = typeof data === 'string' ? data : '[ArrayBuffer]';
+        expect(message, `Expected WebSocket message "${expected}", got "${message}"`).toBe(expected);
+    }
+    /** Assert the connection closes, optionally with `expectedCode`. */ async assertClosed(expectedCode, timeout = 5000) {
+        const event = await this.waitForClose(timeout);
+        if (expectedCode !== undefined) {
+            expect(event.code, `Expected close code ${expectedCode}, got ${event.code}`).toBe(expectedCode);
+        }
+    }
+}

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

@@ -0,0 +1,43 @@
+import type { ActingAsResolver, TestPrincipal, TestingModule } from '../testing-module.js';
+import type { TestWsConnection } from './test-ws-connection.js';
+/**
+ * A transport adapter that performs the WebSocket upgrade and returns a live
+ * connection. Registered by a platform package (e.g. websocket-node).
+ */
+export type WsConnector = (module: TestingModule, path: string, headers: Headers) => Promise<TestWsConnection>;
+/**
+ * Register the transport that {@link TestWsRequest.connect} uses. Called by a
+ * platform adapter's side-effect import (e.g. `@velajs/testing/websocket-node`).
+ */
+export declare function registerWsConnector(connector: WsConnector): void;
+/** The currently registered WebSocket connector, if any. */
+export declare function getWsConnector(): WsConnector | null;
+/**
+ * TestWsRequest
+ *
+ * Builder for a WebSocket connection. `connect()` requires a transport adapter
+ * to be registered; without one it throws a clear, actionable error.
+ *
+ * @example
+ * ```ts
+ * import '@velajs/testing/websocket-node';
+ * const ws = await module.ws('/ws/chat').connect();
+ * ws.send('hi');
+ * await ws.assertMessage('echo:hi');
+ * ```
+ */
+export declare class TestWsRequest {
+    private readonly path;
+    private readonly module;
+    private readonly requestHeaders;
+    private principal;
+    private resolver;
+    constructor(path: string, module: TestingModule);
+    /** Merge additional headers onto the upgrade request. */
+    withHeaders(headers: Record<string, string>): this;
+    /** Authenticate the connection (see {@link TestHttpRequest.actingAs}). */
+    actingAs(principal: TestPrincipal, resolver?: ActingAsResolver): this;
+    /** Open the socket via the registered transport adapter. */
+    connect(): Promise<TestWsConnection>;
+    private applyAuthentication;
+}

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

@@ -0,0 +1,69 @@
+// Adapted from @stratal/testing (MIT, © Temitayo Fadojutimi). Vela's WebSocket
+// transport is pluggable and NOT reachable through a plain in-memory fetch, so
+// the actual upgrade is delegated to a registered connector — provided by
+// `@velajs/testing/websocket-node` for Node. The core harness never promises a
+// universal `connect()`.
+let registeredConnector = null;
+/**
+ * Register the transport that {@link TestWsRequest.connect} uses. Called by a
+ * platform adapter's side-effect import (e.g. `@velajs/testing/websocket-node`).
+ */ export function registerWsConnector(connector) {
+    registeredConnector = connector;
+}
+/** The currently registered WebSocket connector, if any. */ export function getWsConnector() {
+    return registeredConnector;
+}
+/**
+ * TestWsRequest
+ *
+ * Builder for a WebSocket connection. `connect()` requires a transport adapter
+ * to be registered; without one it throws a clear, actionable error.
+ *
+ * @example
+ * ```ts
+ * import '@velajs/testing/websocket-node';
+ * const ws = await module.ws('/ws/chat').connect();
+ * ws.send('hi');
+ * await ws.assertMessage('echo:hi');
+ * ```
+ */ export class TestWsRequest {
+    path;
+    module;
+    requestHeaders = new Headers();
+    principal = null;
+    resolver = null;
+    constructor(path, module){
+        this.path = path;
+        this.module = module;
+    }
+    /** Merge additional headers onto the upgrade 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 socket via the registered transport adapter. */ async connect() {
+        const connector = getWsConnector();
+        if (!connector) {
+            throw new Error('WebSocket connect() requires a transport adapter. Import ' + '"@velajs/testing/websocket-node" (Node). Cloudflare Durable-Object ' + 'WebSockets are exercised via @velajs/cloudflare + the workerd pool, ' + 'not the core harness.');
+        }
+        await this.applyAuthentication();
+        return connector(this.module, this.path, this.requestHeaders);
+    }
+    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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/testing",
-  "version": "0.2.1",
+  "version": "0.5.0",
   "description": "Testing utilities for Vela framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,6 +9,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./websocket-node": {
+      "types": "./dist/websocket-node/index.d.ts",
+      "import": "./dist/websocket-node/index.js"
     }
   },
   "files": [
@@ -17,13 +21,9 @@
     "LICENSE",
     "CHANGELOG.md"
   ],
-  "scripts": {
-    "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "pnpm run typecheck && pnpm test"
-  },
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/websocket-node/index.js"
+  ],
   "keywords": [
     "vela",
     "testing",
@@ -47,24 +47,33 @@
     "node": ">=20"
   },
   "peerDependencies": {
-    "@velajs/vela": ">=1.6.0",
-    "hono": ">=4"
+    "@velajs/vela": ">=1.11.0",
+    "hono": ">=4",
+    "vitest": ">=3",
+    "@hono/node-ws": ">=1",
+    "@hono/node-server": ">=1"
+  },
+  "peerDependenciesMeta": {
+    "@hono/node-ws": {
+      "optional": true
+    },
+    "@hono/node-server": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@swc/cli": "^0.8.0",
-    "@swc/core": "^1.15.11",
+    "@swc/cli": "^0.8.1",
+    "@swc/core": "^1.15.41",
     "@types/bun": "latest",
-    "@velajs/vela": "^1.6.0",
-    "hono": "^4",
-    "typescript": "^5",
+    "@velajs/vela": "^1.12.0",
+    "hono": "^4.12.26",
+    "typescript": "^6.0.3",
     "unplugin-swc": "^1.5.9",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.9"
   },
-  "packageManager": "pnpm@10.20.0",
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "@swc/core",
-      "esbuild"
-    ]
+  "scripts": {
+    "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
-}
+}