Collects mock plugin definitions and real plugins, produces the
IPlugin[] for createTestApp, and resets between tests.
-
mock(): thisname: string,service: object,options?: { provides?: string; priority?: number; }
Registers a mock service under a capability token.
-
plugin(plugin: IPlugin): this
Stores a real plugin.
-
plugins(): IPlugin[]
Returns all plugins in true insertion order.
-
reset(): void
Clears the store. Call in
afterEachto reset between tests.
In-memory IResponse double with snapshot() and ended getter.
-
appendHeader(): IResponsename: string,value: string
Appends a response header, preserving any existing values for the same name rather than replacing them (unlike
IResponse.header, which overwrites). This is the correct way to emit multiple headers of the same name — most notably severalSet-Cookieheaders (e.g. an access cookie plus a refresh cookie, or deleting several cookies at once). - ended(): boolean
-
header(): IResponsename: string,value: string
Sets a response header.
-
html(_body: string): HandlerResult
Terminal HTML response — mirrors the kernel builder's
html(), so a test asserting on the double cannot pass where the real builder would fail. -
json<T>(_body: T): HandlerResult
Sends a JSON response.
-
redirect(): HandlerResulturl: string,_status?: number
Sends a redirect response.
-
send(_body?: Uint8Array): HandlerResult
Sends a raw byte response.
-
snapshot(): ResponseSnapshot
Returns a snapshot of the current response state (status, headers, body). Enables middleware to inspect the response after
next()returns — required for transparent response caching. -
status(code: number): IResponse
Sets the response status code.
-
stream(body: ReadableStream<Uint8Array>): HandlerResult
Sends a streaming response body.
-
text(_body: string): HandlerResult
Sends a plain-text response.
In-memory IServiceRegistry with registration recording.
-
get<T extends object>(token: CapabilityToken): T
Resolves a service by capability token.
-
getAll<T extends object>(token: CapabilityToken): readonly T[]
Resolves every provider registered for a multi-provider token.
-
has(token: CapabilityToken): boolean
Reports whether a capability is available.
-
register<T extends object>(): voidtoken: CapabilityToken,service: T,options?: RegisterOptions
Registers a service instance under a capability token.
-
registerFactory<T extends object>(): voidtoken: CapabilityToken,factory: ServiceFactory<T>,options?: RegisterOptions
Registers a lazy factory: the service is instantiated on first
getand cached for subsequent lookups. -
registrations(): ReadonlyArray<{ token: string; multi: boolean; }>
Records every
register/registerFactorycall, in order. -
unregister(token: CapabilityToken): boolean
Removes a registration. On a multi-provider token this removes EVERY provider registered under it, not just the first.
Collects a web Response body incrementally via a ReadableStream reader.
Creates an IPlugin that registers a mock service under a capability token.
Creates a started test application that can be exercised via inject()
and fetch() without binding a socket.
Builds a contract-faithful IRequestContext for unit-testing middleware
and handlers in isolation (no started app needed).
Free-function HTTP request injector with string, InjectRequest, and
web-standard Request shorthand.
Creates a plugin that REPLACES an already-provided capability with a test double, leaving the rest of the application's composition intact.
Kernel application extends IApplication with inject() capability.
-
hasPlugin(name: string): boolean
Reports whether a plugin carrying this name is pending.
-
inject(request: InjectRequest): Promise<InjectResponse>
Synthesizes an incoming request and runs it through the full pipeline without requiring a listening server.
-
unregister(name: string): boolean
Removes a pending plugin by name before the application starts.
Inject request shape for IKernelApplication.inject.
-
body: unknown
Request body (will be stringified if not a string).
-
headers: Record<string, string> | Headers
Request headers.
-
method: string
HTTP method.
-
url: string
Full request URL.
Inject response shape returned by IKernelApplication.inject.
-
body: string | null
Raw response body as text. A byte body (from
response.send(bytes)) is UTF-8 decoded;nullonly when the response genuinely has no body. -
headers: Headers
Response headers.
-
json<T>(): T
Parses the response body as JSON.
-
statusCode: number
Response status code.
Options for createMockPlugin.
-
name: string
Plugin name (also used as the capability token when
providesis absent). -
priority: number
Registration priority; passed through to the kernel resolver. Omitted when not needed (the returned plugin omits
prioritytoo). -
provides: string
Capability token this plugin provides. Defaults to
name. Override when the plugin name differs from the capability token. -
register: (ctx: IPluginContext) => void | Promise<void>
Additional registration callback invoked during
register(ctx). Useful for registering middleware, routes, or lifecycle hooks alongside the mock service. -
service: object
The mock service object to register.
Parsed body returned by collectStream.
-
chunks: Uint8Array[]
Individual chunks as they arrived from the stream.
-
text: string
The concatenated body decoded as UTF-8 text.
Composition-root arm of TestAppOptions: the test starts from the
application the project actually ships and subtracts from it.
-
app: IKernelApplication
An already-constructed, not yet started application — typically the
createApp()a scaffolded project exports fromsetu.config.ts, or a starter factory's return value. -
autoStart: boolean
Whether to auto-start the application.
-
overrides: readonly IPlugin[]
Plugins to append after
withoutis applied — usuallyoverrideCapabilityresults, though anyIPluginis accepted. -
plugins: never
Not available on this arm — supply
pluginsorapp, never both. -
without: readonly string[]
Plugin names to drop before
start(), so theirregister()never runs and any eager side effect inside it never happens.
Hand-assembled arm of TestAppOptions: the test names the plugins
it wants and gets nothing else.
-
app: never
Not available on this arm — supply
pluginsorapp, never both. -
autoStart: boolean
Whether to auto-start the application.
-
overrides: never
Not available on this arm — supply
pluginsorapp, never both. -
plugins: IPlugin[]
Plugins to pre-register before
start(). Must include a runtime capability provider (RuntimePlugin()or a mock providingCAPABILITIES.RUNTIME) whenautoStartistrue— the kernel throws otherwise. -
without: never
Not available on this arm — supply
pluginsorapp, never both.
Options for createTestContext.
-
body: unknown
Body backing
json()/text()/bytes()on the mock request. -
params: Record<string, string>
Path parameters — defaults to
{}. -
query: Record<string, string>
Query string parameters — defaults to parse from the request URL's search params.
-
request: Partial<IRequest>
Partial
IRequestoverrides (method, url, headers, etc.). -
response: IResponse
Response builder — defaults to
new MockResponse(). -
runtime: IRuntimeServices
Runtime services — when absent, the internal default is used.
-
services: IServiceRegistry
Service registry — defaults to
new MockServiceRegistry(). -
signal: AbortSignal
Abort signal for
ctx.signal. Precedence isoptions.request.signal>options.signal> a live, never-abortingAbortController().signal—request.signalwins because that is the kernel's own rule (request.signal ?? NEVER_ABORT_CONTROLLER.signal). -
startTime: number
Direct
startTimeoverride — highest precedence:options.startTime ?? options.runtime?.hrtime() ?? 0. Must be a monotonic reading, neverDate.now(). -
state: Map<string, unknown>
Request-scoped state — defaults to
new Map().
Usage
import * as _setu_ts_testing__First_party_testing_utilities_for_the_Setu_TS_framework__a_test_application_factory__mock_plugin_builder__request_injector__mock_request_context__service_registry_double__response_builder__fixture_manager__and_streaming_response_reader_ from "testing/src/index.ts";