@velajs/testing 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -1,10 +1,15 @@
 # Changelog
 
+## 0.5.1
+
+### Patch Changes
+
+- 647fd5f: Modernize the package build, validation, and release toolchain.
+
 ## 0.3.0 (2026-07-04)
 
 - `ComponentManager.init` call removed; provider overrides use the supported `Container.replaceProvider`; registers `DiscoveryService` mirroring bootstrap. Requires `@velajs/vela >=1.11.0`.
 
-
 ## 0.2.1 (2026-05-14)
 
 ### Fixes
@@ -25,7 +30,7 @@ Bugs fixed, rebuilt on `@velajs/vela/internal`, no more `reflect-metadata` dep.
 - **Provider override shape was wrong.** `overrideProvider(token).useValue(v)` constructed `{ token, useValue }` but vela's container reads `{ provide, useValue }`. The misleading `as ProviderOptions` cast hid this; nothing actually overrode. Fixed.
 - **`useClass` now uses the container's native `useClass` path** instead of the bogus `useFactory: () => new cls()` workaround. The previous comment claimed `Container.registerOptions` doesn't read `useClass` — it does (`vela/src/container/container.ts`).
 - **`loader.resolveAllInstances()` is now awaited.** Was called synchronously even though vela's signature is async; lifecycle hooks fired before instance resolution finished.
-- **APP_* token wiring uses vela's canonical `bindAppProviders` helper.** Replaces the five duplicated `useGlobalGuards/Pipes/Interceptors/Filters/Middleware(container.resolve(APP_*))` blocks that handled only the single-value case (vela switched to array form months ago). Now stays in lockstep with `VelaFactory.create` automatically.
+- **APP\_\* token wiring uses vela's canonical `bindAppProviders` helper.** Replaces the five duplicated `useGlobalGuards/Pipes/Interceptors/Filters/Middleware(container.resolve(APP_*))` blocks that handled only the single-value case (vela switched to array form months ago). Now stays in lockstep with `VelaFactory.create` automatically.
 
 ### Breaking changes
 

package/dist/index.d.ts

@@ -1,15 +1,484 @@
-export { Test } from './test.js';
-export { TestingModule } from './testing-module.js';
-export type { ActingAsResolver, TestPrincipal } from './testing-module.js';
-export { TestingModuleBuilder, OverrideBy } from './testing-module.builder.js';
-export { TestHttpClient } from './http/test-http-client.js';
-export { TestHttpRequest } from './http/test-http-request.js';
-export { TestResponse } from './http/test-response.js';
-export { getValueAtPath, hasValueAtPath } from './http/path-utils.js';
-export { TestSseConnection } from './sse/test-sse-connection.js';
-export type { TestSseEvent } from './sse/test-sse-connection.js';
-export { TestSseRequest } from './sse/test-sse-request.js';
-export { TestWsConnection } from './ws/test-ws-connection.js';
-export { TestWsRequest, registerWsConnector, getWsConnector } from './ws/test-ws-request.js';
-export type { WsConnector } from './ws/test-ws-request.js';
-export type { TestDatabase } from './db/test-database.js';
+import { ModuleOptions, Token, Type, VelaApplication } from "@velajs/vela";
+import { Container } from "@velajs/vela/internal";
+import { ISeeder } from "@velajs/vela/seeder";
+//#region src/db/test-database.d.ts
+/**
+ * TestDatabase
+ *
+ * A minimal driver contract for database assertions in tests. Vela has no ORM
+ * in core, so the harness ships only this interface plus thin assertion
+ * wrappers (`module.assertDatabaseHas/Missing/Count`). A consumer — or a future
+ * `@velajs/crud` driver — provides the concrete implementation; the harness
+ * never couples to a specific database library.
+ *
+ * @example
+ * ```ts
+ * class MyTestDb implements TestDatabase {
+ *   async truncate() { ... }
+ *   async has(table, where) { ... }
+ *   async count(table) { ... }
+ * }
+ * await module.assertDatabaseHas(new MyTestDb(), 'user', { email: 'a@b.com' });
+ * ```
+ */
+interface TestDatabase {
+  /** Remove all rows from every table (reset between tests). */
+  truncate(): Promise<void>;
+  /** Whether a row matching `where` exists in `table`. */
+  has(table: string, where: Record<string, unknown>): Promise<boolean>;
+  /** The number of rows in `table`. */
+  count(table: string): Promise<number>;
+}
+//#endregion
+//#region src/http/test-response.d.ts
+/**
+ * TestResponse
+ *
+ * Wraps a `Response` with fluent, chainable assertions. Synchronous status /
+ * header assertions return `this`; JSON assertions (which must read the body)
+ * return `Promise<this>`.
+ *
+ * @example
+ * ```ts
+ * const res = await module.http.get('/users/1').send();
+ * res.assertOk();
+ * await res.assertJsonPath('data.id', 1);
+ * ```
+ */
+declare class TestResponse {
+  private readonly response;
+  private jsonData;
+  private textData;
+  constructor(response: Response);
+  /** The raw `Response`. */
+  get raw(): Response;
+  /** The response status code. */
+  get status(): number;
+  /** The response headers. */
+  get headers(): Headers;
+  /** Parse (and cache) the response body as JSON. */
+  json<T = unknown>(): Promise<T>;
+  /** Read (and cache) the response body as text. */
+  text(): Promise<string>;
+  /** Assert status is 200 OK. */
+  assertOk(): this;
+  /** Assert status is 201 Created. */
+  assertCreated(): this;
+  /** Assert status is 204 No Content. */
+  assertNoContent(): this;
+  /** Assert status is 400 Bad Request. */
+  assertBadRequest(): this;
+  /** Assert status is 401 Unauthorized. */
+  assertUnauthorized(): this;
+  /** Assert status is 403 Forbidden. */
+  assertForbidden(): this;
+  /** Assert status is 404 Not Found. */
+  assertNotFound(): this;
+  /** Assert status is 422 Unprocessable Entity. */
+  assertUnprocessable(): this;
+  /** Assert status is 500 Internal Server Error. */
+  assertServerError(): this;
+  /** Assert the response has the given status code. */
+  assertStatus(expected: number): this;
+  /** Assert the status is in the 2xx range. */
+  assertSuccessful(): this;
+  /** Assert each key in `expected` equals the corresponding top-level value. */
+  assertJson(expected: Record<string, unknown>): Promise<this>;
+  /** Assert the value at a dot-notation path equals `expected`. */
+  assertJsonPath(path: string, expected: unknown): Promise<this>;
+  /** Assert every path/value pair in `expectations` matches (batch assert). */
+  assertJsonPaths(expectations: Record<string, unknown>): Promise<this>;
+  /** Assert the top-level JSON object has every key in `structure`. */
+  assertJsonStructure(structure: string[]): Promise<this>;
+  /** Assert a path exists (value may be anything, including `null`). */
+  assertJsonPathExists(path: string): Promise<this>;
+  /** Assert a path does not exist. */
+  assertJsonPathMissing(path: string): Promise<this>;
+  /** Assert the value at a path satisfies a predicate. */
+  assertJsonPathMatches(path: string, matcher: (value: unknown) => boolean): Promise<this>;
+  /** Assert the string value at a path contains `substring`. */
+  assertJsonPathContains(path: string, substring: string): Promise<this>;
+  /** Assert the array value at a path includes `item`. */
+  assertJsonPathIncludes(path: string, item: unknown): Promise<this>;
+  /** Assert the array value at a path has `count` items. */
+  assertJsonPathCount(path: string, count: number): Promise<this>;
+  /** Assert a header is present, optionally equal to `expected`. */
+  assertHeader(name: string, expected?: string): this;
+  /** Assert a header is absent. */
+  assertHeaderMissing(name: string): this;
+}
+//#endregion
+//#region src/http/test-http-request.d.ts
+/**
+ * TestHttpRequest
+ *
+ * Fluent builder for a single test HTTP request. `send()` builds a `Request`
+ * and drives it through `module.fetch()` (the full Hono pipeline).
+ *
+ * @example
+ * ```ts
+ * const res = await module.http
+ *   .post('/users')
+ *   .withBody({ name: 'A' })
+ *   .withHeaders({ 'X-Trace': '1' })
+ *   .send();
+ * res.assertCreated();
+ * ```
+ */
+declare class TestHttpRequest {
+  private readonly method;
+  private readonly path;
+  private readonly module;
+  private readonly host;
+  private body;
+  private readonly requestHeaders;
+  private principal;
+  private resolver;
+  constructor(method: string, path: string, headers: Headers, module: TestingModule, host?: string | null);
+  /** Set the request body (JSON-serialized on send). */
+  withBody(data: unknown): this;
+  /** Merge additional headers. */
+  withHeaders(headers: Record<string, string>): this;
+  /** Set `Content-Type: application/json`. */
+  asJson(): this;
+  /**
+   * Authenticate the request as `principal`. The `resolver` (or a default one
+   * registered via `module.setAuthResolver`) turns the principal into request
+   * headers. The resolver signature `(module, principal) => Promise<Headers>`
+   * is the cross-package contract sibling packages (e.g. `@velajs/better-auth`)
+   * build against.
+   */
+  actingAs(principal: TestPrincipal, resolver?: ActingAsResolver): this;
+  /** Build the `Request` and send it through `module.fetch()`. */
+  send(): Promise<TestResponse>;
+  private applyAuthentication;
+}
+//#endregion
+//#region src/http/test-http-client.d.ts
+/**
+ * TestHttpClient
+ *
+ * Fluent entry point for test HTTP requests. `forHost`/`withHeaders` return a
+ * new immutable client; the verb methods start a {@link TestHttpRequest}.
+ *
+ * @example
+ * ```ts
+ * const res = await module.http
+ *   .forHost('example.com')
+ *   .post('/users')
+ *   .withBody({ name: 'A' })
+ *   .send();
+ * res.assertCreated();
+ * ```
+ */
+declare class TestHttpClient {
+  private readonly module;
+  private readonly host;
+  private readonly defaultHeaders;
+  constructor(module: TestingModule, host?: string | null, defaultHeaders?: Headers);
+  /**
+   * Return a new client bound to `host`. Also sets the `Host` header so domain
+   * routing works even when the runtime reads the header rather than the URL.
+   */
+  forHost(host: string): TestHttpClient;
+  /** Return a new client with additional default headers on every request. */
+  withHeaders(headers: Record<string, string>): TestHttpClient;
+  get(path: string): TestHttpRequest;
+  post(path: string): TestHttpRequest;
+  put(path: string): TestHttpRequest;
+  patch(path: string): TestHttpRequest;
+  delete(path: string): TestHttpRequest;
+  private createRequest;
+}
+//#endregion
+//#region src/sse/test-sse-connection.d.ts
+/** A parsed Server-Sent Event. */
+interface TestSseEvent {
+  data: string;
+  event?: string;
+  id?: string;
+  retry?: number;
+}
+/**
+ * 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();
+ * ```
+ */
+declare class TestSseConnection {
+  private readonly response;
+  private readonly eventQueue;
+  private eventWaiters;
+  private streamEnded;
+  private endWaiters;
+  constructor(response: Response);
+  /** The raw `Response`. */
+  get raw(): Response;
+  /** Wait for the next event (rejects after `timeout` ms). */
+  waitForEvent(timeout?: number): Promise<TestSseEvent>;
+  /** Wait for the stream to end (rejects after `timeout` ms). */
+  waitForEnd(timeout?: number): Promise<void>;
+  /** Collect all remaining events until the stream ends. */
+  collectEvents(timeout?: number): Promise<TestSseEvent[]>;
+  /** Assert the next event matches the expected partial shape. */
+  assertEvent(expected: Partial<TestSseEvent>, timeout?: number): Promise<void>;
+  /** Assert the next event's `data` equals `expected`. */
+  assertEventData(expected: string, timeout?: number): Promise<void>;
+  /** Assert the next event's `data` is JSON equal to `expected`. */
+  assertJsonEventData<T>(expected: T, timeout?: number): Promise<void>;
+  private startReading;
+  private endStream;
+  private parseEvent;
+  private dispatchEvent;
+}
+//#endregion
+//#region src/sse/test-sse-request.d.ts
+/**
+ * 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' });
+ * ```
+ */
+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;
+}
+//#endregion
+//#region src/ws/test-ws-connection.d.ts
+/**
+ * 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();
+ * ```
+ */
+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>;
+}
+//#endregion
+//#region src/ws/test-ws-request.d.ts
+/**
+ * A transport adapter that performs the WebSocket upgrade and returns a live
+ * connection. Registered by a platform package (e.g. websocket-node).
+ */
+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`).
+ */
+declare function registerWsConnector(connector: WsConnector): void;
+/** The currently registered WebSocket connector, if any. */
+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');
+ * ```
+ */
+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;
+}
+//#endregion
+//#region src/testing-module.d.ts
+/** A test principal — an opaque object the auth resolver turns into headers. */
+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.
+ */
+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());
+ * ```
+ */
+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;
+}
+//#endregion
+//#region src/testing-module.builder.d.ts
+declare class OverrideBy {
+  private readonly builder;
+  private readonly token;
+  constructor(builder: TestingModuleBuilder, token: Token);
+  useValue(value: unknown): TestingModuleBuilder;
+  useClass(cls: Type): TestingModuleBuilder;
+  useFactory(options: {
+    factory: (...args: unknown[]) => unknown;
+    inject?: Token[];
+  }): TestingModuleBuilder;
+}
+declare class TestingModuleBuilder {
+  private readonly metadata;
+  private overrides;
+  constructor(metadata: ModuleOptions);
+  overrideProvider(token: Token): OverrideBy;
+  overrideGuard(guard: Type): OverrideBy;
+  overridePipe(pipe: Type): OverrideBy;
+  overrideInterceptor(interceptor: Type): OverrideBy;
+  overrideFilter(filter: Type): OverrideBy;
+  private addOverride;
+  compile(): Promise<TestingModule>;
+}
+//#endregion
+//#region src/test.d.ts
+declare const Test: {
+  createTestingModule(metadata: ModuleOptions): TestingModuleBuilder;
+};
+//#endregion
+//#region src/http/path-utils.d.ts
+/**
+ * Read the value at a dot-notation path (e.g. `data.user.id`).
+ * Returns `undefined` when any segment along the way is null/undefined.
+ */
+declare function getValueAtPath(obj: unknown, path: string): unknown;
+/**
+ * Whether a dot-notation path exists on the object, even when the value at the
+ * path is `null`/`undefined`. Distinguishes "key present but null" from "key
+ * absent".
+ */
+declare function hasValueAtPath(obj: unknown, path: string): boolean;
+//#endregion
+export { type ActingAsResolver, OverrideBy, Test, type TestDatabase, TestHttpClient, TestHttpRequest, type TestPrincipal, TestResponse, TestSseConnection, type TestSseEvent, TestSseRequest, TestWsConnection, TestWsRequest, TestingModule, TestingModuleBuilder, type WsConnector, getValueAtPath, getWsConnector, hasValueAtPath, registerWsConnector };
+//# sourceMappingURL=index.d.ts.map