testing library

The fake server of the client integration tests (brief M4-17; 15 20 row "Integration").

A separate library, never exported by package:sync_engine/sync_engine.dart, and imported only from test/ and integration_test/ folders (tools/arch-check rule 10). The headless tests of this package and the app tests from M4-18 on share it, so there is one fake that cannot drift from the other (D-W-114).

FakeServer.start binds 127.0.0.1 with a free port, serves REST under /api/v1/ and the gateway at /api/v1/gateway, keeps a FakeWorld in memory (WorldSeed.standard fills it with Alex, Sam and Robin), checks DPoP proofs (DpopVerifier), validates every request, response and frame against docs/api/ (ContractSchemas) and injects the faults of its FaultPlan. ScriptedAgent plays the agent run of 04 16.5; scenarios.dart holds the five flows of 04 16 as drivers over a ScenarioClient.

Classes

ActionCatalog
The step_up value of every action of docs/spec/actions.yaml (05 2.4).
AgentScript
The steps of a run and the pause before each one.
AgentStep
One step of an AgentScript.
AnswerFault
Answer with status and a problem with code (and reason) instead of handling the request (nothing is stored); retryAfter sets Retry-After.
ContractOperation
The facts of one REST operation of docs/api/openapi.yaml.
ContractSchemas
The API documents of the repository, loaded once per isolate.
ContractViolation
One place where a JSON value breaks its schema.
DelayFault
Handle the request, then hold the response for duration, so the echo on the gateway can arrive before it.
DpopAccepted
The proof is valid; jkt is the RFC 7638 thumbprint of its key.
DpopRejected
The proof is rejected with 401 and code (use_dpop_nonce or invalid_dpop_proof, 06 5); detail names the failed check, never the proof.
DpopResult
The outcome of DpopVerifier.verify.
DpopVerifier
Checks DPoP proofs: signature with the header jwk (ES256), typ, htm, htu, ath, iat, nonce and jti reuse; the key must be the one the token is bound to.
DropResponseFault
Handle the request (the write is stored and its events are appended), then close the connection before the response (04 16.2).
FakeAgent
One agent next to its FakePerson of kind agent (same ID, handle and display name).
FakeAgentInterface
The agent interface state of one FakeWorld; FakeAgentInterface.of gives the one of a world.
FakeAuditLog
The audit rows of the fake in ascending seq, each an AuditEvent as JSON.
FakeChannel
A channel with the levels of the principals that see it.
FakeDevice
One device of a person (08 5).
FakeEvent
One event of the log, durable (with seq) or ephemeral.
FakeFile
A file of the fake: the API File, its bytes, thumbnails, upload session and transcript.
FakeFileSettings
The settings of the file handlers of the fake (brief M4-22 Scope): the part plan, the mode, the scan, the transcription and the faults "abort after part n", "being checked" and "blocked".
FakeFileTicket
A file ticket of createFileTicket (12 9.2): file, variant, principal, login session and expiry.
FakeGatewayConnection
One gateway connection as a test sees it.
FakeHost
One host: its state, keys, declaration, reported names, valid assignments and every name ever given (ruling T12: a name stays bound to its person on the host).
FakeI1Guard
The I1 guard of the fake's rights changes (10 5.4, 11; BR-01, BR-07, BR-08).
FakeNotification
One hint the fake created and sent as notification.created (13 6.3), for assertions.
FakePairing
A device pairing (08 5.3).
FakePerson
One person or agent of the world.
FakeRequest
One REST request as a handler sees it, after routing, token and proof checks.
FakeRequestRecord
One request as the fake answered it, for assertions.
FakeResponse
The answer of a handler.
FakeSearchSettings
The limits of the search handlers of the fake (brief M4-23 Scope): the configuration values of 14 15 and the list page sizes of 06 6 with their defaults, so a test can lower them.
FakeServer
A fake of the server for the integration tests of the client (15 20 row "Integration").
FakeServerOptions
The settings of a FakeServer; every value the fake reports to clients has the default of 04 18 or 08 18 and can be shortened by tests.
FakeSession
One login session with its tokens (08 7).
FakeStatsSubscription
A stats.live subscription: the instance (spaceId null) or one space.
FakeTerminal
The terminal of the fake server: sessions, the host link, the open device streams and the server values the handlers use (24 17 defaults; tests lower them).
Plays the host service behind the stream endpoint of the fake: the app's tests connect FakeHost of package:terminal_ui/testing.dart here.
FakeTerminalPipe
The host end of one device stream in the fake (brief M4-36 Scope: a stream endpoint that relays to an in-process host). The fake hands it to FakeTerminal.hostLink after the device's identify; the link plays the host service: it reads fromDevice (each element one Noise message of the device), answers with toDevice and ends the stream with close.
FakeTerminalSession
One terminal session as the fake server keeps it (docs/spec/24-terminal.md 6, 10; brief M4-36 Scope): metadata only, never content.
FakeTerminalStream
One open device stream: the fake closes it with a code on demand.
FakeUploadPart
One stored part of an upload session (12 3.2).
FakeWorld
The in-memory model of the fake server.
FaultPlan
A queue of fault rules, matched in order (Design note 4).
GatewayFake
Serves /api/v1/gateway on the fake server.
GatewayFaultTarget
The gateway side the gateway faults act on; the fake server implements it.
GatewayFrameRecord
One frame on a gateway connection, for assertions.
GatewayTimings
The values the gateway reports to clients (04 18), parameters so tests can shorten them.
RequestFault
What a REST fault does to one request.
RestFake
Serves /api/v1/ on the fake server.
ScenarioClient
What a scenario does with the client under test (Design note 7).
ScenarioMessage
A message as the client under test holds it locally.
ScenarioOutboxEntry
An outbox entry of the client under test that is not confirmed yet.
ScriptedAgent
An agent of the world that answers mentions with the run of its script.
StoredResponse
A stored response of a write with Idempotency-Key (04 5.2).
WorldSeed
The standard world of the scenarios.

Extensions

FakeWorldTerminal on FakeWorld
The terminal steps of the world: events and the state changes that end sessions.
FakeWorldTerminalHosts on FakeWorld
Building terminal hosts for the tests of the apps (brief M4-36).
FilesWorld on FakeWorld
The files of 12: upload sessions with parts (3.1, 3.2), completion with the check and the scan (3.4), the states of 2, thumbnails (7.3), the transcript (8.2), downloads with Repr-Digest (9.3), tickets (9.2) and attaching (10). The checks are the visibility and the rules of 12 10, nothing else (README).
ThreadViewWorld on FakeWorld
The writes and reads of the thread view (brief M4-20 Scope): capabilities, main threads, operators, revisions, pins, templates, threads from a message, title, close, reopen, move and mark unread. Each write appends the event of 05 section 6 like the other writes of the world; the checks are the visibility, the level and the capability manage where 05 names it, nothing else (README).

Constants

auditGenesisHash → const String
The prev_hash of the first row: 32 zero bytes in hex.
i1Hint → const String
The hint of an i1_violation (10 5.4: "switch to organization first").

Functions

embeddedActionsYaml() → String
The text of docs/spec/actions.yaml compiled into this library (contract_documents.g.dart, docs/DECISIONS.md D-M4-26-9), for the action catalogue of the fake where the repository cannot be read.
embeddedPermissionsChapter() → String
The text of docs/spec/07-permissions.md compiled into this library (contract_documents.g.dart, docs/DECISIONS.md D-M4-27-7), for the grant preview example of the fake where the repository cannot be read.
grantPreviewExample({Directory? from}) → String
The example text of 07 9.3: the first fenced block between the language-check markers after the heading ### 9.3 of docs/spec/07-permissions.md of the repository that holds from (default: the working directory). Without such a repository (an app under test in the macOS app sandbox) it reads the copy compiled into the fake (contract_documents.g.dart, docs/DECISIONS.md D-M4-27-7).
scenarioAccessRemoval(FakeServer server, WorldSeed w, ScenarioClient client) → Future<void>
04 16.4: access to a channel is removed while the client is connected: its content goes, the view closes with a notice, and later events of the channel never arrive.
scenarioAgentRun(FakeServer server, WorldSeed w, ScenarioClient client) → Future<void>
04 16.5: a mention of the agent Robin starts a run; the live box follows the coalesced patches, a follow-up is delivered and absorbed, the agent replies and the run ends; the live box document is discarded at the end.
scenarioCatchUp(FakeServer server, WorldSeed w, ScenarioClient client) → Future<void>
04 16.3: a reconnect catches up from the cursor in pages with cursor frames (the private channel's events are skipped), then catchup.complete; only visible events arrive.
scenarioResync(FakeServer server, WorldSeed w, ScenarioClient client) → Future<void>
04 16.3, the resync_required branch: the log no longer holds the client's cursor (retention); the client keeps its outbox, loads the snapshot, reloads the focused thread and goes on live from the head without reconnecting.
scenarioSendOffline(FakeServer server, WorldSeed w, ScenarioClient client) → Future<void>
04 16.2: a message written offline is sent after the reconnect and its catch-up; the first response is lost after the commit, the retry with the same client_msg_id is a replay (200, Idempotent-Replay: true), and exactly one message exists.
scenarioSendOnline(FakeServer server, WorldSeed w, ScenarioClient client) → Future<void>
04 16.1: a message sent online; its echo confirms the outbox entry while the response is still on its way (the fake holds it), and exactly one message exists on both sides.
waitFor(String what, FutureOr<bool> condition(), {Duration timeout = const Duration(seconds: 15)}) → Future<void>
Waits until condition holds, polling every few milliseconds; throws ScenarioFailure naming what after timeout.

Typedefs

EventHook = void Function(FakeEvent event)
Called for every appended event, durable or ephemeral.
FakeAuditCheck = JsonMap
The result of FakeAuditLog.verify, shaped as AuditVerifyResult.
FakeAutocomplete = List<JsonMap> Function(String option, String value, JsonMap others)
Suggestions of an agent for one option: the option name, the typed value and the other option values in; {name, value} choices out (API CommandChoice).
FakeHandler = FutureOr<FakeResponse> Function(FakeRequest request)
Handles one operation; throw FakeProblem for a problem answer.
HostJson = Map<String, Object?>
The JSON maps of the fake.
JsonMap = Map<String, Object?>
A JSON object of the API.
MessageCreatedHook = void Function(JsonMap message, FakePerson author)
Called after a message was stored and its message.created appended; the scripted agent of 04 16.5 listens here.
RunPatchHook = void Function(String runId, int baseVersion, int version, List<JsonMap> ops)
Called after the run document runId changed from baseVersion to version by ops (04 11.2); the gateway turns it into coalesced run.updated frames.

Exceptions / Errors

ContractError
Thrown when the fake itself would send something that breaks the contract: a programming error of the fake, never of the client under test.
FakeProblem
A rejection of a write or read, answered as an RFC 9457 problem (06 5).
ScenarioFailure
A scenario check that failed; message says what was expected.