Short answer
What to know
A deterministic API fixture is a response whose URL, bytes and media type stay fixed. Payloads publishes versioned static files and a SHA-256 manifest, so a test can fetch realistic data while still asserting the exact input it received.
Start with a versioned URL
Use a path under /v1 rather than a generated or random-data endpoint. The version is part of the contract: a published v1 asset is not changed in place.
The collection endpoints are deliberately small enough to read in a failed test log. Record endpoints are useful when a test only needs one object.
const url = "https://payloads.mochavi.com/v1/users.json";
const response = await fetch(url);
if (!response.ok) throw new Error("fixture failed: " + response.status);
const users = await response.json();Assert the contract that matters
A good fixture test separates transport assertions from application assertions. Check the response status and media type first, then validate the decoded shape or the behaviour of the code under test.
If byte-for-byte stability matters, read the expected SHA-256 from the public manifest and compare it with the downloaded response. That detects a proxy, cache or accidental fixture change instead of silently accepting new input.
- HTTP status is successful.
- Content-Type matches the parser you intend to exercise.
- The payload validates against the published JSON Schema where applicable.
- The checksum matches when exact bytes are part of the test contract.
Choose remote or vendored fixtures deliberately
| Approach | Good fit | Trade-off |
|---|---|---|
| Fetch the public URL | Examples, smoke tests and integration checks that intentionally exercise HTTP | The test depends on network and DNS availability |
| Vendor the file | Hermetic unit tests and offline CI | You own updates and may duplicate fixtures across repositories |
| Cache with checksum verification | CI that wants reproducibility and occasional refreshes | Requires a small cache step |
When a static fixture is the wrong tool
Payloads does not simulate writes, authentication, latency, errors or request-dependent responses. Use a mock server or an HTTP test service when the server behaviour is what you need to verify.
Static fixtures are strongest when the subject of the test is your downloader, decoder, validator, importer or UI—not a pretend backend.