vdm/contracts/fixtures

contracts/fixtures — golden request/response pairs

Every method has at least one success fixture. A method with no fixture is not done.

These files are replayed by tests/conformance/ against both the generated C++ and a live server, which is what lets four lanes build in parallel and still be compatible: green fixtures mean the C++ daemon and the TypeScript extension agree, without either having ever run against the other. tools/mockd also answers from them, so the GUI and extension are developed against the same bytes conformance asserts.

Layout

fixtures/
├── *.json          one success fixture per method
├── errors/         error cases: auth, transport, not-found, bad path, timeout
└── events/         one fixture per server-to-client notification

Shape

{
  "name": "download.add — add an ISO for later, into the Programs category",
  "description": "Why this case is worth pinning.",
  "transport": "uds",          // optional: replay only on this transport
  "requires": "...",           // optional: a condition a plain server cannot produce
  "kind": "timeout",           // optional: the correct behaviour is *no reply*
  "request":  { "jsonrpc": "2.0", "id": 11, "method": "download.add", "params": { } },
  "response": { "jsonrpc": "2.0", "id": 11, "result": { } },
  "assertions": [ "things a runner or a reviewer should check" ]
}

An event fixture carries notification instead of request/response.

assertions are prose, for the human writing the implementation. The runners check the machine-checkable parts: schema validity, error codes, shape, and the timeout.

Placeholders

Some values cannot be pinned in a golden file. These stand in for them, and the runners treat them as "any value of the right shape":

Placeholder	Means
$uuid	any UUID
$isoDate	any RFC 3339 date-time
$opaque	a credential-shaped string (a token)
$any	any value
$taskId, $taskId2	a task the runner creates during setup, and binds before replaying

$taskId exists so a fixture never depends on a task id that only happens to exist in a seeded mock. The same fixture then runs against an empty veloxd and a populated mockd.

Values are matched by shape, not by equality

A live daemon returns its own task ids and its own clock. Demanding byte-identical results would only teach the suite to lie, so the runners assert:

• the payload passes the generated validator — this is the real cross-language check;
• the key structure matches the golden file, with no extra and no missing fields;
• error codes match exactly.

A null where the golden shows a value is accepted: the validator has already ruled on whether null is legal there, and a golden file shows one plausible value, not the only one.

requires: fixtures a mock cannot produce

Most error fixtures are intrinsic — a path outside the allowed roots, an out-of-range parameter, an unknown task id — and any correct server produces them from the request alone. Those are replayed everywhere.

Four are environmental: a 403 from an origin server, a full disk, a pairing lockout, a wedged daemon. They carry requires, are skipped by default, and are exercised where the condition can actually be arranged — run.sh starts a deliberately slow mockd to prove capture.offer fails open, and lane PKG/QA's tools/testserver covers the hostile-server cases in tests/integration/.

errors/capture.offer.timeout.json is the most important file in this directory. Its correct response is no response: past 750 ms the extension must abandon the offer and let Firefox download normally. A download manager that eats downloads when its daemon is down is worse than no download manager.

No fixture may pair a real external URL with startMode: "now"

This suite replays every fixture against a real, live veloxd (tests/conformance/run.sh), not just mockd. mockd never actually fetches anything, so it hid this for a while: a fixture with startMode: "now" (or "queue" into a running queue — anything that gets admitted to the scheduler right away) and a real, resolvable URL makes a real daemon actually start downloading it, for real, onto whatever machine runs the suite. This happened — twice, with download.add.json pointed at a ~6 GB Ubuntu ISO, straight into the developer's real ~/Downloads.

The fix in each case is one of:

• startMode: "later" — exercises the add path (validation, category assignment, the event) without ever handing the task to the engine;
• a URL under example.org/example.com (IANA-reserved for exactly this, RFC 2606) — resolvable enough to validate as a URL, never a real download source;
• requires, if the fixture's entire point needs a real transfer to fail in a specific way (see errors/download.add.disk-full.json) — skipped by default, so it only ever runs where the condition has actually been arranged.

A real saveDir gets the same treatment for the same reason: an absolute path like /home/sami/Downloads/... only means anything on the machine that fixture was written on. Omit saveDir and let saveTo.defaultDir apply, or use a relative-feeling path under a root the runner controls.