@znight/testing 0.0.0-stage → 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,697 @@
+import { Application, ClassKey, Container, CoreLogger, DependencyRef, ExternalDefinition, MethodInterception, Plugin, ProviderClass, ProviderDefinition, ProviderFactory, ProviderKey, ProviderValues, Scope, ShutdownOptions, SourceLocation, Token, TypedToken, ZnightExtensionsMetadata, ZnightMetadata } from "@znight/core";
+/** Property values of one configuration class (`{ port: 8080 }`). */
+type ConfigProperties = Readonly<Record<string, unknown>>;
+/**
+ * Configuration values by configuration class, for `TestBed.create(..., { config })`: a record keyed
+ * by token, display name or `@Config` prefix, or `[ConfigClass, values]` pairs.
+ *
+ * ```ts
+ * config: { DatabaseConfig: { host: 'db.test' } }
+ * config: { database: { host: 'db.test' } } // @Config('database')
+ * config: [[DatabaseConfig, { host: 'db.test' }]]
+ * ```
+ */
+type ConfigValues = Iterable<readonly [ProviderKey, ConfigProperties]> | Readonly<Record<string, ConfigProperties>>;
+/**
+ * Public types of the mocks created by `@znight/testing`. They describe the Jest-compatible API
+ * shared by the built-in spy, `vi.fn()` (Vitest), `jest.fn()` (Jest) and `mock()` (`bun:test`).
+ */
+/** Any function. Every function type is assignable to it (parameters are contravariant). */
+type AnyFunction = (...args: never[]) => unknown;
+/**
+ * Signature of an untyped mock function: accepts any arguments and returns anything.
+ */
+type UntypedFunction = (...args: any[]) => any;
+/** Outcome of one call of a mock function (`mock.results`). */
+type MockResult<R> = {
+  readonly type: "return";
+  readonly value: R;
+} | {
+  readonly type: "throw";
+  readonly value: unknown;
+} | {
+  readonly type: "incomplete";
+  readonly value: undefined;
+};
+/** Recorded calls of a mock function (`fn.mock`). */
+interface MockState<F extends AnyFunction = UntypedFunction> {
+  /** Arguments of every call, in call order. */
+  readonly calls: Parameters<F>[];
+  /** Outcome of every call, in call order. */
+  readonly results: MockResult<ReturnType<F>>[];
+  /** `this` of every call (the new instance for `new` calls). */
+  readonly instances: unknown[];
+  /** `this` of every call. */
+  readonly contexts: unknown[];
+  /** Global, monotonic order of every call (comparable across mocks). */
+  readonly invocationCallOrder: number[];
+  /** Arguments of the last call. */
+  readonly lastCall: Parameters<F> | undefined;
+}
+/**
+ * A mock function (spy): callable like `F`, records its calls and can be programmed. The API is the
+ * common subset of `jest.fn()`, `vi.fn()` and `bun:test`'s `mock()`.
+ */
+interface MockFunction<F extends AnyFunction = UntypedFunction> {
+  (...args: Parameters<F>): ReturnType<F>;
+  readonly mock: MockState<F>;
+  /** Every call returns `value` (until reset). */
+  mockReturnValue(value: ReturnType<F>): this;
+  /** The next call returns `value`. Queued values are used before the default implementation. */
+  mockReturnValueOnce(value: ReturnType<F>): this;
+  /** Every call returns a promise resolved with `value`. */
+  mockResolvedValue(value: Awaited<ReturnType<F>>): this;
+  mockResolvedValueOnce(value: Awaited<ReturnType<F>>): this;
+  /** Every call returns a promise rejected with `error`. */
+  mockRejectedValue(error: unknown): this;
+  mockRejectedValueOnce(error: unknown): this;
+  mockImplementation(implementation: (...args: Parameters<F>) => ReturnType<F>): this;
+  mockImplementationOnce(implementation: (...args: Parameters<F>) => ReturnType<F>): this;
+  /** Every call returns its `this`. */
+  mockReturnThis(): this;
+  /** Name displayed by assertion messages. */
+  mockName(name: string): this;
+  getMockName(): string;
+  getMockImplementation(): ((...args: Parameters<F>) => ReturnType<F>) | undefined;
+  /** Forgets the recorded calls (implementations are kept). */
+  mockClear(): this;
+  /** Forgets the recorded calls and the programmed implementations. */
+  mockReset(): this;
+  mockRestore(): void;
+}
+/** A member of a {@link Mocked} object: methods become {@link MockFunction}s, objects are mocked deeply. */
+type MockedMember<V> = V extends AnyFunction ? MockFunction<V> : V extends object ? Mocked<V> : V;
+/**
+ * A mock of `T`: assignable to `T`, every method is a {@link MockFunction} and every object member
+ * is itself mocked.
+ *
+ * ```ts
+ * const repository: Mocked<UserRepository> = createMock<UserRepository>()
+ * repository.findById.mockResolvedValue(user)
+ * ```
+ */
+type Mocked<T> = T & { [K in keyof T]: MockedMember<T[K]>; };
+/**
+ * An untyped deep mock: every property is a callable {@link MockFunction} which is itself a deep
+ * mock (`mock.repository.findById.mockResolvedValue(user)`).
+ */
+interface DeepMock {
+  readonly [key: string]: DeepMockFunction;
+}
+/** A callable member of a {@link DeepMock}. */
+type DeepMockFunction = MockFunction & DeepMock;
+/**
+ * Creates a mock function from an optional implementation: `vi.fn`, `jest.fn`, `bun:test`'s `mock`
+ * or {@link createSpy}.
+ */
+type MockFnFactory = (implementation?: AnyFunction) => unknown;
+/**
+ * Which spy implementation mocks use:
+ * - `'auto'` (default): Vitest (`globalThis.vi.fn`), Jest (`globalThis.jest.fn`), `bun:test`
+ *   (`mock`, when running on Bun), otherwise the built-in spy;
+ * - `'builtin'`: the built-in Jest-compatible spy ({@link createSpy});
+ * - a factory such as `vi.fn`, `jest.fn` or `mock` from `bun:test`.
+ */
+type MockFnOption = MockFnFactory | "auto" | "builtin";
+/**
+ * The auto-mocks of a `TestBed`, looked up by class, token, alias or display name.
+ *
+ * ```ts
+ * const { instance, mocks } = await TestBed.create(UserService, { metadata })
+ * mocks.get(UserRepository).findById.mockResolvedValue(user) // typed
+ * mocks.get('Logger').info // untyped deep mock
+ * ```
+ */
+interface MockRegistry {
+  /**
+   * The auto-mock injected for `key`: a class (typed result), a token, an alias (interface, base
+   * class) or a unique display name (`'UserRepository'`).
+   *
+   * @throws ZnightError ZNIGHT001 when no auto-mock matches (the message says why: provided value,
+   *   configuration class, optional dependency...), ZNIGHT008 when a display name is ambiguous.
+   */
+  get<T>(key: ClassKey<T>): Mocked<T>;
+  get<T = never>(key: TypedToken<T>): [T] extends [never] ? DeepMock : Mocked<T>;
+  /** Whether an auto-mock matches `key`. */
+  has(key: ClassKey | Token): boolean;
+  /** Tokens of the auto-mocked dependencies, in injection order. */
+  tokens(): Token[];
+  /** `mockClear()` on every spy of every auto-mock (recorded calls are forgotten). */
+  clearAll(): void;
+  /** Resets every auto-mock to its initial state (calls and programmed behaviours are forgotten). */
+  resetAll(): void;
+}
+/** Options of {@link createMetadata}. */
+interface CreateMetadataOptions {
+  readonly aliases?: Readonly<Record<Token, Token>>;
+  /** Externals, as tokens or full definitions (`{ token, scope, providedBy }`). */
+  readonly externals?: readonly (Token | ExternalDefinition)[];
+  readonly extensions?: ZnightExtensionsMetadata;
+  /** Default: a deterministic topological order (dependencies first, declaration order otherwise). */
+  readonly resolutionOrder?: readonly Token[];
+}
+/**
+ * Hand-written metadata with the exact shape the compiler generates (version, resolution order...),
+ * for tests that do not run the compiler (plugins, libraries, edge cases).
+ *
+ * ```ts
+ * const metadata = createMetadata({
+ *   'src/clock.ts#Clock': { scope: 'singleton', class: Clock, deps: [], factory: () => new Clock() },
+ * })
+ * ```
+ *
+ * @throws ZnightError ZNIGHT005 for a malformed provider definition.
+ */
+export declare function createMetadata(providers: Readonly<Record<Token, ProviderDefinition>>, options?: CreateMetadataOptions): ZnightMetadata;
+/** A provider class or a token, in {@link defineTestMetadata}. */
+type TestKey = Token | ProviderClass | ClassKey;
+/** A dependency in {@link defineTestMetadata}: like `DependencyRef`, with classes allowed in place of tokens. */
+type TestDependency = TestKey | {
+  readonly token: TestKey;
+  readonly optional: true;
+} | {
+  readonly multi: readonly TestKey[];
+} | {
+  readonly lazy: TestKey;
+};
+/** A provider in {@link defineTestMetadata}. */
+interface TestProvider<T = unknown> {
+  /** Default: `test#<ClassName>` (see `tokenPrefix`). Required without `class`. */
+  readonly token?: Token;
+  readonly class?: ProviderClass<T>;
+  /** Default: `'singleton'`. */
+  readonly scope?: Scope;
+  /** Constructor (or factory) dependencies, in parameter order. */
+  readonly deps?: readonly TestDependency[];
+  /** Default: `deps => new Class(...deps)`. Required without `class`. */
+  readonly factory?: ProviderFactory<T>;
+  readonly async?: boolean;
+  readonly interceptors?: Readonly<Record<string, MethodInterception>>;
+  readonly dispose?: string;
+  /** `@Named` qualifier. */
+  readonly name?: string;
+  readonly primary?: boolean;
+  readonly source?: SourceLocation;
+}
+/** Input of {@link defineTestMetadata}. */
+interface TestMetadataSpec {
+  /** Providers: classes (no dependency) or {@link TestProvider}s. */
+  readonly providers?: readonly (TestProvider | ProviderClass)[];
+  /** Alias → provider pairs (`[UserRepository, PgUserRepository]`), or a record of tokens. */
+  readonly aliases?: Iterable<readonly [TestKey, TestKey]> | Readonly<Record<Token, TestKey>>;
+  readonly externals?: readonly (Token | ExternalDefinition)[];
+  /** Feature metadata (`http`, `messaging`, `config`), tokens written with {@link testToken}. */
+  readonly extensions?: ZnightExtensionsMetadata;
+  readonly resolutionOrder?: readonly Token[];
+  /** Prefix of the tokens derived from class names. Default: `'test'` (`test#UserService`). */
+  readonly tokenPrefix?: string;
+}
+/** The token {@link defineTestMetadata} derives from a class: `<prefix>#<ClassName>`. */
+export declare function testToken(cls: ProviderClass | ClassKey, prefix?: string): Token;
+/**
+ * Class-first hand-written metadata: tokens are derived from class names (`test#UserService`),
+ * dependencies may be classes, factories default to `new Class(...deps)` and the resolution order
+ * is computed.
+ *
+ * ```ts
+ * const metadata = defineTestMetadata({
+ *   providers: [
+ *     PgUserRepository,
+ *     { class: UserService, deps: [PgUserRepository, '@znight/observability#Logger'] },
+ *   ],
+ *   aliases: [[UserRepository, PgUserRepository]],
+ *   externals: ['@znight/observability#Logger'],
+ * })
+ * ```
+ *
+ * @throws ZnightError ZNIGHT004 for duplicate tokens; TypeError for a provider without class nor
+ *   token/factory.
+ */
+export declare function defineTestMetadata(spec?: TestMetadataSpec): ZnightMetadata;
+/** Options of {@link createMock}. */
+interface CreateMockOptions {
+  /**
+   * Name of the mock, used to name its spies in assertion messages (`UserRepository.findById`).
+   * Default: the class name, or `mock`.
+   */
+  readonly name?: string;
+  /**
+   * When `true`, calling an unconfigured method returns a deep mock (the same one for every call)
+   * instead of `undefined`, so fluent APIs work: `db.select().from('users')`. Default: `false`.
+   */
+  readonly deep?: boolean;
+  /** Spy implementation. Default: auto-detected (see `MockFnOption`). */
+  readonly mockFn?: MockFnOption;
+}
+/**
+ * Creates a deep auto-mock.
+ *
+ * - Every property read returns a spy (`MockFunction`), created on first access and then stable.
+ *   Spies are deep too: `mock.pool.query.mockResolvedValue(rows)`.
+ * - Unconfigured spies return `undefined` (or a deep mock with `{ deep: true }`).
+ * - The mock is **not thenable** and inert for serialisers: `then`, `toJSON`, `asymmetricMatch`,
+ *   `$$typeof`, `Symbol.toPrimitive`... read as `undefined`, so `await mock`, `JSON.stringify(mock)`
+ *   and `expect(...).toEqual(mock)` behave.
+ * - Assigned properties win: `mock.enabled = false`.
+ * - With a class, the mock inherits its prototype (`instanceof` works) and getters read as
+ *   `undefined` instead of a (truthy) spy.
+ * - Functions of `partial` become spies with that implementation; other values are set as is.
+ *
+ * ```ts
+ * const repository = createMock(UserRepository, { findById: async id => ({ id }) })
+ * const logger = createMock<Logger>()
+ * logger.info('hello')
+ * expect(logger.info).toHaveBeenCalledWith('hello')
+ * ```
+ */
+export declare function createMock<T>(cls: ClassKey<T>, partial?: Partial<T>, options?: CreateMockOptions): Mocked<T>;
+export declare function createMock<T = never>(partial?: Partial<T>, options?: CreateMockOptions): [T] extends [never] ? DeepMock : Mocked<T>;
+/** Whether `value` is a mock (or one of its spies) created by {@link createMock}. */
+export declare function isMock(value: unknown): boolean;
+/** Forgets the calls recorded by every spy of `mock` (`mockClear()`); implementations are kept. */
+export declare function clearMock(mock: object): void;
+/**
+ * Resets every spy of `mock` to its initial state: recorded calls and programmed implementations
+ * are forgotten, implementations given to {@link createMock} (and deep returns) are restored.
+ */
+export declare function resetMock(mock: object): void;
+/** Where the spy factory used by mocks comes from. */
+type MockFnSource = "custom" | "vitest" | "jest" | "bun" | "builtin";
+/** A spy factory and its origin (see {@link resolveMockFn}). */
+interface ResolvedMockFn {
+  readonly source: MockFnSource;
+  readonly create: MockFnFactory;
+}
+/**
+ * Sets the spy factory used when `mockFn` is not passed explicitly (e.g. in a Vitest setup file:
+ * `setDefaultMockFn(vi.fn)`). Without argument, restores auto-detection.
+ */
+export declare function setDefaultMockFn(option?: MockFnOption): void;
+/**
+ * Resolves a {@link MockFnOption} (default: the option set with {@link setDefaultMockFn}, `'auto'`
+ * initially) to a spy factory.
+ */
+export declare function resolveMockFn(option?: MockFnOption): ResolvedMockFn;
+/**
+ * Auto-detects the spy factory of the running test framework: Vitest (`globalThis.vi.fn`, with
+ * `globals: true`), Jest (`globalThis.jest.fn`), `bun:test` (`mock`, loaded only when running on
+ * Bun), otherwise the built-in spy ({@link createSpy}).
+ */
+export declare function detectMockFn(): ResolvedMockFn;
+/** A typed `[key, value]` entry for `overrides` / `providers` / `provide`. */
+type OverrideEntry<T = unknown> = readonly [ProviderKey<T>, T];
+/** A `[key, definition]` entry replacing a provider with a factory. */
+type OverrideDefinitionEntry<T = unknown> = readonly [ProviderKey<T>, ProviderDefinition<T>];
+/**
+ * A type-checked override: the value must match the type designated by the class or typed token.
+ *
+ * ```ts
+ * await TestApp.create({ metadata, overrides: [override(UserRepository, new InMemoryUserRepository())] })
+ * ```
+ */
+export declare function override<T>(key: ProviderKey<T>, value: NoInfer<T>): OverrideEntry<T>;
+/** Options of {@link overrideFactory}. */
+interface OverrideFactoryOptions {
+  /** Tokens resolved and passed to the factory, in order. Default: none. */
+  readonly deps?: readonly DependencyRef[];
+  /** Default: `'singleton'`. */
+  readonly scope?: Scope;
+  /** Set when the factory returns a promise (singletons only). */
+  readonly async?: boolean;
+  /** Method called when the instance is disposed. */
+  readonly dispose?: string;
+}
+/**
+ * Replaces a provider with a factory whose dependencies are resolved by the container (or, in
+ * `TestBed`, like the target's dependencies).
+ *
+ * ```ts
+ * overrideFactory(UserRepository, ([db]) => new InMemoryUserRepository(db), { deps: ['src/db.ts#Database'] })
+ * ```
+ */
+export declare function overrideFactory<T>(key: ProviderKey<T>, factory: ProviderFactory<NoInfer<T>>, options?: OverrideFactoryOptions): OverrideDefinitionEntry<T>;
+/**
+ * Creates the built-in, dependency-free, Jest-compatible spy. It records `mock.calls`,
+ * `mock.results`, `mock.instances`, `mock.contexts`, `mock.invocationCallOrder` and `mock.lastCall`,
+ * supports `mockReturnValue(Once)`, `mockResolvedValue(Once)`, `mockRejectedValue(Once)`,
+ * `mockImplementation(Once)`, `mockReturnThis`, `mockName`, `mockClear`, `mockReset` and
+ * `mockRestore`, and is recognised by Jest's and Vitest's `expect` (`_isMockFunction`).
+ *
+ * `mockReset()` restores the implementation given to `createSpy()` (Vitest semantics).
+ *
+ * ```ts
+ * const find = createSpy((id: string) => ({ id }))
+ * find.mockReturnValueOnce({ id: 'x' })
+ * find('1')
+ * find.mock.calls // [['1']]
+ * ```
+ */
+export declare function createSpy<F extends AnyFunction = UntypedFunction>(implementation?: F): MockFunction<F>;
+/** Whether `value` is a spy created by {@link createSpy}. */
+export declare function isBuiltinSpy(value: unknown): boolean;
+/** Name of the HTTP plugin `TestApp.inject()` delegates to (`HttpPlugin.configure()` from `@znight/http`). */
+export declare const HTTP_PLUGIN_NAME = "http";
+/** An in-memory HTTP request for {@link TestApp.inject}. */
+interface InjectRequest {
+  /** HTTP method. Default: `GET`. */
+  readonly method?: string;
+  /** Path, with an optional query string (`/users?page=2`). */
+  readonly url: string;
+  readonly headers?: Readonly<Record<string, string>>;
+  /**
+   * Request body, encoded by the HTTP plugin: a string or bytes are sent as is (`text/plain` /
+   * `application/octet-stream` without `content-type` header), a `FormData` as
+   * `multipart/form-data` (files included: uploads), a `Blob` / `File` with its type, anything else
+   * as JSON (`application/json`).
+   */
+  readonly body?: unknown;
+  /** Query parameters added to those of `url`. */
+  readonly query?: Readonly<Record<string, string | readonly string[]>>;
+  /**
+   * Request cookies (name → value), sent by the HTTP plugin in a `cookie` header, after any `cookie`
+   * header of `headers`. Values are encoded like the cookies the plugin sets, so a value read from
+   * `response.cookies` can be sent back as is (signed values included).
+   */
+  readonly cookies?: Readonly<Record<string, string>>;
+  /**
+   * Cookies the HTTP plugin signs with its current secret (`cookies.secrets[0]`) and merges into
+   * `cookies` before dispatch: the way to send a valid `@SignedCookie`.
+   */
+  readonly signedCookies?: Readonly<Record<string, string>>;
+}
+/**
+ * A parsed `Set-Cookie` header of an {@link InjectResponse}: the shape of `SetCookieInfo` from
+ * `@znight/http`.
+ */
+interface SetCookieInfo {
+  readonly name: string;
+  /** Decoded value (a signed cookie: `<value>.<signature>`). */
+  readonly value: string;
+  /** The `Set-Cookie` header line. */
+  readonly raw: string;
+  readonly expires?: Date;
+  readonly maxAge?: number;
+  readonly domain?: string;
+  readonly path?: string;
+  readonly secure: boolean;
+  readonly httpOnly: boolean;
+  readonly sameSite?: "strict" | "lax" | "none";
+  readonly partitioned: boolean;
+  readonly priority?: "low" | "medium" | "high";
+}
+/** The response of {@link TestApp.inject}. */
+interface InjectResponse {
+  readonly status: number;
+  /** Response headers (lower-cased names). */
+  readonly headers: Readonly<Record<string, string | readonly string[] | undefined>>;
+  /** The body decoded as UTF-8. */
+  readonly body: string;
+  /** The raw body bytes (downloads, binary responses). */
+  readonly bytes: Uint8Array;
+  /** The `set-cookie` headers parsed, by cookie name (the last one wins); `{}` without any. */
+  readonly cookies: Readonly<Record<string, SetCookieInfo>>;
+  /** The body parsed as JSON. */
+  json<T = unknown>(): T;
+}
+/**
+ * What the `inject()` of the HTTP plugin resolves with: an {@link InjectResponse} whose `bytes` and
+ * `cookies` may be absent (`TestApp.inject()` then encodes `body` as UTF-8 and returns no cookies).
+ */
+type HttpInjectResult = Omit<InjectResponse, "bytes" | "cookies"> & {
+  readonly bytes?: Uint8Array;
+  readonly cookies?: Readonly<Record<string, SetCookieInfo>>;
+};
+/**
+ * What `TestApp.inject()` expects from the plugin named `'http'`: an in-memory dispatch (no socket).
+ * `HttpPlugin` from `@znight/http` implements it.
+ */
+interface HttpInjector {
+  inject(request: InjectRequest & {
+    readonly method: string;
+  }): Promise<HttpInjectResult>;
+}
+/** A request for {@link TestApp.injectStream} / {@link TestApp.injectSse}: an {@link InjectRequest} that can be aborted. */
+interface InjectStreamRequest extends InjectRequest {
+  /** Aborting it disconnects the client (like cancelling the response body). */
+  readonly signal?: AbortSignal;
+}
+/**
+ * The response of {@link TestApp.injectStream}: available at the headers, the body read as it is
+ * produced. Cancelling `body` disconnects the client. The shape of `InjectStreamResponse` from
+ * `@znight/http`.
+ */
+interface InjectStreamResponse {
+  readonly status: number;
+  readonly headers: Readonly<Record<string, string | readonly string[] | undefined>>;
+  readonly cookies: Readonly<Record<string, SetCookieInfo>>;
+  readonly body: ReadableStream<Uint8Array>;
+}
+/** An event of an event stream (`SseMessage` of `@znight/http`). */
+interface SseMessage {
+  /** Event type: `message` by default. */
+  readonly event: string;
+  readonly data: string;
+  /** The last event id at dispatch time. */
+  readonly id: string;
+  json<T = unknown>(): T;
+}
+/**
+ * The response of {@link TestApp.injectSse}: an event stream read in memory like `EventSource`
+ * would (`InjectSseResponse` of `@znight/http`).
+ */
+interface InjectSseResponse extends AsyncIterable<SseMessage>, AsyncDisposable {
+  readonly status: number;
+  readonly headers: Readonly<Record<string, string | readonly string[] | undefined>>;
+  readonly cookies: Readonly<Record<string, SetCookieInfo>>;
+  /** `''` for an event stream; otherwise the whole body (an error, a 204...). */
+  readonly body: string;
+  json<T = unknown>(): T;
+  /** The next event (comments skipped). Rejects on timeout (default 2 000 ms) or when the stream ended. */
+  next(options?: {
+    readonly timeoutMs?: number;
+  }): Promise<SseMessage>;
+  take(count: number, options?: {
+    readonly timeoutMs?: number;
+  }): Promise<SseMessage[]>;
+  /** Comments received so far (heartbeats are `''`). */
+  readonly comments: readonly string[];
+  /** What a browser would send as `Last-Event-ID`. */
+  readonly lastEventId: string;
+  /** The last `retry` received. */
+  readonly retry: number | undefined;
+  /** Resolves when the server ends the stream. */
+  readonly done: Promise<void>;
+  /** Disconnects (the server sees a client disconnect). Idempotent. */
+  close(): Promise<void>;
+  /** Reconnects like `EventSource`: the same request plus `last-event-id`. */
+  reconnect(): Promise<InjectSseResponse>;
+}
+/**
+ * What `TestApp.injectStream()` / `injectSse()` expect from the plugin named `'http'`
+ * (`HttpPlugin` of `@znight/http` ≥ 0.1.0, the release that ships streaming).
+ */
+interface HttpStreamInjector {
+  injectStream(request: InjectStreamRequest & {
+    readonly method: string;
+  }): Promise<InjectStreamResponse>;
+  injectSse(request: InjectStreamRequest & {
+    readonly method: string;
+  }): Promise<InjectSseResponse>;
+}
+/**
+ * A plugin implementing the optional `initRoots(context)` member of `Plugin` (`@znight/core`), read
+ * by `TestApp.create()`: the providers the plugin needs at boot although the metadata does not make
+ * them entry points, i.e. classes or tokens given in its options (`HttpPlugin.configure({ guards,
+ * interceptors, exceptionMappers })`) or derived from its metadata section (`context.metadata`).
+ * `TestApp` adds them to the providers instantiated at boot (see {@link TestAppOptions.only}), so
+ * that their async dependencies exist when the plugin resolves them: an async factory cannot run on
+ * demand.
+ *
+ * Called once per `TestApp.create()`, before the application is created. Keys that are not
+ * providers of the metadata are ignored (the plugin reports them itself).
+ */
+type PluginInitRoots = Required<Pick<Plugin, "initRoots">>;
+/** Options of {@link TestApp.create}. */
+interface TestAppOptions {
+  /** The generated metadata (`__ZNIGHT_METADATA__`). */
+  readonly metadata: ZnightMetadata;
+  readonly plugins?: readonly Plugin[];
+  /** Values supplied by the application (externals, configuration...), as in `Application.create`. */
+  readonly providers?: ProviderValues;
+  /**
+   * Replacements applied last, with the highest precedence: values or provider definitions
+   * (`{ scope, deps, factory }`), keyed by class or token. Overridden providers are instantiated.
+   */
+  readonly overrides?: ProviderValues;
+  /**
+   * Which providers are instantiated at boot (with their dependency closure, plus the overrides and
+   * the providers the plugins resolve at bootstrap, see {@link PluginInitRoots}: global guards,
+   * interceptors and exception mappers of `HttpPlugin`):
+   * - default: the entry points of the metadata, i.e. the HTTP controllers (with their guards and
+   *   interceptors), the message consumers and the hosts of scheduled jobs, or every provider when
+   *   there is none;
+   * - `'all'`: every provider;
+   * - a list of classes or tokens.
+   *
+   * Other providers are created on first use (synchronous factories only: list a provider here
+   * when it, or one of its dependencies, has an async factory).
+   */
+  readonly only?: readonly ProviderKey[] | "all";
+  /** Application logger. Default: a console logger writing warnings and errors. */
+  readonly logger?: CoreLogger;
+  /** Run `app.start()` (plugins `onStart`: listen, subscribe...). Default: `true`. */
+  readonly start?: boolean;
+  /** Shutdown timeouts. Signal handlers are always disabled. */
+  readonly shutdown?: Omit<ShutdownOptions, "signals" | "process">;
+}
+/**
+ * End-to-end harness: a started {@link Application} without signal handlers, overrides applied last
+ * and only what the tested entry points need instantiated.
+ *
+ * ```ts
+ * await using app = await TestApp.create({
+ *   metadata: __ZNIGHT_METADATA__,
+ *   plugins: [HttpPlugin.configure({ adapter: fastify() })],
+ *   overrides: [[UserRepository, fakeRepository]],
+ * })
+ * const response = await app.inject({ method: 'GET', url: '/users/1' })
+ * expect(response.status).toBe(200)
+ * expect(response.json()).toEqual({ id: '1' })
+ * ```
+ */
+export declare class TestApp implements AsyncDisposable {
+  #private;
+  /** The application under test. */
+  readonly app: Application;
+  private constructor();
+  /**
+   * Creates and (by default) starts the application.
+   *
+   * Plugins are used as configured: give the servers they start a free port or none in tests
+   * (`HttpPlugin.configure({ port: 0 })`, `ObservabilityPlugin.configure({ metrics: { server: false } })`);
+   * a start failing on a port already in use (`EADDRINUSE`) gets a hint saying so.
+   *
+   * @throws the error of `Application.create()` / `app.start()` (everything is rolled back).
+   */
+  static create(options: TestAppOptions): Promise<TestApp>;
+  /** The application container. */
+  get container(): Container;
+  /** Shortcut for `app.container.get(key)`. */
+  get<T>(key: ProviderClass<T>): T;
+  get<T>(key: ClassKey<T>): T;
+  get<T = unknown>(key: TypedToken<T>): T;
+  /**
+   * Dispatches a request in memory through the HTTP plugin (`HttpPlugin`): routing, guards,
+   * interceptors, validation, serialisation, without opening a socket. Send uploads as a
+   * `FormData` body; read downloads from `response.bytes`. Send cookies with `cookies` (and
+   * `signedCookies`), read those the response sets from `response.cookies`.
+   *
+   * @throws ZnightError ZNIGHT001 when the application has no HTTP plugin, ZNIGHT021 once closed.
+   */
+  inject(request: InjectRequest): Promise<InjectResponse>;
+  /**
+   * Dispatches a request in memory and resolves at the response headers; the body is read as it is
+   * produced (`response.body`). Cancelling the body (or aborting `signal`) disconnects the client.
+   *
+   * @throws ZnightError ZNIGHT001 when the HTTP plugin does not support streaming, ZNIGHT021 once closed.
+   */
+  injectStream(request: InjectStreamRequest): Promise<InjectStreamResponse>;
+  /**
+   * Opens an event stream (Server-Sent Events) in memory and reads it like `EventSource`:
+   *
+   * ```ts
+   * await using stream = await app.injectSse({ url: '/orders/o-1/events' })
+   * const event = await stream.next() // rejects after 2 000 ms
+   * expect(event.json()).toMatchObject({ status: 'paid' })
+   * const resumed = await stream.reconnect() // last-event-id, like EventSource
+   * ```
+   *
+   * Leaving the `await using` block (or `close()`) disconnects: the server sees `ctx.signal` abort.
+   *
+   * @throws ZnightError ZNIGHT001 when the HTTP plugin does not support event streams, ZNIGHT021 once closed.
+   */
+  injectSse(request: InjectStreamRequest): Promise<InjectSseResponse>;
+  /** Stops the application (idempotent): plugins `onStop`, providers `onStop` and disposal, plugins `onDispose`. */
+  close(): Promise<void>;
+  /** {@link close}, for `await using app = await TestApp.create(...)`. */
+  [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * How `@Intercept` interceptors of the target are handled:
+ * - `'none'` (default): interceptors are neither instantiated nor applied, the target's methods are
+ *   the plain ones;
+ * - `'real'`: interceptors are built (their own dependencies auto-mocked) or taken from
+ *   `provide`/`overrides`, and applied like the container does.
+ */
+type AopMode = "none" | "real";
+/** Options of {@link TestBed.create}. */
+interface TestBedOptions {
+  /** The generated metadata (`__ZNIGHT_METADATA__`). */
+  readonly metadata: ZnightMetadata;
+  /**
+   * Values injected instead of auto-mocks, keyed by class, token, alias or display name. Required
+   * for qualified values (`@Inject('dbUrl')`, `@Provides({ name })` without a class) such as
+   * primitives; also used for optional dependencies and members of multi dependencies.
+   */
+  readonly provide?: ProviderValues;
+  /**
+   * Like `provide`, but a value shaped like a provider definition (`{ scope, deps, factory }`) is
+   * built with its factory, its own dependencies being resolved like the target's (auto-mocked...).
+   * A definition keyed by the target replaces the target's factory. Wins over `provide`.
+   */
+  readonly overrides?: ProviderValues;
+  /** Values of configuration classes (real instances are injected for `@Config` classes). */
+  readonly config?: ConfigValues;
+  /** Spy implementation of the auto-mocks. Default: auto-detected. */
+  readonly mockFn?: MockFnOption;
+  /** Auto-mocks return deep mocks from unconfigured methods instead of `undefined`. Default: `false`. */
+  readonly deep?: boolean;
+  /** Interceptors handling, see {@link AopMode}. Default: `'none'`. */
+  readonly aop?: AopMode;
+}
+/** What {@link TestBed.create} returns. */
+interface TestBedResult<T> {
+  /** The target, built with its real (generated) factory. */
+  readonly instance: T;
+  /** The auto-mocks injected into the target. */
+  readonly mocks: MockRegistry;
+  /**
+   * A container holding the target and everything injected into it (auto-mocks, provided values,
+   * configuration instances), for code that resolves dependencies itself.
+   */
+  readonly container: Container;
+}
+/**
+ * Unit-test harness: builds one provider with its real factory and auto-mocks its **direct**
+ * dependencies, by kind:
+ *
+ * | Dependency                                   | Injected                                            |
+ * | -------------------------------------------- | --------------------------------------------------- |
+ * | class / interface / `@Provides` / external   | deep auto-mock                                      |
+ * | configuration class (`@Config`)              | real instance: defaults + `config` values           |
+ * | qualified value (`@Inject('x')`, primitives) | the `provide` value (an error otherwise)            |
+ * | optional (`@Optional()`, `T \| undefined`)   | `undefined` (or the `provide` value)                |
+ * | multi (`T[]`)                                | `[]` (or the provided members)                      |
+ * | `Lazy<T>`                                    | `{ get: () => mock }`                               |
+ * | interceptor (`@Intercept`)                   | nothing, not applied (unless `aop: 'real'`)         |
+ *
+ * ```ts
+ * const { instance, mocks } = await TestBed.create(UserService, { metadata: __ZNIGHT_METADATA__ })
+ * mocks.get(UserRepository).findById.mockResolvedValue({ id: '1' })
+ * await instance.findById('1')
+ * expect(mocks.get(UserRepository).findById).toHaveBeenCalledWith('1')
+ * ```
+ */
+export declare class TestBed {
+  private constructor();
+  /**
+   * Builds `target` (a class, token, alias or display name of a provider of `options.metadata`).
+   *
+   * @throws ZnightError ZNIGHT001 (unknown target, qualified dependency without value), ZNIGHT012
+   *   (invalid `config`), ZNIGHT015 (the factory failed).
+   */
+  static create<T>(target: ProviderClass<T> | ClassKey<T>, options: TestBedOptions): Promise<TestBedResult<T>>;
+  static create<T = unknown>(target: TypedToken<T>, options: TestBedOptions): Promise<TestBedResult<T>>;
+}
+export type { AnyFunction, AopMode, ConfigProperties, ConfigValues, CreateMetadataOptions, CreateMockOptions, DeepMock, DeepMockFunction, HttpInjectResult, HttpInjector, HttpStreamInjector, InjectRequest, InjectResponse, InjectSseResponse, InjectStreamRequest, InjectStreamResponse, MockFnFactory, MockFnOption, MockFnSource, MockFunction, MockRegistry, MockResult, MockState, Mocked, MockedMember, OverrideDefinitionEntry, OverrideEntry, OverrideFactoryOptions, PluginInitRoots, ResolvedMockFn, SetCookieInfo, SseMessage, TestAppOptions, TestBedOptions, TestBedResult, TestDependency, TestKey, TestMetadataSpec, TestProvider, UntypedFunction };
+//# sourceMappingURL=index.d.mts.map