Use RECORD in Holodeck Mocks

Use this skill when a test mocks HTTP with @warp-drive/holodeck and you need to re-record one request, or when you are reviewing a test that sets RECORD. RECORD is a per-request override. It is a local tool for refreshing a fixture, not a setting a committed test should carry.

How recording is decided

Holodeck records or replays according to a build-time flag from @warp-drive/build-config.

const SHOULD_RECORD = Boolean(!CI || IS_RECORDING);

A local run records every mock. A run with CI set replays every mock from .mock-cache. RECORD overrides that for a single mock: it records the request even when the rest of the suite replays.

Steps

1. Rely on the default first. To change a response, edit the mock and run the suite locally. It re-records without any option.

2. Reach for RECORD only when one request has to record while the suite replays, for example when you run with CI=1 locally and need a single fixture refreshed.

   await GET(this, 'users/1', () => ({ data: { id: '1', type: 'user' } }), { RECORD: true });

   POST, PUT, PATCH, DELETE, and HEAD take the same option. The low-level form is mock(this, generate, true).

3. Run the test, then commit the fixture it wrote under .mock-cache.

4. Delete RECORD from the test before you commit the test.

5. Prove the fixture replays. CI is compiled into the test bundle, so set it on the command that builds as well as the one that runs.

   CI=1 pnpm build:tests && CI=1 pnpm test

Why RECORD must not be committed

A committed RECORD: true records that request in every environment, CI included. The request is never compared against its committed fixture again, so the test passes whatever that fixture says, and a stale or wrong fixture goes unnoticed. The rest of the suite still replays, which makes the one exception easy to miss in review.

Notes

• With RECORD, the response generator runs even in replay. Without it, replay never calls the generator, which is what makes a replayed suite cheap.
• A test that declares a mock and never requests it fails from afterEach, with or without RECORD.
• Treat RECORD in a diff the way you treat a focused or skipped test: ask for it to be removed before merge.

Related

• Related skill: Fetch and Cache Data