testing/cross_backend/spine_suites.ts

One call that runs every shipped single-backend cross suite a backend's capabilities admit — describe_spine_cross_suites(handle, options).

A consumer's cross project otherwise wires one file per upstream suite, so a suite added here never reaches it unless someone adds the file. The one-call form runs SUITE_NAMES — the closed registry of shipped suites, each named by its module — and builds every suite's options from the handle: the paths, cookie name and capabilities from handle.config (to_cross_suite_options), the daemon token from the handle, and each suite's setup_test through default_cross_process_setup with whatever seeding that suite needs (the multi-actor keeper, the offer grantor, the cell role holder). Each suite gates its own cases on the capabilities, so a backend runs what it mounts.

Options are additive.

exclude names a suite with the reason it can't run on this backend; the reason is required and shows in the run as a skipped test, so a skip is stated in code and visible in the report. testing_backdoor can't be excluded, by suite or by case, nor its capabilities.testing_backdoors changed: it checks the declaration the backdoor gating reads.
exclude_cases names single tests of a suite that does run, each by its name path (describe titles and test name, joined with ' > ') with a required reason; one beforeEach skips them at run time, so each shows as skipped with its reason, and an entry matching no collected test of its suite fails the closing check test.
overrides replaces a suite's derived options, field by field (a shallow merge over what the handle gives) — a role list the backend's WS upgrade requires, an xfail for a tracked divergence, a narrower capability set. An entry can be a function of the derived options instead, for a change built on a derived value. A required option the merge leaves undefined throws at collection.
rpc_success_fixtures / rpc_skip_methods / rpc_input_overrides go to the standard bundle's RPC round-trip; rpc_input_overrides also seeds rpc_adversarial's params cases (each override is the valid base they break one field of). A key naming a method on neither the declared surface nor live_rpc_endpoints throws at collection.
ws_required_roles names the roles the backend's WS upgrade requires, so the suites that open sockets for accounts they create give them those roles.
suite_roles names the roles the role-shaped suites use when the backend's registry lacks the spine's own (cell_editor, participant); the call seeds the holder each needs.

Inputs the handle doesn't carry. The declared surface (surface_source, session_options, rpc_endpoints, roles) is a required option. Paths and roles that name what the reference spines mount (the role-gated WS endpoint and its roles) default to the SPINE_* constants, and a suite whose capability flag is off never reaches them. Anything else a suite needs comes from the handle when it can (session_cookie_codec's cookie_keys from the config's SECRET_FUZ_COOKIE_KEYS), else from overrides; when neither has it, the call throws naming the suite — provide it or exclude the suite.

Backdoors. The backend's capabilities.testing_backdoors must declare SPINE_SUITES_REQUIRED_BACKDOORS (the per-test reset and the audit barrier), and _testing_put_fact when it declares fact_serving; the call throws otherwise. A suite every case of which drives another backdoor (credential_deadline, origin_conformance, ws_outbound_overflow) skips itself on a backend not declaring it, shown like an exclude with a reason naming the backdoor — so an exclude, override or exclude_cases entry for it is refused as dead.

Not in the one call (STANDALONE_CROSS_SUITES, with the reasons): the suites that need two handles (the differential), a backend spawned with live limiters (login_security, ws_action_rate_limit — the standard suites would exhaust them), and the conformance runner, which runs the consumer's own cases. Each keeps its own entry point.

Suites are registered without a wrapping describe, so their test names are the same as when each is called on its own — and an exclude_cases path is the name the reporter prints after the file and any describe wrapping the call.

view source

Declarations
#

18 declarations

check_spine_case_exclusions
#

testing/cross_backend/spine_suites.ts view source

internal

(exclude_cases: Readonly<Partial<Record<"cell_crud" | "cell_relations" | "cell_gated_create" | "fact_serving" | "ready" | "ws_role_gated" | "account_lifecycle" | "origin" | "actor_lookup" | "app_settings" | ... 33 more ... | "ws_round_trip", Readonly<...>>>>, collected: ReadonlyMap<...>): void

import {check_spine_case_exclusions} from '@fuzdev/fuz_app/testing/cross_backend/spine_suites.js';

Check every exclude_cases entry against the test paths each suite collected — the static half of the case exclusions, which the closing test register_spine_case_exclusions registers runs.

`exclude_cases`

the entries, by suite

type

Readonly<Partial<Record<"cell_crud" | "cell_relations" | "cell_gated_create" | "fact_serving" | "ready" | "ws_role_gated" | "account_lifecycle" | "origin" | "actor_lookup" | "app_settings" | "body_size" | "body_size_smuggling" | "cell_grant_role" | "cell_grant_steward" | "cell_moderate" | "cell_ref_admission" | "cookie_attributes" | "credential_deadline" | "credential_header_robustness" | "identity_parity" | "origin_conformance" | "origin_scope" | "peer_ping_ws" | "query_shape" | "role_grant_offer_enumeration" | "role_grant_offer_lifecycle" | "role_grant_offer_notification_ws" | "role_grant_participation" | "role_grant_role_grammar" | "rpc_adversarial" | "session_cap" | "session_cookie_codec" | "simple_request" | "sse_round_trip" | "standard" | "testing_backdoor" | "token_lifetime" | "token_scope_surface" | "transport_composition" | "ws_connection_cap" | "ws_envelope" | "ws_inbound_dispatch" | "ws_outbound_overflow" | "ws_round_trip", Readonly<Record<string, string>>>>>

`collected`

each run suite's collected test paths

type ReadonlyMap<SuiteName, ReadonlySet<string>>

returns

void

throws

Error - naming every entry whose suite collected no test at its path

CrossSuiteHandleOptions
#

testing/cross_backend/spine_suites.ts view source

CrossSuiteHandleOptions import type {CrossSuiteHandleOptions} from '@fuzdev/fuz_app/testing/cross_backend/spine_suites.js';

The suite options a backend's BackendConfig supplies.

`capabilities`

type BackendCapabilities

readonly

`base_url`

type string

readonly

`rpc_path`

type string

readonly

`ws_path`

type string

readonly

`sse_path`

type string | undefined

readonly

`cookie_name`

type string

readonly

describe_spine_cross_suites
#

testing/cross_backend/spine_suites.ts view source

(handle: ReconstructedBootstrappedBackendHandle, options: SpineCrossSuitesOptions): void import {describe_spine_cross_suites} from '@fuzdev/fuz_app/testing/cross_backend/spine_suites.js';

Run every shipped single-backend cross suite against one spawned backend — see the module doc for what the options add and what stays outside.

`handle`

the backend, as inject_backend_handle() returns it

type ReconstructedBootstrappedBackendHandle

`options`

the declared surface, plus excludes, case exclusions and overrides

type SpineCrossSuitesOptions

returns

void

throws

Error - on an exclude with no reason, an unknown suite name, a suite both excluded and overridden, an excluded `testing_backdoor` (or one of its cases, or an override changing its `capabilities.testing_backdoors`), an exclude, override or `exclude_cases` entry for a suite that skips itself or isn't run, a backend not declaring `SPINE_SUITES_REQUIRED_BACKDOORS` (or `_testing_put_fact` with `fact_serving`), or a suite missing an input the handle doesn't carry

get_spine_suite_backdoors
#

testing/cross_backend/spine_suites.ts view source

internal

(name: "cell_crud" | "cell_relations" | "cell_gated_create" | "fact_serving" | "ready" | "ws_role_gated" | "account_lifecycle" | "origin" | "actor_lookup" | "app_settings" | "body_size" | ... 32 more ... | "ws_round_trip"): readonly ("_testing_reset" | ... 8 more ... | "_testing_shorten_credential_expiry")[]

import {get_spine_suite_backdoors} from '@fuzdev/fuz_app/testing/cross_backend/spine_suites.js';

The backdoors every case of name drives beyond SPINE_SUITES_REQUIRED_BACKDOORS — a backend not declaring one skips the suite.

`name`

the suite

type SuiteName

returns

readonly TestingBackdoorMethod[]

its SuiteEntry.backdoors, empty for a suite needing none

register_spine_case_exclusions
#

testing/cross_backend/spine_suites.ts view source

internal

(exclude_cases: Readonly<Partial<Record<"cell_crud" | "cell_relations" | "cell_gated_create" | "fact_serving" | "ready" | "ws_role_gated" | "account_lifecycle" | "origin" | "actor_lookup" | "app_settings" | ... 33 more ... | "ws_round_trip", Readonly<...>>>>, ranges: readonly SuiteTaskRange[]): void

import {register_spine_case_exclusions} from '@fuzdev/fuz_app/testing/cross_backend/spine_suites.js';

Skip the exclude_cases tests, and fail on an entry no collected test has. describe_spine_cross_suites calls it after registering the suites, in the same suite.

One beforeEach on the calling suite: it finds the test's top-level task among the ranges the suites registered, and calls ctx.skip(reason) when that suite's entries name the test's path — so the suite files stay as they are, and the test shows as skipped with its reason. A closing test holds every entry to a test its suite collected (check_spine_case_exclusions; the paths are read at collection, so a filtered run still checks them). A skipped test's own beforeEach hooks don't run, but its afterEach hooks and its suite's beforeAll still do.

`exclude_cases`

the entries, by suite

type

Readonly<Partial<Record<"cell_crud" | "cell_relations" | "cell_gated_create" | "fact_serving" | "ready" | "ws_role_gated" | "account_lifecycle" | "origin" | "actor_lookup" | "app_settings" | "body_size" | "body_size_smuggling" | "cell_grant_role" | "cell_grant_steward" | "cell_moderate" | "cell_ref_admission" | "cookie_attributes" | "credential_deadline" | "credential_header_robustness" | "identity_parity" | "origin_conformance" | "origin_scope" | "peer_ping_ws" | "query_shape" | "role_grant_offer_enumeration" | "role_grant_offer_lifecycle" | "role_grant_offer_notification_ws" | "role_grant_participation" | "role_grant_role_grammar" | "rpc_adversarial" | "session_cap" | "session_cookie_codec" | "simple_request" | "sse_round_trip" | "standard" | "testing_backdoor" | "token_lifetime" | "token_scope_surface" | "transport_composition" | "ws_connection_cap" | "ws_envelope" | "ws_inbound_dispatch" | "ws_outbound_overflow" | "ws_round_trip", Readonly<Record<string, string>>>>>

`ranges`

each run suite's top-level tasks in the calling suite

type readonly SuiteTaskRange[]

returns

void

SPINE_SUITES_REQUIRED_BACKDOORS
#

testing/cross_backend/spine_suites.ts view source

readonly ("_testing_reset" | "_testing_drain_effects" | "_testing_mint_session" | "_testing_put_fact" | "_testing_flood_notifications" | "_testing_schema_snapshot" | "_testing_migration_tracker" | "_testing_action_manifest" | "_testing_origin_check" | "_testing_shorten_credential_expiry")[]

type readonly TestingBackdoorMethod[]

import {SPINE_SUITES_REQUIRED_BACKDOORS} from '@fuzdev/fuz_app/testing/cross_backend/spine_suites.js';

The backdoors describe_spine_cross_suites requires of every backend, since the suites share them: _testing_reset is every setup_test's per-test reset, and _testing_drain_effects the barrier every audit read waits on. A backend whose capabilities.testing_backdoors lacks one fails at collection.

SpineCrossSuitesOptions
#

testing/cross_backend/spine_suites.ts view source

SpineCrossSuitesOptions import type {SpineCrossSuitesOptions} from '@fuzdev/fuz_app/testing/cross_backend/spine_suites.js';

Options for describe_spine_cross_suites.

`surface_source`

The declared surface — the standard bundle and rpc_adversarial enumerate it.

type AppSurfaceSpec

readonly

`session_options`

The backend's session config, for the standard bundle.

type SessionOptions<string>

readonly

`rpc_endpoints`

The backend's RPC endpoints, for the standard bundle.

type RpcEndpointsSuiteOption

readonly

`live_rpc_endpoints?`

The RPC endpoints the backend live-mounts, for the methods it keeps off the declared surface (cell verbs, opt-in resolvers, _testing_* backdoors); given, rpc_adversarial sends them bad envelopes and params too. A backend's whole live mount is a fine value — a declared method still runs once, from the declared surface.

type RpcEndpointsSuiteOption

readonly

`roles?`

The backend's role schema; given, the standard bundle runs its admin suite.

type RoleSchemaResult

readonly

`setup?`

Setup options every suite's setup_test starts from — a signup path the backend mounts elsewhere, reject_unknown_audit_metadata_keys for a backend's own spine suite. A suite's own seeding is added to it (the role, account and actor lists concatenate).

type CrossProcessSetupOptions

readonly

`exclude?`

Suites this backend doesn't run, each with a non-empty reason. Each shows in the run as one skipped test carrying the reason. Not testing_backdoor, nor a suite that already skips itself for an undeclared backdoor.

type Readonly<Partial<Record<SuiteName, string>>>

readonly

`exclude_cases?`

Single tests this backend doesn't run, by suite, each by its name path (SuiteCaseExclusions) with a non-empty reason; each shows in the run as skipped with its reason. An entry naming a suite the call doesn't run, testing_backdoor, or a path no collected test of that suite has, fails.

readonly

`overrides?`

Per-suite option overrides, a shallow merge over what the handle gives.

type SuiteOverrides

readonly

`suite_roles?`

The roles the role-shaped suites use, when the backend lacks the spine's own.

type SpineSuiteRoles

readonly

`ws_required_roles?`

The roles the backend's WS upgrade on ws_path requires (an admin-gated /api/ws: [ROLE_ADMIN]). Given, the suites that open sockets for accounts they create — credential_deadline, session_cap, ws_round_trip — create them holding these (ws_account_roles), and role_grant_offer_notification_ws expects revoking one to close the socket (ws_required_roles). Each must be admin-grantable.

type readonly string[]

readonly

`rpc_max_body_bytes?`

The backend's request-body cap on rpc_path, in bytes, when it isn't the spine default (SPINE_BODY_LIMIT_DEFAULT_BYTES): the boundary body_size, body_size_smuggling and transport_composition's RPC over-cap row probe.

type number

readonly

`ws_max_message_bytes?`

The backend's inbound WebSocket message cap on ws_path, in bytes, when it isn't the spine default (DEFAULT_WS_MAX_MESSAGE_BYTES): the boundary ws_round_trip's oversized-message case sends past.

type number

readonly

`rpc_success_fixtures?`

Forwarded to the standard bundle (StandardCrossProcessTestOptions.rpc_success_fixtures).

type RpcSuccessFixtures

readonly

`rpc_skip_methods?`

Forwarded to the standard bundle (StandardCrossProcessTestOptions.rpc_skip_methods).

type string[]

readonly

`rpc_input_overrides?`

Forwarded to the standard bundle (StandardCrossProcessTestOptions.rpc_input_overrides) and to rpc_adversarial (RpcAdversarialCrossTestOptions.input_overrides), where each override seeds the method's params cases. Those cases are sent as a single-actor principal, so an override omits acting. A key naming a method on neither the declared surface nor live_rpc_endpoints throws at collection.

type Map<string, Record<string, unknown>>

readonly

SpineSuiteRoles
#

testing/cross_backend/spine_suites.ts view source

SpineSuiteRoles import type {SpineSuiteRoles} from '@fuzdev/fuz_app/testing/cross_backend/spine_suites.js';

The roles the role-shaped suites use, for a backend whose registry lacks the spine's own. Set them here rather than in overrides: the call seeds the holder each needs.

`cell_grant?`

The role cell_grant_role's grants name, seeded on its holder at reset. Default SPINE_CELL_EDITOR_ROLE. ROLE_KEEPER serves a backend with only the builtin roles; ROLE_ADMIN can't (an admin reaches every cell).

type string

readonly

`conferral?`

The admin-grantable role role_grant_offer_lifecycle offers and role_grant_participation confers. Default SPINE_PARTICIPANT_ROLE; ROLE_ADMIN serves a backend with only the builtin roles (the scoped assign case then skips, as a builtin is global-only).

type string

readonly

STANDALONE_CROSS_SUITES
#

testing/cross_backend/spine_suites.ts view source

Readonly<Record<StandaloneSuiteName, string>>

type Readonly<Record<StandaloneSuiteName, string>>

import {STANDALONE_CROSS_SUITES} from '@fuzdev/fuz_app/testing/cross_backend/spine_suites.js';

The shipped suite modules describe_spine_cross_suites leaves out, each with why. Their entry points stay as they are; a consumer calls them beside the one call.

StandaloneSuiteName
#

testing/cross_backend/spine_suites.ts view source

StandaloneSuiteName

type "conformance_table" | "differential" | "login_security" | "ws_action_rate_limit"

import type {StandaloneSuiteName} from '@fuzdev/fuz_app/testing/cross_backend/spine_suites.js';

A shipped suite module describe_spine_cross_suites leaves out.

SUITE_NAMES
#

testing/cross_backend/spine_suites.ts view source

readonly ["account_lifecycle", "actor_lookup", "app_settings", "body_size", "body_size_smuggling", "cell_crud", "cell_gated_create", "cell_grant_role", "cell_grant_steward", ... 34 more ..., "ws_round_trip"]

import {SUITE_NAMES} from '@fuzdev/fuz_app/testing/cross_backend/spine_suites.js';

Every shipped suite describe_spine_cross_suites runs, each named by its module under testing/cross_backend/ (ws_round_trip is describe_cross_process_ws_tests, standard the standard bundle). Closed: a guard test holds it, with STANDALONE_CROSS_SUITES, to every module that exports a describe_* suite, so a new suite fails until it is registered.

SuiteCaseExclusions
#

testing/cross_backend/spine_suites.ts view source

Readonly<Partial<Record<"cell_crud" | "cell_relations" | "cell_gated_create" | "fact_serving" | "ready" | "ws_role_gated" | "account_lifecycle" | "origin" | "actor_lookup" | "app_settings" | ... 33 more ... | "ws_round_trip", Readonly<...>>>>

type Readonly<Partial<Record<SuiteName, Readonly<Record<string, string>>>>>

import type {SuiteCaseExclusions} from '@fuzdev/fuz_app/testing/cross_backend/spine_suites.js';

Per-suite test exclusions: each test's name path — its describe titles and its own name, joined with ' > ', as the reporter prints it after the file (and after any describe wrapping the call) — mapped to why it can't run on this backend.