References ($ref)

Share and reuse item definitions across test files.

Basic usage

Items can reference shared fragments using $ref with a relative path:

{
  "items": [
    { "$ref": "../shared/api-gateway.json" },
    { "$ref": "../shared/postgres-db.json" }
  ]
}

The path is relative to the file containing the $ref. At resolution time, Dokkimi replaces the $ref with the full contents of the referenced file.

Overriding fields

Additional fields are shallow-merged as overrides on top of the fragment:

{
  "items": [
    {
      "$ref": "../shared/postgres.json",
      "initFilePath": "../init-files/users-seed.sql"
    }
  ]
}

The fragment's fields are used as the base, and inline fields override them.

Don't override name on a $ref unless you intentionally want a second instance with a different name. The fragment already has a name — overriding it creates a differently-named copy.

Multi-ref

$ref can also be an array of paths. Fragments are resolved and merged left-to-right, with later files overriding earlier ones. Inline fields still win over all fragments:

{
  "items": [
    {
      "$ref": ["../shared/base-service.json", "../shared/staging-overrides.json"],
      "env": ["...$ref.env", { "name": "EXTRA", "value": "inline-wins" }]
    }
  ]
}

Array spreading

To extend an array field from the fragment instead of replacing it, use "...$ref.<path>" as an element in the override array:

{
  "$ref": "../shared/my-service.json",
  "env": ["...$ref.env", { "name": "EXTRA_VAR", "value": "123" }]
}

The "...$ref.env" marker is replaced with the fragment's env array. Position controls order — entries before the marker are prepended, entries after are appended. If the path doesn't resolve to an array, the marker expands to nothing.

The path supports dot notation for nested fields (e.g., "...$ref.some.nested.array").

$ref for variables

Both definition-level and test-level variables support $ref to load values from shared files:

{
  "variables": {
    "$ref": "../shared/db-vars.json",
    "localOverride": "my-value"
  }
}

Multi-ref also works for variables:

{
  "variables": {
    "$ref": ["../shared/db-vars.json", "../shared/test-users.json"],
    "extraVar": "inline-wins"
  }
}

Referenced files must be plain { "key": "value" } objects — no nested objects, no $ref inside them.

Rules

← Mocks Tests & Steps →