@stratal/testing 0.0.13 → 0.0.14

package/dist/index.d.mts

@@ -0,0 +1,1070 @@
+import { Application, ApplicationConfig, 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, DefaultConnectionName } from "@stratal/framework/database";
+import { AuthService } from "@stratal/framework/auth";
+import { HttpResponse, RequestHandler, http } from "msw";
+
+//#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/types.d.ts
+declare abstract class Seeder<K extends ConnectionName = DefaultConnectionName> {
+  abstract run(db: DatabaseService<K>): Promise<void>;
+}
+//#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/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(new 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;
+  /**
+   * 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 in a database transaction
+   */
+  seed(...seeders: Seeder[]): Promise<void>;
+  seed(name: ConnectionName, ...seeders: 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, Seeder, type StoredFile, Test, TestError, TestHttpClient, TestHttpRequest, TestResponse, TestSetupError, TestSseConnection, type TestSseEvent, TestSseRequest, TestWsConnection, TestWsRequest, TestingModule, TestingModuleBuilder, type TestingModuleConfig, createMockFetch, getTestEnv, http };
+//# sourceMappingURL=index.d.mts.map