@znight/testing 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ugho STEPHAN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,442 @@
-# Temporary Holding Version
+# @znight/testing
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Testing utilities for [Znight](../../README.md) applications: unit tests with auto-mocked
+dependencies, end-to-end tests with in-memory requests.
+
+- **`TestBed`**: unit tests. Builds one provider with its real (generated) factory and auto-mocks its
+  direct dependencies.
+- **`TestApp`**: end-to-end tests. A started `Application` without signal handlers, with overrides
+  applied last, only what the tested entry points need instantiated, and in-memory HTTP requests
+  (`app.inject()`).
+- **Deep auto-mocks** and a **Jest-compatible spy**, cooperating with `bun:test`, Vitest and Jest.
+
+```sh
+# bun
+bun add -d @znight/testing
+
+# npm
+npm install -D @znight/testing
+```
+
+Runs on Node.js >= 24 and Bun >= 1.3 (ESM only), with any test runner.
+
+**Documentation:** [`@znight/testing`](https://github.com/znight-org/znight/blob/main/docs/packages/testing.md)
+and the [testing guide](https://github.com/znight-org/znight/blob/main/docs/guide/testing.md).
+**Examples:** every [example application](https://github.com/znight-org/znight/tree/main/examples)
+ships its tests (`bun test`): unit tests with `TestBed`, HTTP tests with `TestApp` in
+[`rest-api`](https://github.com/znight-org/znight/tree/main/examples/rest-api), message consumers in
+[`worker`](https://github.com/znight-org/znight/tree/main/examples/worker), event streams and a
+virtual clock in [`uptime-monitor`](https://github.com/znight-org/znight/tree/main/examples/uptime-monitor).
+
+## Generated metadata first
+
+Znight resolves dependencies at build time: `TestBed` and `TestApp` read the metadata generated by
+`@znight/compiler` (`__ZNIGHT_METADATA__`, `src/.znight/container.generated.ts`). It is not committed,
+so make sure it is fresh before the tests run:
+
+| Test runner | Setup                                                                                           |
+| ----------- | ----------------------------------------------------------------------------------------------- |
+| `bun test`  | Preload the compiler: `bunfig.toml` → `[test] preload = ["@znight/compiler/bun"]`               |
+| Vitest      | Add the `znight()` Vite plugin to `vitest.config.ts` (it regenerates the metadata on every run) |
+| Anything    | Run `znight generate` before the tests (`"pretest": "znight generate"`), `--check` fails in CI  |
+
+```ts
+import { __ZNIGHT_METADATA__ as metadata } from '../src/.znight/container.generated.js'
+```
+
+Without metadata, or for a class missing from it, `TestBed` reports a `ZNIGHT001` naming the class
+and how to regenerate the metadata. A metadata format mismatch is a `ZNIGHT018`. Stale metadata (a
+constructor changed since the last generation) calls the factory with outdated dependencies: keep
+the preload / plugin / `pretest` script in place.
+
+## TestBed
+
+```ts
+import { describe, expect, test } from 'bun:test'
+import { TestBed } from '@znight/testing'
+import { __ZNIGHT_METADATA__ as metadata } from '../src/.znight/container.generated.js'
+
+describe('UserService', () => {
+  test('finds a user', async () => {
+    const { instance, mocks } = await TestBed.create(UserService, { metadata })
+
+    mocks.get(UserRepository).findById.mockResolvedValue({ id: '1', name: 'Ada' })
+
+    expect(await instance.findById('1')).toEqual({ id: '1', name: 'Ada' })
+    expect(mocks.get(UserRepository).findById).toHaveBeenCalledWith('1')
+    expect(mocks.get(Logger).info).toHaveBeenCalled()
+  })
+})
+```
+
+`TestBed.create(target, options)` builds `target` (a class, a token, an alias such as an interface
+or abstract base, or a unique display name) with its generated factory, then returns:
+
+| Field       | Description                                                                                         |
+| ----------- | --------------------------------------------------------------------------------------------------- |
+| `instance`  | The target, built with real code. Async factories are awaited.                                      |
+| `mocks`     | The auto-mocks: `get(key)`, `has(key)`, `tokens()`, `clearAll()`, `resetAll()`.                     |
+| `container` | A `Container` holding the target and everything injected into it (for code resolving dependencies). |
+
+Lifecycle hooks (`onStart`...) are not called: call them yourself when the test needs them.
+
+### What gets injected
+
+Only **direct** dependencies are replaced, by kind:
+
+| Dependency                                                     | Injected                                                                                                                         |
+| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Class, interface, abstract class, `@Provides` value, external  | A deep auto-mock (`mocks.get(...)`)                                                                                              |
+| Configuration class (`@Config`)                                | A real instance: field initializers, then `@Default` values (converted to the field type, like at runtime), then `config` values |
+| Qualified value without class (`@Inject('dbUrl')`, primitives) | The `provide` value, otherwise a `ZNIGHT001` error naming it                                                                     |
+| Optional (`@Optional()`, `T \| undefined`)                     | `undefined`, unless provided                                                                                                     |
+| Multi (`T[]`)                                                  | `[]`, plus the members that are provided                                                                                         |
+| `Lazy<T>`                                                      | `{ get: () => mock }` (the same mock as `mocks.get(T)`)                                                                          |
+| Interceptor (`@Intercept`, `@Logged`...)                       | Nothing, and interceptors are not applied (see `aop`)                                                                            |
+
+A dependency used several times (e.g. directly and lazily) always receives the same value.
+Qualified **class** providers (`@Named('replica') class Replica`) are auto-mocked: their type is known.
+
+### Options
+
+| Option      | Type                                  | Description                                                                                                                                |
+| ----------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `metadata`  | `ZnightMetadata`                      | **Required.** The generated metadata.                                                                                                      |
+| `provide`   | `Map` / `[key, value][]` / record     | Values injected instead of auto-mocks. Keys: class, token, alias or display name (`{ 'AppFactory.dbUrl': 'postgres://' }`).                |
+| `overrides` | same as `provide`                     | Like `provide` (and wins over it), but a provider definition `{ scope, deps, factory }` is **built**, its own dependencies auto-mocked.    |
+| `config`    | record / `[ConfigClass, values][]`    | Values of configuration classes, keyed by class, token, display name or `@Config` prefix.                                                  |
+| `aop`       | `'none'` \| `'real'`                  | `'real'` builds the interceptors (their dependencies auto-mocked, or taken from `provide`/`overrides`) and applies them. Default `'none'`. |
+| `deep`      | `boolean`                             | Unconfigured methods of the auto-mocks return deep mocks instead of `undefined`. Default `false`.                                          |
+| `mockFn`    | `'auto'` \| `'builtin'` \| `vi.fn`... | Spy implementation. Default: auto-detected (see [Spies](#spies)).                                                                          |
+
+```ts
+const { instance } = await TestBed.create(UserService, {
+  metadata,
+  provide: { 'DbFactory.databaseUrl': 'postgres://test' }, // qualified primitive
+  config: { database: { host: 'db.test', port: 5433 } }, // @Config('database')
+  overrides: [
+    // build the real repository; its own dependencies (Database...) are auto-mocked
+    [UserRepository, metadata.providers['src/users/pg-user.repository.ts#PgUserRepository']],
+  ],
+  aop: 'real', // apply @Logged / @Intercept with real interceptors
+})
+```
+
+Errors are explicit: an unknown key in `provide`/`overrides` (`ZNIGHT001`), an unknown configuration
+class or property (`ZNIGHT012`), an ambiguous display name (`ZNIGHT008`), a failing factory
+(`ZNIGHT015` with the original `cause` and the source location).
+
+### `mocks`
+
+`mocks.get(key)` accepts a class (typed result: `Mocked<T>`), a token (`TypedToken<T>` gives a typed
+result), an alias (`UserRepository` for `PgUserRepository`) or a display name (`'Logger'`, untyped deep
+mock unless you pass the type: `mocks.get<Logger>('Logger')`). When the dependency was not
+auto-mocked, the error says why (provided, configuration class, optional, interceptor...).
+
+`mocks.clearAll()` forgets every recorded call; `mocks.resetAll()` also forgets programmed behaviours
+and restores the initial implementations.
+
+## TestApp
+
+```ts
+import { expect, test } from 'bun:test'
+import { HttpPlugin } from '@znight/http'
+import { createMock, override, TestApp } from '@znight/testing'
+
+test('GET /users/:id', async () => {
+  const repository = createMock(UserRepository)
+  repository.findById.mockResolvedValue({ id: '1', name: 'Ada' })
+
+  await using app = await TestApp.create({
+    metadata,
+    plugins: [HttpPlugin.configure({ port: 0 })], // any adapter; port 0 = a free port
+    overrides: [override(UserRepository, repository)],
+  })
+
+  const response = await app.inject({ method: 'GET', url: '/users/1' })
+  expect(response.status).toBe(200)
+  expect(response.json()).toEqual({ id: '1', name: 'Ada' })
+})
+```
+
+`TestApp.create(options)` runs `Application.create()` then `app.start()`, with signal handlers
+disabled. Overrides are applied after the plugins registered (highest precedence) and the real
+container is used: interceptors, scopes and lifecycle hooks all run.
+
+`app.inject()` needs no listening server: configure the HTTP plugin with `port: 0` (a free port) so
+parallel test files never collide, or pass `start: false` to stop after `onBootstrap`.
+
+The same goes for every server a plugin starts on a fixed port. Once `prom-client` is installed,
+`ObservabilityPlugin` from `@znight/observability` serves `/metrics` on port 9464 by default: a
+second test file, or `znight dev`, then fails to start. Disable that server in tests, or give it a
+free port when a test scrapes it:
+
+```ts
+await using app = await TestApp.create({
+  metadata,
+  plugins: [
+    ObservabilityPlugin.configure({ logging: { level: 'silent' }, metrics: { server: false } }), // or server: { port: 0 }
+    HttpPlugin.configure({ port: 0 }),
+  ],
+})
+```
+
+`TestApp` never changes the options of the plugins it is given (they are configured instances):
+when the start fails because a port is taken (`EADDRINUSE` anywhere in the `cause` chain), the error
+carries a hint naming these options.
+
+| Option      | Type                              | Description                                                                                                                                                                                                                                                                                   |
+| ----------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `metadata`  | `ZnightMetadata`                  | **Required.** The generated metadata.                                                                                                                                                                                                                                                         |
+| `plugins`   | `Plugin[]`                        | Plugins, as in `Application.create`.                                                                                                                                                                                                                                                          |
+| `providers` | `Map` / `[key, value][]` / record | Values for externals (`Logger`, `ConfigSource`...), as in `Application.create`.                                                                                                                                                                                                               |
+| `overrides` | `Map` / `[key, value][]` / record | Values or provider definitions replacing providers, applied last. Overridden providers are instantiated at boot.                                                                                                                                                                              |
+| `only`      | `'all'` \| `(Class \| Token)[]`   | Providers instantiated at boot (with their dependencies), plus the overrides and the plugin roots (below). Default: the entry points of the metadata (HTTP controllers with their guards and interceptors, message consumers, hosts of scheduled jobs), or every provider when there is none. |
+| `start`     | `boolean`                         | Run `app.start()` (plugins listen/subscribe). Default `true`; `false` stops after `onBootstrap`.                                                                                                                                                                                              |
+| `logger`    | `CoreLogger`                      | Default: a console logger writing warnings and errors only.                                                                                                                                                                                                                                   |
+| `shutdown`  | `{ timeoutMs?, hookTimeoutMs? }`  | Shutdown timeouts.                                                                                                                                                                                                                                                                            |
+
+Keys of `providers` and `overrides` may be classes, tokens, aliases or unique display names
+(`'UserRepository'`), like in `TestBed`; other strings are used as tokens (values for tokens
+registered at runtime by plugins).
+
+Limiting the boot to the closure of the entry points keeps tests fast and lets them ignore unrelated
+providers (and their missing externals). Other providers are still created on first use (synchronous
+factories only). The hosts of scheduled jobs (`@Cron`, `@Interval`, `@Timeout` of
+`@znight/schedule`) are entry points even when the test does not run the scheduler, so a test that
+only exercises HTTP routes can pass `SchedulePlugin.configure({ enabled: false })` and still trigger
+a job through the registry.
+
+Providers a plugin resolves while it bootstraps without the metadata making them entry points (the
+global `guards`, `interceptors` and `exceptionMappers` of `HttpPlugin.configure({...})`) are
+instantiated at boot too, with their dependencies, when the plugin lists them in the optional
+`initRoots(context)` method of `Plugin` (`@znight/core`), as `HttpPlugin` does (see
+[Compiler contract](#compiler-contract)). These plugin roots complete the entry points and never
+restrict the boot by themselves: without any entry point, every provider is created.
+
+Options computed from the container (`HttpPlugin.configure(c => ({...}))`) cannot be listed before
+the boot: when such a provider (or one of its dependencies) has an async factory, the boot fails
+with `ZNIGHT015` ("cannot create ... on demand: its factory is async"); add it to `only`, or pass
+`only: 'all'`:
+
+```ts
+await using app = await TestApp.create({
+  metadata: __ZNIGHT_METADATA__,
+  plugins: [HttpPlugin.configure(c => ({ port: 0, prefix: c.get(AppConfig).prefix, guards: [AuthGuard] }))],
+  only: [UserController, AuthGuard], // AuthGuard needs the async JwksStore
+})
+```
+
+| Member                  | Description                                                                                                              |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `inject(request)`       | In-memory request through the HTTP plugin: `{ method = 'GET', url, headers?, body?, query?, cookies?, signedCookies? }`. |
+| `injectSse(request)`    | An event stream (Server-Sent Events) read in memory like `EventSource` (see below).                                      |
+| `injectStream(request)` | In-memory request resolving at the response headers, its `body` a `ReadableStream` read as it is produced.               |
+| `get(key)`              | `app.container.get(key)` (class, token, alias or display name).                                                          |
+| `close()`               | Stops the application (idempotent). Also `await using app = await TestApp.create(...)`.                                  |
+| `app` / `container`     | The `Application` and its `Container`.                                                                                   |
+
+`inject()` resolves with `{ status, headers, body, bytes, cookies, json() }` (`body` decoded as
+UTF-8, `bytes` the raw body, for downloads, `cookies` the `set-cookie` headers parsed by name); it
+rejects with `ZNIGHT001` when the application has no HTTP plugin and with `ZNIGHT021` once closed.
+The plugin encodes the request `body`: strings and bytes as is, a `FormData` as
+`multipart/form-data` (files included), a `Blob` / `File` with its type, other values as JSON.
+
+Cookies make round trips: `cookies` sends values in a `cookie` header (after any `cookie` header of
+`headers`), `signedCookies` sends values the HTTP plugin signs with its current secret first (a valid
+`@SignedCookie`), and each `response.cookies[name]` (`SetCookieInfo`: `value`, `raw`, `expires`,
+`maxAge`, `domain`, `path`, `secure`, `httpOnly`, `sameSite`, `partitioned`, `priority`) can be sent
+back as is:
+
+```ts
+const login = await app.inject({ method: 'POST', url: '/auth/login', body: { email, password } })
+expect(login.cookies['session']).toMatchObject({ httpOnly: true, secure: true, sameSite: 'lax' })
+
+const me = await app.inject({ url: '/auth/me', cookies: { session: login.cookies['session']?.value ?? '' } })
+const forged = await app.inject({ url: '/auth/me', signedCookies: { session: 'u-1' } })
+```
+
+Event streams (`@Sse` routes, `HttpResponse.sse()`) never end, so `inject()` rejects them; read
+them with `injectSse()`. Events are read only when asked for, and leaving the `await using` block
+(or `close()`) disconnects: the server sees `ctx.signal` abort.
+
+```ts
+test('order events', async () => {
+  await using stream = await app.injectSse({ url: '/orders/o-1/events' })
+  expect(stream.status).toBe(200)
+  expect(stream.retry).toBe(5_000)
+
+  app.get(OrderHub).publish({ orderId: 'o-1', sequence: 42, type: 'status', status: 'paid' })
+  const event = await stream.next() // rejects after 2 000 ms by default
+  expect(event).toMatchObject({ event: 'status', id: '42' })
+  expect(event.json()).toMatchObject({ status: 'paid' })
+
+  const resumed = await stream.reconnect() // the same request plus `last-event-id: 42`, like EventSource
+  await resumed.close()
+})
+```
+
+`injectSse()` resolves with `{ status, headers, cookies, body, json(), next({ timeoutMs? }),
+take(count), comments, lastEventId, retry, done, close(), reconnect() }`, an async iterable of
+`{ event, data, id, json() }` messages; `body` is the whole body when the answer is not an event
+stream (a 404, a 204). `injectStream()` resolves with `{ status, headers, cookies, body }` (cancel
+`body`, or abort `signal`, to disconnect). Both reject with `ZNIGHT001` when the plugin named `'http'`
+does not implement them (hint: `HttpPlugin` of `@znight/http` ≥ 0.1.0, the release that ships
+streaming), and with `ZNIGHT021` once closed.
+
+```ts
+import { readFile } from 'node:fs/promises'
+
+test('uploads and downloads', async () => {
+  const form = new FormData()
+  form.append('title', 'Me')
+  form.append('avatar', new File([await readFile('test/fixtures/me.png')], 'me.png', { type: 'image/png' }))
+
+  const uploaded = await app.inject({ method: 'POST', url: '/profile/avatar', body: form })
+  expect(uploaded.status).toBe(201)
+
+  const download = await app.inject({ url: '/reports/q1.pdf', headers: { range: 'bytes=0-99' } })
+  expect(download.status).toBe(206)
+  expect(download.bytes.byteLength).toBe(100)
+})
+```
+
+## Mocks
+
+```ts
+import { createMock } from '@znight/testing'
+
+const repository = createMock(UserRepository) // Mocked<UserRepository>, instanceof UserRepository
+const logger = createMock<Logger>() // from an interface
+const client = createMock<HttpClient>({ baseUrl: 'http://test', get: async () => ({ ok: true }) })
+const db = createMock<Database>(undefined, { deep: true }) // db.select().from('users')
+```
+
+- Every property read returns a spy, created on first access and then stable. Spies are deep:
+  `mock.pool.query.mockResolvedValue(rows)`.
+- Unconfigured methods return `undefined`, or with `{ deep: true }` a deep mock (the same one on
+  every call, so fluent APIs work).
+- Mocks are **not thenable** and inert for serialisers: `then`, `toJSON`, `asymmetricMatch`,
+  `$$typeof`, `nodeType`, `tagName`, `__esModule`, `@@...` and every symbol (`Symbol.toPrimitive`,
+  `Symbol.iterator`...) read as `undefined`. `await mock`, `JSON.stringify(mock)` (`{}`), `String(mock)`
+  and equality matchers behave.
+- `Object.prototype` members (`toString`, `hasOwnProperty`...) are the real ones.
+- Assigned properties win: `mock.enabled = false`. With a class, getters read as `undefined` (not a
+  truthy spy) until assigned.
+- Functions of the partial implementation become spies running that implementation.
+
+| Helper                                   | Description                                                  |
+| ---------------------------------------- | ------------------------------------------------------------ |
+| `createMock(Class?, partial?, options?)` | Deep auto-mock. Options: `name`, `deep`, `mockFn`.           |
+| `isMock(value)`                          | Whether `value` is a mock (or one of its spies).             |
+| `clearMock(mock)`                        | `mockClear()` on every spy of the mock.                      |
+| `resetMock(mock)`                        | Back to the initial state (programmed behaviours forgotten). |
+
+## Spies
+
+The spy implementation is detected when a mock is created:
+
+1. Vitest: `globalThis.vi.fn` (Vitest with `globals: true`);
+2. Jest: `globalThis.jest.fn`;
+3. `bun:test`: `mock` (loaded only when running on Bun). Bun's `expect(...).toHaveBeenCalled()`
+   only accepts genuine Bun mocks: they are used as is (deep members are added without wrapping
+   them in a proxy);
+4. otherwise the built-in spy, `createSpy()`: dependency-free and Jest-compatible (`mock.calls`,
+   `mock.results`, `mock.instances`, `mock.contexts`, `mock.invocationCallOrder`, `mock.lastCall`,
+   `mockReturnValue(Once)`, `mockResolvedValue(Once)`, `mockRejectedValue(Once)`,
+   `mockImplementation(Once)`, `mockReturnThis`, `mockName`, `mockClear`, `mockReset`,
+   `mockRestore`). It is recognised by Jest's and Vitest's `expect` (`_isMockFunction`).
+
+Force one with the `mockFn` option, or for the whole test suite in a setup file:
+
+```ts
+// vitest.setup.ts (Vitest without globals)
+import { vi } from 'vitest'
+import { setDefaultMockFn } from '@znight/testing'
+
+setDefaultMockFn(vi.fn) // vi.clearAllMocks() / vi.resetAllMocks() then apply to Znight mocks too
+```
+
+`setDefaultMockFn()` without argument restores auto-detection; `'builtin'` forces the built-in spy.
+Depending on the framework, a spy's own `mockReset()` may drop the implementation it was created
+with (`bun:test` does, the built-in spy restores it); `resetMock()` / `mocks.resetAll()` always restore
+it (partial implementations, deep returns).
+
+## Hand-written metadata
+
+For tests that do not run the compiler (plugins, libraries, edge cases), write the metadata by hand:
+
+```ts
+import { createMetadata, defineTestMetadata, testToken } from '@znight/testing'
+
+// class-first: tokens derived from class names (test#UserService), factories = new Class(...deps)
+const metadata = defineTestMetadata({
+  providers: [
+    PgUserRepository,
+    { class: UserService, deps: [PgUserRepository, '@znight/observability#Logger', { lazy: AuditService }] },
+    { token: 'src/db.ts#DbFactory.url', factory: () => 'postgres://', name: 'url' },
+  ],
+  aliases: [[UserRepository, PgUserRepository]],
+  externals: ['@znight/observability#Logger'],
+  extensions: { http: { controllers: [{ token: testToken(UserController), basePath: '/users', routes: [] }] } },
+})
+
+// exact compiler shape (resolution order computed)
+const raw = createMetadata({
+  'src/clock.ts#Clock': { scope: 'singleton', class: Clock, deps: [], factory: () => new Clock() },
+})
+```
+
+| `TestProvider` field                                                     | Description                                                                     |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
+| `class`                                                                  | Provider class (`container.get(Class)`).                                        |
+| `token`                                                                  | Default `<tokenPrefix>#<ClassName>` (`tokenPrefix` defaults to `test`).         |
+| `deps`                                                                   | Classes or tokens, `{ token, optional: true }`, `{ multi: [...] }`, `{ lazy }`. |
+| `factory`                                                                | Default `deps => new Class(...deps)`.                                           |
+| `scope`, `async`, `interceptors`, `dispose`, `name`, `primary`, `source` | As in `ProviderDefinition`.                                                     |
+
+## Overrides helpers
+
+```ts
+import { override, overrideFactory } from '@znight/testing'
+
+overrides: [
+  override(Clock, fixedClock), // type-checked against Clock
+  overrideFactory(UserRepository, ([db]) => new InMemoryUserRepository(db), { deps: ['src/db.ts#Database'] }),
+]
+```
+
+## Compiler contract
+
+`@znight/testing` exports **no helper called by generated code**: the compiler never imports it. It
+consumes the generated metadata through the documented runtime shapes only (architecture §3 and §9),
+without importing any feature package:
+
+| Metadata                                                                                           | Used by                                      |
+| -------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `providers[token].{ class, deps, factory, async, interceptors, name, source }`                     | `TestBed` (target factory, dependency kinds) |
+| `aliases`, `externals`                                                                             | key lookups, error messages                  |
+| `extensions.config.configs[].{ token, prefix, fields[].{ property, type, default } }`              | `TestBed` configuration instances            |
+| `extensions.http.controllers[].{ token, guards, interceptors, routes[].{ guards, interceptors } }` | `TestApp` boot roots                         |
+| `extensions.messaging.consumers[].token`                                                           | `TestApp` boot roots                         |
+| `extensions.schedule.jobs[].token`                                                                 | `TestApp` boot roots                         |
+
+Runtime contract with `@znight/http`: the plugin named `'http'` exposes
+`inject(request: { method: string; url: string; headers?; body?; query?; cookies?; signedCookies? }): Promise<{ status: number; headers; body: string; bytes?: Uint8Array; cookies?: Record<string, SetCookieInfo>; json<T>(): T }>`
+(`HttpInjector`, `HttpInjectResult`), dispatching in memory. `TestApp` forwards every request field
+as is (signing `signedCookies` is the plugin's job), returns the plugin's response as is when it has
+`bytes` and `cookies`, and otherwise derives `bytes` from `body` and returns no cookies (`{}`).
+`TestApp.injectStream()` / `injectSse()` delegate the same way to the optional
+`injectStream(request)` / `injectSse(request)` members of that plugin (`HttpStreamInjector`:
+`HttpPlugin` of `@znight/http` ≥ 0.1.0), the method defaulting to `GET`; the response shapes are
+`InjectStreamResponse` and `InjectSseResponse` (structural copies of the `@znight/http` types).
+
+Runtime contract with every plugin: the optional `initRoots(context: { metadata }): readonly ProviderKey[]`
+member of `Plugin` (`@znight/core`; `PluginInitRoots` names a plugin implementing it) returns the
+providers (classes or tokens) the plugin resolves at boot that the metadata does not make entry
+points: the classes given in its options, or providers it derives from its own metadata section
+(`context.metadata`). `TestApp.create()` calls it once, before creating the application, and adds
+the keys that designate providers of the metadata to the providers instantiated at boot (other keys
+are ignored: the plugin reports them); it rejects with a `TypeError` when the result is not an
+array. `HttpPlugin` returns the classes of its `guards`, `interceptors` and `exceptionMappers`
+options (nothing when the options are a function of the container).