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
#

11 declarations

view source

bootstrap_test_account
#

testing/app_server.ts view source

(options: BootstrapTestAccountOptions): Promise<{ account: { id: string; username: string; }; actor: { id: string; }; 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; username: string; }; actor: { id: string; }; 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
#

CreateTestAppOptions
#

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.

TEST_COOKIE_SECRET
#

TestAccount
#

testing/app_server.ts view source

TestAccount

A bootstrapped test account with credentials.

account

type {id: string; username: string}

actor

type {id: string}

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

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_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: string; username: string}

actor

The actor linked to the account.

type {id: string}

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>

Depends on
#

Imported by
#