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

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).

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
#

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

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
#

TEST_MIDDLEWARE_PATH
#

TestMiddlewareStackApp
#

TestMiddlewareStackOptions
#

testing/middleware.ts view source

TestMiddlewareStackOptions

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
#