Skip to main content

Per-environment overrides

PACE runs in several environments — dev2, qa, and local are the most common. The same test often needs different values in different environments: a project that exists in dev2 might have a different numeric ID in qa, or a client name might differ. Override files let you handle this without duplicating the entire data file.

Where override files live​

tests/data/env/
  dev.jsonc    ← applied when TEST_ENV=dev   (exact name match)
  qa.jsonc     ← applied when TEST_ENV=qa    (exact name match)
  local.jsonc  ← applied when TEST_ENV=local (exact name match)

The overlay file is selected by exact name match: the resolver looks for tests/data/env/<TEST_ENV>.jsonc. If no file with that exact name exists, no overlay is applied and the base tests/data/*.jsonc values are used as-is.

Other environments in regular use — dev2 (the default when you omit TEST_ENV), qa2, dev3, demo5 — do not yet have overlay files, so running with any of those values applies no overlay. To add overrides for a specific environment, create the file named exactly after that env value (for example, tests/data/env/dev2.jsonc to override for TEST_ENV=dev2).

How TEST_ENV selects the override​

When you run the tests, the TEST_ENV variable tells the data resolver which override file to load on top of the base data. For example:

TEST_ENV=qa pnpm run test

The resolver loads every base file in tests/data/*.jsonc first, then merges the matching override file (tests/data/env/qa.jsonc) on top. Any key in the override file wins over the same key in the base file. Keys that are not mentioned in the override file keep their original values.

If you omit TEST_ENV, it defaults to dev2 — but there is no tests/data/env/dev2.jsonc yet, so no overlay is applied. The base tests/data/*.jsonc values are used as-is.

Dotted-path keys​

Override files do not repeat the full JSON structure of the base file. Instead, they use dotted-path keys — a compact way to point directly at a nested value.

The pattern is:

"<domain>.<entry>.<field>": "new value",

For example, to use a different project organization ID in the local environment:

// tests/data/env/local.jsonc — example with an override added
{
  "$schema": "../../schemas/generated/env.schema.json",

  // Dotted-path keys override values from tests/data/*.jsonc at load time.
  "projects.default.organization_id": "Local-Org",
}

The real file doesn't contain this entry yet — it's shown only to illustrate the syntax.

This overrides only the organization_id field inside projects.default. Every other field in projects.default — the project name, dates, key role, and so on — comes from tests/data/projects.jsonc unchanged.

Reading the path​

To decode a dotted path like projects.default.organization_id:

  1. projects — the domain, which matches tests/data/projects.jsonc
  2. default — the entry key inside the "projects" object
  3. organization_id — the field inside that entry

Open tests/data/projects.jsonc and you will see exactly those levels:

{
  "projects": {
    "default": {
      "organization_id": "Services-Central",
      // …
    },
  },
}

Adding a new override​

  1. Open the override file for the environment you need (e.g. tests/data/env/qa.jsonc).

  2. Add a dotted-path key for the value that differs. Use the same pattern as the example above.

  3. Run the data validator to confirm the path resolves correctly:

    pnpm run test:validate-data

  4. Commit the change.

Only override what actually differs

Adding an override for a value that is the same across all environments just creates a maintenance burden. Only add entries when a value genuinely differs between the base and the target environment.

What the current override files look like​

All three env files currently carry the $schema line and a comment placeholder. They are intentionally sparse — all environments happen to share the same base data for now. When a value diverges (for example, after a QA environment rebuild), add the override to the appropriate file rather than changing the base data.

// tests/data/env/qa.jsonc — as it exists today
{
  "$schema": "../../schemas/generated/env.schema.json",

  // Env-specific overrides for QA. Add entries as QA env data drifts from
  // the canonical manifests.
}