testing/cross_backend/spawn_backend.ts

Spawn a test backend binary, wait for it to come up, and return a handle the test harness drives.

Lifecycle:

  1. Write the bootstrap token (config.bootstrap.token) to config.bootstrap.token_path so the binary picks it up at startup.
  2. child_process.spawn(...) the binary with detached: true — creates a new process group so a SIGTERM to the negative PID tears down any descendants the binary spawned (PTYs, child workers). vitest worker death + Ctrl+C handlers also fire the group teardown so ports never strand.
  3. Poll {base_url}{health_path} until it returns 2xx or startup_timeout_ms elapses.
  4. Read config.bootstrap.daemon_token_path to load the binary's deterministic daemon token; thread it onto BackendHandle so _testing_reset and other keeper-credential calls can authenticate.

Bootstrapping (POST /api/account/bootstrap) is a separate concern — the caller composes bootstrap() from testing/transports/bootstrap.ts against a FetchTransport built around handle.config.base_url. Splitting the two keeps spawn_backend consumer-agnostic — fuz_app knows nothing about specific binary contents.

view source

Declarations
#

2 declarations

BackendHandle
#

testing/cross_backend/spawn_backend.ts view source

BackendHandle import type {BackendHandle} from '@fuzdev/fuz_app/testing/cross_backend/spawn_backend.js';

Handle returned by spawn_backend — passed to per-test setup helpers.

config

The config used to spawn this backend. Carried for diagnostic + downstream access.

type BackendConfig

readonly

child

Child process reference — exposed for diagnostic logging only.

type ChildProcess

readonly

daemon_token

Deterministic daemon token captured from config.bootstrap.daemon_token_path after the binary booted. default_cross_process_setup builds keeper-daemon-token headers from this for _testing_reset calls.

type string

readonly

teardown

SIGTERM the child's process group, drain stderr, await exit. Idempotent — calls after the first are no-ops.

type () => Promise<void>

readonly

spawn_backend
#

testing/cross_backend/spawn_backend.ts view source

(config: BackendConfig): Promise<BackendHandle> import {spawn_backend} from '@fuzdev/fuz_app/testing/cross_backend/spawn_backend.js';

Spawn config.start_command and return a handle once the binary is health-probe-ready and the daemon-token file is readable.

Errors at any stage SIGTERM the child group before rethrowing — the caller never sees a half-started backend.

config

type BackendConfig

returns

Promise<BackendHandle>

Depends on
#

Imported by
#