TestAppHandle

class TestAppHandle

Integration-test handle returned by app.test() (where app came from host.build()).

Mirrors how FlareAppNode.run() returns a NodeRunHandle and FlareAppCF.export() returns a { fetch } handle; the test runtime’s analogue.

Sends synthetic requests through the full pipeline (routing, middleware, handler) without binding a port. Always resolves to a standard Web Response; the internal ResponseLike union is normalized before returning.

Each fetch call constructs a FlareRequest via the host’s adapter (createTestRequest), so the request adapter and native shape match what production code sees, preserving differences in signal(), background(), and raw header handling between Node and CF.

How you get one

new TestAppHandle(app, adapter, resetFn)

Constructor

new TestAppHandle(app: HostedApp, adapter: AnyAdapter, resetFn: ResetFn): TestAppHandle

app HostedApp

adapter AnyAdapter

resetFn ResetFn

Methods

fetch()

fetch(target: string, init?: TestRequestInit): Promise<Response>

Sends a synthetic request through the pipeline.

target string · "METHOD /path", e.g. "GET /users/123", "POST /chat".

init? TestRequestInit · Optional headers, body, and signal. body is unknown: bytes pass through, strings pass through, anything else is JSON-stringified and content-type: application/json is set if absent.

returns Promise<Response>

Throws:

When target is not a "METHOD /path" string.

reset()

reset(opts?: { replace?: ReadonlyMap<ServiceToken<FlareService>, ServiceClass> }): Promise<void>

Tears the test app down and re-runs the lifecycle with a new replace map.

Runs onStop, restores the original registrations, applies the new replacements, and starts again. The same handle keeps working; subsequent app.fetch() calls hit the new graph.

Use to swap services between scenarios inside a single test file without needing to split into separate files for each replacement set.

opts? { replace?: ReadonlyMap<ServiceToken<FlareService>, ServiceClass> }

returns Promise<void>

stop()

stop(): Promise<void>

Runs onStop() on all services in reverse dependency order.

Call in afterAll.

returns Promise<void>

Learn: Write your first test