@stratal/testing 0.0.13 → 0.0.15

package/dist/index.d.mts

@@ -0,0 +1,1130 @@
+import { Application, ApplicationConfig, Constructor, StratalEnv } from "stratal";
+import { DynamicModule, InjectionToken, ModuleClass, ModuleOptions } from "stratal/module";
+import { DownloadResult, PresignedUrlResult, StorageConfig, StorageManagerService, StorageService, StreamingBlobPayloadInputTypes, UploadOptions, UploadResult } from "stratal/storage";
+import { Container } from "stratal/di";
+import { ConnectionName, DatabaseService } from "@stratal/framework/database";
+import { Seeder } from "stratal/seeder";
+import { AuthService } from "@stratal/framework/auth";
+import { HttpResponse, RequestHandler, http } from "msw";
+import { CommandInput, CommandResult } from "stratal/quarry";
+
+//#region src/storage/fake-storage.service.d.ts
+/**
+ * Stored file representation in memory
+ */
+interface StoredFile {
+  content: Uint8Array;
+  mimeType: string;
+  size: number;
+  metadata?: Record<string, string>;
+  uploadedAt: Date;
+}
+/**
+ * FakeStorageService
+ *
+ * In-memory storage implementation for testing.
+ * Registered by default in TestingModuleBuilder.
+ *
+ * Similar to Laravel's Storage::fake() - stores files in memory
+ * and provides assertion helpers for testing.
+ *
+ * @example
+ * ```typescript
+ * // Access via TestingModule
+ * module.storage.assertExists('path/to/file.pdf')
+ * module.storage.assertMissing('deleted/file.pdf')
+ * module.storage.clear() // Reset between tests
+ * ```
+ */
+declare class FakeStorageService extends StorageService {
+  protected readonly storageManager: StorageManagerService;
+  protected readonly options: StorageConfig;
+  private files;
+  constructor(storageManager: StorageManagerService, options: StorageConfig);
+  /**
+   * Upload content to fake storage
+   */
+  upload(body: StreamingBlobPayloadInputTypes, relativePath: string, options: UploadOptions, disk?: string): Promise<UploadResult>;
+  /**
+   * Download a file from fake storage
+   */
+  download(path: string): Promise<DownloadResult>;
+  /**
+   * Delete a file from fake storage
+   */
+  delete(path: string): Promise<void>;
+  /**
+   * Check if a file exists in fake storage
+   */
+  exists(path: string): Promise<boolean>;
+  /**
+   * Generate a fake presigned download URL
+   */
+  getPresignedDownloadUrl(path: string, expiresIn?: number): Promise<PresignedUrlResult>;
+  /**
+   * Generate a fake presigned upload URL
+   */
+  getPresignedUploadUrl(path: string, expiresIn?: number): Promise<PresignedUrlResult>;
+  /**
+   * Generate a fake presigned delete URL
+   */
+  getPresignedDeleteUrl(path: string, expiresIn?: number): Promise<PresignedUrlResult>;
+  /**
+   * Chunked upload (same as regular upload for fake)
+   */
+  chunkedUpload(body: StreamingBlobPayloadInputTypes, path: string, options: Omit<UploadOptions, 'size'> & {
+    size?: number;
+  }, disk?: string): Promise<UploadResult>;
+  /**
+   * Assert that a file exists at the given path
+   *
+   * @param path - Path to check
+   * @throws AssertionError if file does not exist
+   */
+  assertExists(path: string): void;
+  /**
+   * Assert that a file does NOT exist at the given path
+   *
+   * @param path - Path to check
+   * @throws AssertionError if file exists
+   */
+  assertMissing(path: string): void;
+  /**
+   * Assert storage is empty
+   *
+   * @throws AssertionError if any files exist
+   */
+  assertEmpty(): void;
+  /**
+   * Assert storage has exactly N files
+   *
+   * @param count - Expected number of files
+   * @throws AssertionError if count doesn't match
+   */
+  assertCount(count: number): void;
+  /**
+   * Get all stored files (for inspection)
+   */
+  getStoredFiles(): Map<string, StoredFile>;
+  /**
+   * Get all stored file paths
+   */
+  getStoredPaths(): string[];
+  /**
+   * Get a specific file by path
+   */
+  getFile(path: string): StoredFile | undefined;
+  /**
+   * Clear all stored files (call in beforeEach for test isolation)
+   */
+  clear(): void;
+  private createPresignedUrl;
+  private bodyToUint8Array;
+}
+//#endregion
+//#region src/core/http/test-response.d.ts
+/**
+ * TestResponse
+ *
+ * Wrapper around Response with assertion methods.
+ *
+ * @example
+ * ```typescript
+ * response
+ *   .assertOk()
+ *   .assertStatus(200)
+ *   .assertJsonPath('data.id', userId)
+ * ```
+ */
+declare class TestResponse {
+  private readonly response;
+  private jsonData;
+  private textData;
+  constructor(response: Response);
+  /**
+   * Get the raw Response object.
+   */
+  get raw(): Response;
+  /**
+   * Get the response status code.
+   */
+  get status(): number;
+  /**
+   * Get response headers.
+   */
+  get headers(): Headers;
+  /**
+   * Get the response body as JSON.
+   */
+  json<T = unknown>(): Promise<T>;
+  /**
+   * Get the response body as text.
+   */
+  text(): Promise<string>;
+  /**
+   * Assert response status is 200 OK.
+   */
+  assertOk(): this;
+  /**
+   * Assert response status is 201 Created.
+   */
+  assertCreated(): this;
+  /**
+   * Assert response status is 204 No Content.
+   */
+  assertNoContent(): this;
+  /**
+   * Assert response status is 400 Bad Request.
+   */
+  assertBadRequest(): this;
+  /**
+   * Assert response status is 401 Unauthorized.
+   */
+  assertUnauthorized(): this;
+  /**
+   * Assert response status is 403 Forbidden.
+   */
+  assertForbidden(): this;
+  /**
+   * Assert response status is 404 Not Found.
+   */
+  assertNotFound(): this;
+  /**
+   * Assert response status is 422 Unprocessable Entity.
+   */
+  assertUnprocessable(): this;
+  /**
+   * Assert response status is 500 Internal Server Error.
+   */
+  assertServerError(): this;
+  /**
+   * Assert response has the given status code.
+   */
+  assertStatus(expected: number): this;
+  /**
+   * Assert response status is in the 2xx success range.
+   */
+  assertSuccessful(): this;
+  /**
+   * Assert JSON response contains the given data.
+   */
+  assertJson(expected: Record<string, unknown>): Promise<this>;
+  /**
+   * Assert JSON response has value at the given path.
+   *
+   * @param path - Dot-notation path (e.g., 'data.user.id')
+   * @param expected - Expected value at path
+   */
+  assertJsonPath(path: string, expected: unknown): Promise<this>;
+  /**
+   * Assert JSON response structure matches the given schema.
+   */
+  assertJsonStructure(structure: string[]): Promise<this>;
+  /**
+   * Assert a JSON path exists (value can be anything, including null).
+   *
+   * @param path - Dot-notation path (e.g., 'data.user.id')
+   */
+  assertJsonPathExists(path: string): Promise<this>;
+  /**
+   * Assert a JSON path does not exist.
+   *
+   * @param path - Dot-notation path (e.g., 'data.user.deletedAt')
+   */
+  assertJsonPathMissing(path: string): Promise<this>;
+  /**
+   * Assert JSON value at path matches a custom predicate.
+   *
+   * @param path - Dot-notation path (e.g., 'data.items')
+   * @param matcher - Predicate function to validate the value
+   */
+  assertJsonPathMatches(path: string, matcher: (value: unknown) => boolean): Promise<this>;
+  /**
+   * Assert string value at path contains a substring.
+   *
+   * @param path - Dot-notation path (e.g., 'data.message')
+   * @param substring - Substring to search for
+   */
+  assertJsonPathContains(path: string, substring: string): Promise<this>;
+  /**
+   * Assert array value at path includes a specific item.
+   *
+   * @param path - Dot-notation path (e.g., 'data.tags')
+   * @param item - Item to search for in the array
+   */
+  assertJsonPathIncludes(path: string, item: unknown): Promise<this>;
+  /**
+   * Assert array length at path equals the expected count.
+   *
+   * @param path - Dot-notation path (e.g., 'data.items')
+   * @param count - Expected array length
+   */
+  assertJsonPathCount(path: string, count: number): Promise<this>;
+  /**
+   * Assert multiple JSON paths at once (batch assertion).
+   *
+   * @param expectations - Object mapping paths to expected values
+   */
+  assertJsonPaths(expectations: Record<string, unknown>): Promise<this>;
+  /**
+   * Assert response has the given header.
+   */
+  assertHeader(name: string, expected?: string): this;
+  /**
+   * Assert response does not have the given header.
+   */
+  assertHeaderMissing(name: string): this;
+  /**
+   * Get value at dot-notation path.
+   */
+  private getValueAtPath;
+  /**
+   * Check if a path exists in the object (even if value is null/undefined).
+   */
+  private hasValueAtPath;
+}
+//#endregion
+//#region src/core/http/test-http-request.d.ts
+/**
+ * TestHttpRequest
+ *
+ * Request builder with fluent API for configuring test HTTP requests.
+ *
+ * @example
+ * ```typescript
+ * const response = await module.http
+ *   .post('/api/v1/register')
+ *   .withBody({ name: 'Test School' })
+ *   .withHeaders({ 'X-Custom': 'value' })
+ *   .send()
+ * ```
+ *
+ * @example Authenticated request
+ * ```typescript
+ * const response = await module.http
+ *   .get('/api/v1/profile')
+ *   .actingAs({ id: user.id })
+ *   .send()
+ * ```
+ */
+declare class TestHttpRequest {
+  private readonly method;
+  private readonly path;
+  private readonly module;
+  private readonly host;
+  private body;
+  private requestHeaders;
+  private actingAsUser;
+  constructor(method: string, path: string, headers: Headers, module: TestingModule, host?: string | null);
+  /**
+   * Set the request body
+   */
+  withBody(data: unknown): this;
+  /**
+   * Add headers to the request
+   */
+  withHeaders(headers: Record<string, string>): this;
+  /**
+   * Set Content-Type to application/json
+   */
+  asJson(): this;
+  /**
+   * Authenticate the request as a specific user
+   */
+  actingAs(user: {
+    id: string;
+  }): this;
+  /**
+   * Send the request and return response
+   *
+   * Calls module.fetch() - NOT SELF.fetch()
+   */
+  send(): Promise<TestResponse>;
+  private applyAuthentication;
+}
+//#endregion
+//#region src/core/http/test-http-client.d.ts
+/**
+ * TestHttpClient
+ *
+ * Fluent HTTP client for making test requests.
+ *
+ * @example
+ * ```typescript
+ * const response = await module.http
+ *   .forHost('example.com')
+ *   .post('/api/v1/users')
+ *   .withBody({ name: 'Test' })
+ *   .send()
+ *
+ * response.assertCreated()
+ * ```
+ */
+declare class TestHttpClient {
+  private readonly module;
+  private defaultHeaders;
+  private host;
+  constructor(module: TestingModule);
+  /**
+   * Set the host for the request
+   */
+  forHost(host: string): this;
+  /**
+   * Set default headers for all requests
+   */
+  withHeaders(headers: Record<string, string>): this;
+  /**
+   * Create a GET request
+   */
+  get(path: string): TestHttpRequest;
+  /**
+   * Create a POST request
+   */
+  post(path: string): TestHttpRequest;
+  /**
+   * Create a PUT request
+   */
+  put(path: string): TestHttpRequest;
+  /**
+   * Create a PATCH request
+   */
+  patch(path: string): TestHttpRequest;
+  /**
+   * Create a DELETE request
+   */
+  delete(path: string): TestHttpRequest;
+  private createRequest;
+}
+//#endregion
+//#region src/core/quarry/test-command-result.d.ts
+/**
+ * Fluent assertion wrapper for command results.
+ *
+ * @example
+ * ```typescript
+ * const result = await module
+ *   .quarry('users:create')
+ *   .withInput({ email: 'test@example.com' })
+ *   .run()
+ *
+ * result.assertSuccessful()
+ * result.assertOutputContains('User created')
+ * ```
+ */
+declare class TestCommandResult {
+  private readonly result;
+  constructor(result: CommandResult);
+  get exitCode(): number;
+  get output(): string[];
+  get errors(): string[];
+  assertSuccessful(): this;
+  assertFailed(exitCode?: number): this;
+  assertExitCode(code: number): this;
+  assertOutputContains(text: string): this;
+  assertOutputMissing(text: string): this;
+  assertErrorContains(text: string): this;
+  assertErrorMissing(text: string): this;
+}
+//#endregion
+//#region src/core/quarry/test-command-request.d.ts
+/**
+ * Fluent builder for testing Quarry commands.
+ *
+ * @example
+ * ```typescript
+ * const result = await module
+ *   .quarry('users:create')
+ *   .withInput({ email: 'test@example.com', admin: true })
+ *   .run()
+ *
+ * result.assertSuccessful()
+ * result.assertOutputContains('User created')
+ * ```
+ */
+declare class TestCommandRequest {
+  private readonly commandName;
+  private readonly module;
+  private _input;
+  constructor(commandName: string, module: TestingModule);
+  /**
+   * Set the flat input for the command.
+   */
+  withInput(input: CommandInput): this;
+  /**
+   * Execute the command and return a TestCommandResult for assertions.
+   */
+  run(): Promise<TestCommandResult>;
+}
+//#endregion
+//#region src/core/sse/test-sse-connection.d.ts
+/**
+ * Represents a parsed SSE event
+ */
+interface TestSseEvent {
+  data: string;
+  event?: string;
+  id?: string;
+  retry?: number;
+}
+/**
+ * TestSseConnection
+ *
+ * Live SSE connection wrapper with assertion helpers for testing.
+ *
+ * @example
+ * ```typescript
+ * const sse = await module.sse('/streaming/sse').connect()
+ * await sse.assertEvent({ event: 'message', data: 'hello', id: '1' })
+ * await sse.waitForEnd()
+ * ```
+ */
+declare class TestSseConnection {
+  private readonly response;
+  private readonly eventQueue;
+  private eventWaiters;
+  private streamEnded;
+  private endWaiters;
+  constructor(response: Response);
+  /**
+   * Wait for the next SSE event
+   */
+  waitForEvent(timeout?: number): Promise<TestSseEvent>;
+  /**
+   * Wait for the stream to end
+   */
+  waitForEnd(timeout?: number): Promise<void>;
+  /**
+   * Collect all remaining events until the stream ends
+   */
+  collectEvents(timeout?: number): Promise<TestSseEvent[]>;
+  /**
+   * Assert that the next event matches the expected partial shape
+   */
+  assertEvent(expected: Partial<TestSseEvent>, timeout?: number): Promise<void>;
+  /**
+   * Assert that the next event's data matches the expected string
+   */
+  assertEventData(expected: string, timeout?: number): Promise<void>;
+  /**
+   * Assert that the next event's data is JSON matching the expected value
+   */
+  assertJsonEventData<T>(expected: T, timeout?: number): Promise<void>;
+  /**
+   * Access the raw Response
+   */
+  get raw(): Response;
+  private startReading;
+  private parseEvent;
+  private dispatchEvent;
+}
+//#endregion
+//#region src/core/sse/test-sse-request.d.ts
+/**
+ * TestSseRequest
+ *
+ * Builder for SSE connection requests. Follows the TestWsRequest pattern.
+ *
+ * @example
+ * ```typescript
+ * const sse = await module.sse('/streaming/sse').connect()
+ * await sse.assertEvent({ event: 'message', data: 'hello' })
+ * await sse.waitForEnd()
+ * ```
+ *
+ * @example Authenticated SSE
+ * ```typescript
+ * const sse = await module.sse('/streaming/sse').actingAs({ id: user.id }).connect()
+ * ```
+ */
+declare class TestSseRequest {
+  private readonly path;
+  private readonly module;
+  private requestHeaders;
+  private actingAsUser;
+  constructor(path: string, module: TestingModule);
+  /**
+   * Add custom headers to the request
+   */
+  withHeaders(headers: Record<string, string>): this;
+  /**
+   * Authenticate the SSE connection as a specific user
+   */
+  actingAs(user: {
+    id: string;
+  }): this;
+  /**
+   * Send the request and return a live SSE connection
+   */
+  connect(): Promise<TestSseConnection>;
+  private applyAuthentication;
+}
+//#endregion
+//#region src/core/ws/test-ws-connection.d.ts
+/**
+ * TestWsConnection
+ *
+ * Live WebSocket connection wrapper with assertion helpers for testing.
+ *
+ * @example
+ * ```typescript
+ * const ws = await module.ws('/ws/chat').connect()
+ * ws.send('hello')
+ * await ws.assertMessage('echo:hello')
+ * ws.close()
+ * await ws.waitForClose()
+ * ```
+ */
+declare class TestWsConnection {
+  private readonly ws;
+  private readonly messageQueue;
+  private messageWaiters;
+  private closeEvent;
+  private closeWaiters;
+  constructor(ws: WebSocket);
+  /**
+   * Send a message through the WebSocket
+   */
+  send(data: string | ArrayBuffer | Uint8Array): void;
+  /**
+   * Close the WebSocket connection
+   */
+  close(code?: number, reason?: string): void;
+  /**
+   * Wait for the next message, returning its data
+   */
+  waitForMessage(timeout?: number): Promise<string | ArrayBuffer>;
+  /**
+   * Wait for the connection to close
+   */
+  waitForClose(timeout?: number): Promise<{
+    code?: number;
+    reason?: string;
+  }>;
+  /**
+   * Assert that the next message equals the expected value
+   */
+  assertMessage(expected: string, timeout?: number): Promise<void>;
+  /**
+   * Assert that the connection closes, optionally with an expected code
+   */
+  assertClosed(expectedCode?: number, timeout?: number): Promise<void>;
+  /**
+   * Access the raw Cloudflare WebSocket
+   */
+  get raw(): WebSocket;
+}
+//#endregion
+//#region src/core/ws/test-ws-request.d.ts
+/**
+ * TestWsRequest
+ *
+ * Builder for WebSocket upgrade requests. Follows the TestHttpRequest pattern.
+ *
+ * @example
+ * ```typescript
+ * const ws = await module.ws('/ws/chat').connect()
+ * ws.send('hello')
+ * await ws.assertMessage('echo:hello')
+ * ws.close()
+ * ```
+ *
+ * @example Authenticated WebSocket
+ * ```typescript
+ * const ws = await module.ws('/ws/chat').actingAs({ id: user.id }).connect()
+ * ```
+ */
+declare class TestWsRequest {
+  private readonly path;
+  private readonly module;
+  private requestHeaders;
+  private actingAsUser;
+  constructor(path: string, module: TestingModule);
+  /**
+   * Add custom headers to the upgrade request
+   */
+  withHeaders(headers: Record<string, string>): this;
+  /**
+   * Authenticate the WebSocket connection as a specific user
+   */
+  actingAs(user: {
+    id: string;
+  }): this;
+  /**
+   * Send the upgrade request and return a live WebSocket connection
+   */
+  connect(): Promise<TestWsConnection>;
+  private applyAuthentication;
+}
+//#endregion
+//#region src/core/testing-module.d.ts
+/**
+ * TestingModule
+ *
+ * Provides access to the test application, container, HTTP client, and utilities.
+ *
+ * @example
+ * ```typescript
+ * const module = await Test.createTestingModule({
+ *   modules: [RegistrationModule],
+ * }).compile()
+ *
+ * // Make HTTP requests
+ * const response = await module.http
+ *   .post('/api/v1/register')
+ *   .withBody({ ... })
+ *   .send()
+ *
+ * // Access services
+ * const service = module.get(REGISTRATION_TOKENS.RegistrationService)
+ *
+ * // Database utilities
+ * await module.truncateDb()
+ * await module.seed(UserSeeder)
+ * await module.assertDatabaseHas('user', { email: 'test@example.com' })
+ *
+ * // Cleanup
+ * await module.close()
+ * ```
+ */
+declare class TestingModule {
+  private readonly app;
+  private readonly env;
+  private readonly ctx;
+  private _http;
+  private readonly _requestContainer;
+  constructor(app: Application, env: StratalEnv, ctx: ExecutionContext);
+  /**
+   * Resolve a service from the container
+   */
+  get<T>(token: InjectionToken<T>): T;
+  /**
+   * Get HTTP test client for making requests
+   */
+  get http(): TestHttpClient;
+  /**
+   * Get fake storage service for assertions
+   */
+  get storage(): FakeStorageService;
+  /**
+   * Create a WebSocket test request builder for the given path
+   */
+  ws(path: string): TestWsRequest;
+  /**
+   * Create an SSE test request builder for the given path
+   */
+  sse(path: string): TestSseRequest;
+  /**
+   * Create a Quarry command test request builder
+   */
+  quarry(name: string): TestCommandRequest;
+  /**
+   * Get Application instance
+   */
+  get application(): Application;
+  /**
+   * Get DI Container (request-scoped)
+   */
+  get container(): Container;
+  /**
+   * Execute an HTTP request through HonoApp
+   */
+  fetch(request: Request): Promise<Response>;
+  /**
+   * Run callback in request scope (for DB operations, service access)
+   */
+  runInRequestScope<T>(callback: (container: Container) => T | Promise<T>): Promise<T>;
+  /**
+   * Get database service instance (resolved in request scope)
+   */
+  getDb(): DatabaseService;
+  getDb<K extends ConnectionName>(name: K): DatabaseService<K>;
+  /**
+   * Truncate all non-prisma tables in the database
+   */
+  truncateDb(name?: ConnectionName): Promise<void>;
+  /**
+   * Run seeders by class constructor in the request-scoped container
+   */
+  seed(...SeederClasses: Constructor<Seeder>[]): Promise<void>;
+  /**
+   * Assert that a record exists in the database
+   */
+  assertDatabaseHas(table: string, data: Record<string, unknown>, name?: ConnectionName): Promise<void>;
+  /**
+   * Assert that a record does not exist in the database
+   */
+  assertDatabaseMissing(table: string, data: Record<string, unknown>, name?: ConnectionName): Promise<void>;
+  /**
+   * Assert the number of records in a table
+   */
+  assertDatabaseCount(table: string, expected: number, name?: ConnectionName): Promise<void>;
+  /**
+   * Cleanup - call in afterAll
+   */
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/core/testing-module-builder.d.ts
+/**
+ * Configuration for creating a testing module
+ *
+ * Extends ModuleOptions to support all module properties like NestJS.
+ *
+ * @example
+ * ```typescript
+ * const module = await Test.createTestingModule({
+ *   imports: [RegistrationModule, GeoModule],
+ *   providers: [{ provide: MOCK_TOKEN, useValue: mockValue }],
+ *   controllers: [TestController],
+ * }).compile()
+ * ```
+ */
+interface TestingModuleConfig extends ModuleOptions {
+  /** Optional environment overrides */
+  env?: Partial<StratalEnv>;
+  /** Logging configuration. Defaults: level=ERROR, formatter='json' */
+  logging?: ApplicationConfig['logging'];
+}
+/**
+ * Builder for creating test modules with provider overrides
+ */
+declare class TestingModuleBuilder {
+  private config;
+  private overrides;
+  constructor(config: TestingModuleConfig);
+  /**
+   * Override a provider with a custom implementation
+   */
+  overrideProvider<T>(token: InjectionToken<T>): ProviderOverrideBuilder<T>;
+  /**
+   * Add a provider override (internal use by ProviderOverrideBuilder)
+   *
+   * @internal
+   */
+  addProviderOverride<T>(override: ProviderOverrideConfig<T>): this;
+  /**
+   * Merge additional environment bindings
+   */
+  withEnv(env: Partial<StratalEnv>): this;
+  /**
+   * Compile the testing module
+   *
+   * Creates the Application, applies overrides, initializes, and returns TestingModule.
+   */
+  compile(): Promise<TestingModule>;
+  /**
+   * Create a test root module with the given options
+   */
+  private createTestRootModule;
+}
+//#endregion
+//#region src/core/override/provider-override-builder.d.ts
+/**
+ * Provider override configuration
+ */
+interface ProviderOverrideConfig<T = unknown> {
+  token: InjectionToken<T>;
+  type: 'value' | 'class' | 'factory' | 'existing';
+  implementation: T | (new (...args: unknown[]) => T) | ((container: Container) => T) | InjectionToken<T>;
+}
+/**
+ * Fluent builder for provider overrides
+ *
+ * Provides a NestJS-style API for overriding providers in tests.
+ *
+ * @example
+ * ```typescript
+ * const module = await Test.createTestingModule({
+ *   imports: [RegistrationModule],
+ * })
+ *   .overrideProvider(EMAIL_TOKENS.EmailService)
+ *   .useValue(mockEmailService)
+ *   .compile()
+ * ```
+ */
+declare class ProviderOverrideBuilder<T> {
+  private readonly parent;
+  private readonly token;
+  constructor(parent: TestingModuleBuilder, token: InjectionToken<T>);
+  /**
+   * Use a static value as the provider
+   *
+   * The value will be registered directly in the container.
+   *
+   * @param value - The value to use as the provider
+   * @returns The parent TestingModuleBuilder for chaining
+   */
+  useValue(value: T): TestingModuleBuilder;
+  /**
+   * Use a class as the provider
+   *
+   * The class will be registered as a singleton.
+   *
+   * @param cls - The class constructor to use as the provider
+   * @returns The parent TestingModuleBuilder for chaining
+   */
+  useClass(cls: new (...args: unknown[]) => T): TestingModuleBuilder;
+  /**
+   * Use a factory function as the provider
+   *
+   * The factory receives the container and should return the provider instance.
+   *
+   * @param factory - Factory function that creates the provider
+   * @returns The parent TestingModuleBuilder for chaining
+   */
+  useFactory(factory: (container: Container) => T): TestingModuleBuilder;
+  /**
+   * Use an existing token as the provider (alias)
+   *
+   * The override token will resolve to the same instance as the target token.
+   *
+   * @param existingToken - The token to alias
+   * @returns The parent TestingModuleBuilder for chaining
+   *
+   * @example
+   * ```typescript
+   * const module = await Test.createTestingModule({
+   *   imports: [MyModule],
+   * })
+   *   .overrideProvider(ABSTRACT_TOKEN)
+   *   .useExisting(ConcreteService)
+   *   .compile()
+   * ```
+   */
+  useExisting(existingToken: InjectionToken<T>): TestingModuleBuilder;
+}
+//#endregion
+//#region src/core/test.d.ts
+/**
+ * Test
+ *
+ * Static class for creating testing modules.
+ * Provides a NestJS-style API for configuring test modules.
+ *
+ * @example
+ * ```typescript
+ * // In vitest.setup.ts:
+ * Test.setBaseModules([CoreModule])
+ *
+ * // In test files:
+ * const module = await Test.createTestingModule({
+ *   imports: [RegistrationModule, GeoModule],
+ * })
+ *   .overrideProvider(EMAIL_TOKENS.EmailService)
+ *   .useValue(mockEmailService)
+ *   .compile()
+ * ```
+ */
+declare class Test {
+  /**
+   * Base modules to include in all test modules
+   * Set once in vitest.setup.ts
+   */
+  private static baseModules;
+  /**
+   * Set base modules to include in all test modules
+   * Should be called once in vitest.setup.ts
+   *
+   * @param modules - Modules to include before test-specific modules (e.g., CoreModule)
+   */
+  static setBaseModules(modules: (ModuleClass | DynamicModule)[]): void;
+  /**
+   * Get base modules
+   */
+  static getBaseModules(): (ModuleClass | DynamicModule)[];
+  /**
+   * Create a testing module builder
+   *
+   * @param config - Configuration with modules and optional env overrides
+   * @returns TestingModuleBuilder for configuring and compiling the module
+   */
+  static createTestingModule(config: TestingModuleConfig): TestingModuleBuilder;
+}
+//#endregion
+//#region src/core/http/fetch-mock.types.d.ts
+/**
+ * Options for mocking JSON responses
+ */
+interface MockJsonOptions {
+  /**
+   * HTTP status code for the response
+   * @default 200
+   */
+  status?: number;
+  /**
+   * Custom headers to include in the response
+   */
+  headers?: Record<string, string>;
+  /**
+   * Delay in milliseconds before responding
+   */
+  delay?: number;
+  /**
+   * HTTP method to match (GET, POST, PUT, PATCH, DELETE, etc.)
+   * @default 'GET'
+   */
+  method?: string;
+  /**
+   * Specific path to override URL pathname
+   * If not provided, the pathname from the URL will be used
+   */
+  path?: string;
+}
+/**
+ * Options for mocking error responses
+ */
+interface MockErrorOptions {
+  /**
+   * Custom headers to include in the error response
+   */
+  headers?: Record<string, string>;
+  /**
+   * HTTP method to match (GET, POST, PUT, PATCH, DELETE, etc.)
+   * @default 'GET'
+   */
+  method?: string;
+  /**
+   * Specific path to override URL pathname
+   * If not provided, the pathname from the URL will be used
+   */
+  path?: string;
+}
+//#endregion
+//#region src/core/http/mock-fetch.d.ts
+/**
+ * MSW-based fetch mock for declarative HTTP mocking in tests.
+ *
+ * Replaces the old Cloudflare `fetchMock` (undici MockAgent) with MSW's `setupServer`.
+ * Works in both Node.js and workerd test environments.
+ *
+ * @example
+ * ```typescript
+ * import { createMockFetch } from '@stratal/testing'
+ *
+ * const mock = createMockFetch()
+ *
+ * beforeAll(() => mock.listen())
+ * afterEach(() => mock.reset())
+ * afterAll(() => mock.close())
+ *
+ * it('should mock external API', async () => {
+ *   mock.mockJsonResponse('https://api.example.com/data', { success: true })
+ *
+ *   const response = await fetch('https://api.example.com/data')
+ *   const json = await response.json()
+ *
+ *   expect(json.success).toBe(true)
+ * })
+ * ```
+ */
+declare class MockFetch {
+  private server;
+  constructor(handlers?: RequestHandler[]);
+  /** Start intercepting. Call in beforeAll/beforeEach. */
+  listen(): void;
+  /** Reset runtime handlers. Call in afterEach. */
+  reset(): void;
+  /** Stop intercepting. Call in afterAll. */
+  close(): void;
+  /** Add runtime handler(s) for a single test. */
+  use(...handlers: RequestHandler[]): void;
+  /**
+   * Mock a JSON response.
+   *
+   * @param url - Full URL to mock (e.g., 'https://api.example.com/users')
+   * @param data - JSON data to return
+   * @param options - HTTP method, status code, headers
+   *
+   * @example
+   * ```typescript
+   * mock.mockJsonResponse('https://api.example.com/users', { users: [] })
+   * mock.mockJsonResponse('https://api.example.com/users', { created: true }, { method: 'POST', status: 201 })
+   * ```
+   */
+  mockJsonResponse(url: string, data: Record<string, unknown> | unknown[], options?: MockJsonOptions): void;
+  /**
+   * Mock an error response.
+   *
+   * @param url - Full URL to mock
+   * @param status - HTTP error status code
+   * @param message - Optional error message
+   * @param options - HTTP method, headers
+   *
+   * @example
+   * ```typescript
+   * mock.mockError('https://api.example.com/fail', 401, 'Unauthorized')
+   * mock.mockError('https://api.example.com/fail', 500, 'Server Error', { method: 'POST' })
+   * ```
+   */
+  mockError(url: string, status: number, message?: string, options?: MockErrorOptions): void;
+}
+/**
+ * Factory function to create a new MockFetch instance
+ *
+ * @param handlers - Optional initial MSW request handlers
+ * @returns A new MockFetch instance
+ *
+ * @example
+ * ```typescript
+ * import { createMockFetch } from '@stratal/testing'
+ *
+ * const mock = createMockFetch()
+ *
+ * beforeAll(() => mock.listen())
+ * afterEach(() => mock.reset())
+ * afterAll(() => mock.close())
+ * ```
+ */
+declare function createMockFetch(handlers?: RequestHandler[]): MockFetch;
+//#endregion
+//#region src/auth/acting-as.d.ts
+/**
+ * ActingAs
+ *
+ * Creates authentication sessions for testing.
+ * Uses Better Auth's internalAdapter to create real database sessions.
+ *
+ * @example
+ * ```typescript
+ * const actingAs = new ActingAs(authService)
+ * const headers = await actingAs.createSessionForUser({ id: 'user-123' })
+ * ```
+ */
+declare class ActingAs {
+  private readonly authService;
+  constructor(authService: AuthService);
+  createSessionForUser(user: {
+    id: string;
+  }): Promise<Headers>;
+}
+//#endregion
+//#region src/core/env/test-env.d.ts
+/**
+ * Get test environment with optional overrides
+ *
+ * @param overrides - Optional partial env to merge with cloudflare:test env
+ * @returns Complete Env object for testing
+ */
+declare function getTestEnv(overrides?: Partial<StratalEnv>): StratalEnv;
+//#endregion
+//#region src/errors/test-error.d.ts
+/**
+ * Base error class for all test framework errors.
+ * Extends from Error and allows easy identification via `instanceof`.
+ */
+declare class TestError extends Error {
+  readonly cause?: Error | undefined;
+  constructor(message: string, cause?: Error | undefined);
+}
+//#endregion
+//#region src/errors/setup-error.d.ts
+/**
+ * Error thrown when test setup fails.
+ * Examples: schema creation failure, migration failure, application bootstrap failure.
+ */
+declare class TestSetupError extends TestError {
+  constructor(message: string, cause?: Error);
+}
+//#endregion
+export { ActingAs, FakeStorageService, HttpResponse, type MockErrorOptions, MockFetch, type MockJsonOptions, ProviderOverrideBuilder, type ProviderOverrideConfig, type StoredFile, Test, TestCommandRequest, TestCommandResult, TestError, TestHttpClient, TestHttpRequest, TestResponse, TestSetupError, TestSseConnection, type TestSseEvent, TestSseRequest, TestWsConnection, TestWsRequest, TestingModule, TestingModuleBuilder, type TestingModuleConfig, createMockFetch, getTestEnv, http };
+//# sourceMappingURL=index.d.mts.map