Inspect the build graph

inspectBuild returns a read-only snapshot of a FlareHost and an optional built app. Use it in tests or diagnostics when you need to assert on registrations, routing, or compile state without sending a request. Without it, asserting on route count or registration totals means reaching into the host’s private fields, which are internal and free to shift between releases; inspectBuild exposes the same state through a stable read-only seam, so the assertion survives a refactor of those internals.

Callable before or after host.build(). Pre-compile sections return empty or partial data (for example http.compiled === false and an empty route list).

Basic usage

import { FlareHost, FlareResponse } from "@flare-ts/core";
import { node } from "@flare-ts/core/node";
import { inspectBuild } from "@flare-ts/core/testing";

const host = new FlareHost(node);
host.http.get("/ping", () => new FlareResponse(200, { ok: true }));

const before = inspectBuild({ host });
// before.http.compiled === false

const app = host.build();
const after = inspectBuild({ host, app });
// after.http.compiled === true

Pass app to populate the AppInspectSnapshot fields present and isTestApp. requestIdHeader and requestTiming come from host config either way.

Snapshot shape

BuildSnapshot has three top-level fields:

Field	Type	Contents
host	HostInspectSnapshot	Build state, merged config, runtime, lifecycle, registration counts, singleton keys, test mode flags, httpCompiled
http	HttpArcInspectSnapshot	compiled, route list, per-route pipelines, router, usesSharedContainer
app	AppInspectSnapshot	Whether an app instance was passed, test-app flag, request ID / timing config

Host fields worth probing

• host.registrations: counts of scoped services, singletons, controllers, middleware
• host.singletonKeys: registered singleton token names
• host.testMode.enabled: whether FLARE_MODE=test latched at host construction
• host.testMode.singletonsCompiled: whether singletons were instantiated (false until app.test() in test mode)

HTTP arc fields worth probing

• http.routes: registered route patterns as strings
• http.pipelines: each entry has route, score, execCount (middleware + handler steps), hasCors
• http.router: when compiled, exposes routeCount, maxDepth, and match(path) / lastMatchSegments(path) probes

import { strict as assert } from "node:assert";

const snap = inspectBuild({ host, app });
assert.equal(snap.http.router?.routeCount, 1);
assert.ok((snap.http.router?.match("/ping") ?? -1) >= 0);

Typical assertions

• Registration smoke test: after composing a host in a test helper, assert snap.host.registrations.controllers === 3 before calling build().
• Router probe: after build(), assert snap.http.router?.match("/users/42") resolves the expected route index.
• Pipeline depth: assert snap.http.pipelines[0]?.execCount reflects middleware you registered on a group.
• Test mode: assert snap.host.testMode.enabled when debugging why app.test() throws.

inspectBuild does not mutate the host. It is safe to call multiple times on the same instance.

Related

• Build-time validation: what build() validates
• What build() does: compile vs bundle
• Testing: integration and unit helpers alongside inspectBuild