@velajs/testing 0.4.0 → 0.5.0

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.4.0",
+  "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,7 +21,9 @@
     "LICENSE",
     "CHANGELOG.md"
   ],
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/websocket-node/index.js"
+  ],
   "keywords": [
     "vela",
     "testing",
@@ -42,7 +48,18 @@
   },
   "peerDependencies": {
     "@velajs/vela": ">=1.11.0",
-    "hono": ">=4"
+    "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.1",