testing/middleware.ts

Table-driven middleware test helpers.
Provides mock builders for bearer auth middleware dependencies,
a generic test runner that iterates case tables, and a reusable
middleware stack factory for integration testing.

Declarations
#

11 declarations

view source

BearerAuthMocks
#

testing/middleware.ts view source

BearerAuthMocks

Mocks bundle returned by create_bearer_auth_mocks.

`mock_validate`

type ReturnType<typeof vi.fn>

`mock_find_by_id`

type ReturnType<typeof vi.fn>

`mock_find_by_account`

type ReturnType<typeof vi.fn>

`mock_find_active_for_actor`

type ReturnType<typeof vi.fn>

BearerAuthTestCase
#

testing/middleware.ts view source

BearerAuthTestCase

A full test case for the table-driven bearer auth runner.

inheritance

extends:

BearerAuthTestOptions

`validate_expectation`

Whether the request should reach token validation or be short-circuited.

type 'called' | 'not_called'

`assert_context_set`

If true, assert REQUEST_CONTEXT_KEY and CREDENTIAL_TYPE_KEY were set to api_token values.

type boolean

`assert_context_preserved`

If true, assert the pre-existing session context and credential type are preserved.

type boolean

`assert_mocks`

Optional callback for custom spy assertions on the mocks bundle.

type (mocks: BearerAuthMocks) => void

BearerAuthTestOptions
#

testing/middleware.ts view source

BearerAuthTestOptions

Mock configuration for bearer auth middleware test setup.

`name`

Test description.

type string

`headers`

Request headers.

type Record<string, string>

`pre_context`

Pre-set request context (simulates session already resolved).

type RequestContext

`mock_validate_result`

What query_validate_api_token() returns.

type unknown

`mock_find_by_id_result`

What query_account_by_id() returns.

type unknown

`mock_find_by_account_result`

What query_actor_by_account() returns.

type unknown

`mock_permits_result`

What query_permit_find_active_for_actor() returns.

type unknown

`expected_status`

Expected HTTP status, or 'next' if the middleware should call next().

type number | 'next'

`expected_error`

Expected error field in JSON response body.

type string

`expected_error_schema`

Zod schema to validate error response body against. Defaults to ApiError when expected_error is set.

type z.ZodType

create_bearer_auth_mocks
#

testing/middleware.ts view source

(tc: BearerAuthTestOptions): BearerAuthMocks

Create mock dependencies for create_bearer_auth_middleware, configured per test case.
Configures the module-level mocks for query_validate_api_token,
query_account_by_id, query_actor_by_account, and query_permit_find_active_for_actor
so each test case controls return values independently.

`tc`

the test config providing mock return values

type BearerAuthTestOptions

returns

BearerAuthMocks

mocks bundle with spy references

create_bearer_auth_test_app
#

testing/middleware.ts view source

(tc: BearerAuthTestOptions, ip_rate_limiter?: RateLimiter | null): { app: Hono<BlankEnv, BlankSchema, "/">; mocks: BearerAuthMocks; }

Create a Hono app wired with create_bearer_auth_middleware using mocked deps.
The route handler at /api/test returns the resolved context in the response body,
enabling assertions on REQUEST_CONTEXT_KEY and CREDENTIAL_TYPE_KEY.

`tc`

the test config providing mock behavior

type BearerAuthTestOptions

`ip_rate_limiter`

optional rate limiter (null to disable)

type RateLimiter | null

default null

returns

{ app: Hono<BlankEnv, BlankSchema, "/">; mocks: BearerAuthMocks; }

the app and mocks bundle

create_test_middleware_stack_app
#

testing/middleware.ts view source

(options?: TestMiddlewareStackOptions | undefined): TestMiddlewareStackApp

Create a Hono app with real proxy + origin + bearer middleware for integration testing.
All DB queries return undefined (no real database needed).
The echo route at TEST_MIDDLEWARE_PATH returns {ok, client_ip, has_context}.

`options?`

middleware stack configuration

type TestMiddlewareStackOptions | undefined

optional

returns

TestMiddlewareStackApp

the app and mock spies (reconfigure via mockImplementation for valid-token paths)

describe_bearer_auth_cases
#

testing/middleware.ts view source

(suite_name: string, cases: BearerAuthTestCase[], ip_rate_limiter?: RateLimiter | null): void

Run a table of bearer auth middleware test cases.
Generates one test() per case inside a describe() block.

`suite_name`

the describe block name

type string

`cases`

the test case table

type BearerAuthTestCase[]

`ip_rate_limiter`

optional rate limiter shared across cases

type RateLimiter | null

default null

returns

void

TEST_CLIENT_IP
#

testing/middleware.ts view source

"127.0.0.1"

Default client IP set by the proxy stub in test apps.

TEST_MIDDLEWARE_PATH
#

testing/middleware.ts view source

"/api/test"

Path used by the echo route in create_test_middleware_stack_app.

TestMiddlewareStackApp
#

testing/middleware.ts view source

TestMiddlewareStackApp

Return type of create_test_middleware_stack_app.

`app`

type Hono

`mock_validate`

type ReturnType<typeof vi.fn>

`mock_find_by_id`

type ReturnType<typeof vi.fn>

`mock_find_by_account`

type ReturnType<typeof vi.fn>

`mock_find_active_for_actor`

type ReturnType<typeof vi.fn>

TestMiddlewareStackOptions
#

testing/middleware.ts view source

TestMiddlewareStackOptions

Options for create_test_middleware_stack_app.

`trusted_proxies`

Trusted proxy IPs.

type Array<string>

`allowed_origins`

Comma-separated allowed origin patterns.

type string

`connection_ip`

Connection IP or factory.

type string | (() => string | undefined)

`ip_rate_limiter`

Rate limiter for bearer auth.

type RateLimiter | null

Depends on
#

Imported by
#

testing/adversarial_headers.ts