Add Golden File Tests for API Responses

1. Write a golden helper that only updates files when an explicit environment flag is set.

import { readFile, writeFile, mkdir } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';
import assert from 'node:assert/strict';

const file = (name) => fileURLToPath(new URL(`./golden/${name}.json`, import.meta.url));
const sortKeys = (value) =>
  Array.isArray(value) ? value.map(sortKeys)
    : value && typeof value === 'object'
      ? Object.fromEntries(Object.keys(value).sort().map((k) => [k, sortKeys(value[k])]))
      : value;

export async function assertGolden(name, payload) {
  const actual = JSON.stringify(sortKeys(payload), null, 2) + '\n';
  if (process.env.UPDATE_GOLDEN === '1') {
    await mkdir(new URL('./golden/', import.meta.url), { recursive: true });
    await writeFile(file(name), actual);
  }
  const expected = await readFile(file(name), 'utf8');
  assert.equal(actual, expected, `golden mismatch: ${name}.json`);
}

Expected output: UPDATE_GOLDEN=1 creates or rewrites the file; a normal run compares and fails with the file name.

2. Remove nondeterminism: fixed clock, fixed identifiers, sorted keys, and a projection of contract fields only.

const payload = {
  data: orders.map((o) => ({ id: o.publicId, status: o.status, total: o.totalCents })),
  meta: { page: 1, perPage: 20 },
};
await assertGolden('orders-success', payload);

Expected output: Two consecutive runs produce byte-identical files with no timestamps or database-generated ids.

3. Cover the shapes clients depend on: success, validation error, and an empty collection.

UPDATE_GOLDEN=1 node --test test/api-golden.test.js

Expected output: three files under test/golden: orders-success.json, orders-validation-error.json, orders-empty.json

4. Review the diff like source code, then commit the golden files with the change that caused them.

git diff --stat test/golden && git diff test/golden

Expected output: The diff shows exactly the intended field change; unrelated churn is reverted before committing.

5. Refuse silent regeneration on CI so a bad snapshot cannot be accepted automatically.

if (process.env.CI === 'true' && process.env.UPDATE_GOLDEN === '1') {
  throw new Error('UPDATE_GOLDEN is not allowed in CI');
}

Expected output: CI fails fast if the update flag is set, forcing snapshots to be updated and reviewed locally.

Problem

The golden file changes on every run

Solution

A timestamp, random id, or object key order is leaking in. Inject a fixed clock, map ids to stable values, and sort keys before serializing.

Problem

Nobody reads golden diffs before approving

Solution

Keep one small file per case, name it after the behaviour, and treat a golden diff as an API change requiring the same review as a schema change.

Problem

CI fails only because of line endings

Solution

Normalize output to LF and add .gitattributes with text eol=lf for the golden directory.