Module document 

Scenario document model, parsing, and validation (ADR-0069 sections 1-2).

A scenario document is a .test.yaml (or .test.yml) sidecar that declares one integration-tier test: exactly one route source (routeFiles, routeFilesFromRoot, or inline routes), an ordered scenario: action list, an optional env: map with fixed fixture values, an optional envPassthrough: allowlist, an optional endpoint-keyed partners: scripting map, and an optional pinned profile. Unknown fields are rejected.

The scenario vocabulary and the unit-tier vocabulary (inputs, expects, intercepts) never mix in one document. A document with scenario: that also declares a unit-tier section is rejected at load time.

Durations (deadline, duration, elapsedAtLeast) are humantime strings, for example "5s" or "250ms", parsed during validation so errors can name the action index.

Structs

EndpointRef

An endpoint reference: a bare endpoint string or a map with endpoint, provisioning, and bindVar keys.

PartnerExpectation

The partner expectation of a validate action with a partner target: a recorded-request count bound plus optional method, path, and query subset filters.

PartnerScript

One partner script of a partners: entry: the response a partner serves when the system under test reaches its endpoint, or the fault it applies instead. Exactly one of response / fault must be declared. Grammar only; the runner consumes the map.

PartnerScriptResponse

The response a partner script serves.

ScenarioDocument

A parsed scenario document. Route file paths stay as declared; resolving them against the document directory or the project root is the runner’s job, the same split the unit-tier parser keeps.

Enums

CountBound

The recorded-request count bound of a PartnerExpectation: exactly one bound form per expectation. Poll semantics per bound (arrivals only add, so the filtered count is monotone non-decreasing):

DocError

Parse and validation errors for scenario documents.

Expectation

A validation expectation. The grammar keys mirror the mock-testkit matcher rules: equals, regex, contains, startsWith, endsWith, exists, jsonSubset.

PartnerFault

The fault a partner script applies instead of serving a response.

PathFilter

The path filter of a PartnerExpectation over the recorded path-and-query; at most one filter per expectation.

Provisioning

Partner provisioning source (ADR-0069 section 9). The axis is who owns the lifecycle. testcontainer and user-provided are reserved grammar values; the parser rejects them.

RouteSource

The route source of a scenario document. Exactly one form is declared; the parser rejects zero or multiple declarations.

ScenarioAction

One ordered scenario action (ADR-0069 section 11, adopted from Citrus: send, receive with a mandatory deadline, sleep, validate).

ScenarioTarget

What a validate action asserts against.

ValidateExpectation

The expectation of a validate action, keyed by its target: the message matcher grammar for lastReceived and variable targets, the partner count grammar for partner targets.

Functions

parse_scenario_document

Parses and validates a scenario document. Validation order: (a) the path carries a reserved test-document suffix; (b) the text deserializes; (c) a non-empty scenario: section exists; (d) no unit-tier section coexists with it; (e) exactly one route source is declared; (f) each action converts (single-key dispatch, deadlines, durations, endpoint provisioning, expectation grammar) with action-index errors; (g) each partners entry converts (script grammar, response status range) with entry-key errors; (h) no env key collides with a declared bindVar; (i) each partner validate target URI equals a harness endpoint reference declared by the scenario’s own send/receive actions.