testing/app_server.ts

Bootstrapped app server factory for integration tests.

Creates a keeper account, API token, and signed session cookie on a database. By default uses a cached in-memory PGlite (shared WASM instance per vitest worker thread via test_db.ts module cache); pass db to use an existing database (any driver) instead.

Also provides create_test_app — a combined helper that creates both a TestAppServer and a fully assembled Hono app with middleware and routes.

Declarations
#

12 declarations

view source

bootstrap_test_account
#

testing/app_server.ts view source

(options: BootstrapTestAccountOptions): Promise<{ account: { id: string & $brand<"Uuid">; username: string; }; actor: { id: string & $brand<"Uuid">; }; api_token: string; session_cookie: string; }>

Bootstrap a test account with credentials.

Creates an account with actor, grants roles, creates an API token, creates a session, and signs a session cookie. Shared by create_test_app_server and TestApp.create_account.

options

type BootstrapTestAccountOptions

returns

Promise<{ account: { id: string & $brand<"Uuid">; username: string; }; actor: { id: string & $brand<"Uuid">; }; api_token: string; session_cookie: string; }>

BootstrapTestAccountOptions
#

create_test_app
#

testing/app_server.ts view source

(options: CreateTestAppOptions): Promise<TestApp>

Create a fully assembled test app with a Hono server, middleware, and routes.

Combines create_test_app_server + create_app_server into a single call. Disables rate limiters and logging by default (test-friendly).

A fresh Hono app is created each call — middleware closures bind to the server's deps (db, keyring), so reuse across servers is unsafe. The expensive resource (PGlite WASM) is cached separately in test_db.ts.

options

test app configuration

type CreateTestAppOptions

returns

Promise<TestApp>

a TestApp ready for HTTP testing

create_test_app_server
#

testing/app_server.ts view source

(options: TestAppServerOptions): Promise<TestAppServer>

Create an app server with a bootstrapped account for testing.

Sets up: - Auth tables (via cached PGlite factory, or reuses existing db) - A keeper account with hashed password - Role role_grants for each role in options.roles - An API token for Bearer auth - A session with a signed cookie value

Uses stub_password_deps by default — deterministic hashing that works correctly for login/logout tests without Argon2 overhead.

options

session options and optional overrides

type TestAppServerOptions

returns

Promise<TestAppServer>

a TestAppServer ready for HTTP testing

CreateTestAppOptions
#

testing/app_server.ts view source

CreateTestAppOptions

Configuration for create_test_app.

inheritance

create_route_specs

Route spec factory — called with the assembled AppServerContext.

type (context: AppServerContext) => Array<RouteSpec>

rpc_endpoints

RPC endpoints mounted by create_app_server — eager array or (ctx: AppServerContext) => Array<RpcEndpointSpec> factory. Symmetric with the suite-level rpc_endpoints option on describe_standard_admin_integration_tests etc., so callers wiring a full RPC stack don't have to switch shapes between low-level and suite-level helpers. Equivalent to app_options.rpc_endpoints; when both are set app_options wins and console.warn fires.

type RpcEndpointsSuiteOption

app_options

Optional overrides for AppServerOptions (backend, session_options, and create_route_specs are managed).

type Partial< Omit<AppServerOptions, 'backend' | 'session_options' | 'create_route_specs'> >

stub_password_deps
#

testing/app_server.ts view source

PasswordHashDeps

Fast password stub for tests that don't exercise login/password flows.

Hashes are deterministic (stub_hash_<password>) and verify correctly, so auth bootstrap and session creation work without Argon2 overhead.

SuiteAppOptions
#

testing/app_server.ts view source

Partial<Omit<AppServerOptions, "backend" | "session_options" | "create_route_specs" | "rpc_endpoints">>

app_options shape accepted by DB-backed suite helpers (describe_standard_integration_tests, describe_audit_completeness_tests, etc.). Excludes rpc_endpoints on top of the fields CreateTestAppOptions excludes — suites require rpc_endpoints at the suite level (hard-failed by require_rpc_endpoint_path) so setup-time path lookup and runtime dispatch read from one source of truth. Low-level create_test_app callers still pass rpc_endpoints via app_options.

TEST_COOKIE_SECRET
#

TestAccount
#

testing/app_server.ts view source

TestAccount

A bootstrapped test account with credentials.

account

type {id: Uuid; username: string}

actor

type {id: Uuid}

session_cookie

Signed session cookie value.

type string

api_token

Raw API token for Bearer auth.

type string

create_session_headers

Build request headers with this account's session cookie.

type (extra?: Record<string, string>) => Record<string, string>

create_bearer_headers

Build request headers with this account's Bearer token.

type (extra?: Record<string, string>) => Record<string, string>

TestApp
#

testing/app_server.ts view source

TestApp

A fully assembled test app — Hono app + backend + helpers.

app

type Hono

backend

type TestAppServer

surface_spec

type AppSurfaceSpec

surface

type AppSurface

route_specs

type Array<RouteSpec>

create_session_headers

Build request headers with the bootstrapped session cookie.

type (extra?: Record<string, string>) => Record<string, string>

create_bearer_headers

Build request headers with the bootstrapped Bearer token.

type (extra?: Record<string, string>) => Record<string, string>

create_daemon_token_headers

Build request headers with the daemon token (keeper auth).

type (extra?: Record<string, string>) => Record<string, string>

create_account

Create an additional account with credentials.

type (options?: { username?: string; password_value?: string; roles?: Array<string>; }) => Promise<TestAccount>

cleanup

Cleanup resources (delegates to TestAppServer.cleanup).

type () => Promise<void>

TestAppServer
#

testing/app_server.ts view source

TestAppServer

An AppBackend with a bootstrapped account, API token, and session cookie.

inheritance

extends:

account

The bootstrapped account.

type {id: Uuid; username: string}

actor

The actor linked to the account.

type {id: Uuid}

api_token

Raw API token for Bearer auth.

type string

session_cookie

Signed session cookie value for cookie auth.

type string

keyring

Keyring used for cookie signing — exposed for forging expired/tampered cookies in tests.

type Keyring

cleanup

Release test resources (no-op when DB is injected or factory-cached).

type () => Promise<void>

TestAppServerOptions
#

testing/app_server.ts view source

TestAppServerOptions

Configuration for create_test_app_server.

session_options

Session options — needed for cookie signing.

type SessionOptions<string>

db

Existing database — skips internal DB creation when provided. Caller owns the DB lifecycle.

type Db

db_type

Database driver type — only used when db is provided. Default: 'pglite-memory'.

type DbType

password

Password implementation. Default: stub_password_deps. Pass argon2_password_deps for tests that exercise login.

type PasswordHashDeps

username

Username for the bootstrapped account. Default: 'keeper'.

type string

password_value

Password for the bootstrapped account. Default: 'test-password-123'.

type string

roles

Roles to grant. Default: [ROLE_KEEPER].

type Array<string>

on_audit_event

Backend audit event callback — threaded into create_audit_emitter so it becomes the first listener on backend.deps.audit.on_event_chain. When audit_log_sse: true is passed to create_app_server, the SSE listener is appended after this one. Use to wire consumer SSE auth guards in tests. Default: no-op.

type (event: AuditLogEvent) => void

audit_log_config

Optional audit log config — threaded into create_audit_emitter and captured inside backend.deps.audit's closure.

Use when the consumer registers extra event types via create_audit_log_config({extra_events}) — without this, emits for those events fall back to BUILTIN_AUDIT_LOG_CONFIG and log "unknown event_type" warnings.

type AuditLogConfig

Depends on
#

Imported by
#