# axx fixtures

> Generate, check and adopt schema-governed fixture files (the fixture factory)

Source: https://axx.nimbusxr.us/next/references/cli/axx-fixtures/

The fixture factory expands *.factory.yaml, *.fixture.yaml and *.prototype.yaml
sources into fixture files (Avro/JSON/YAML/XML/protobuf payloads, database seed
datasets) that are validated against their schemas, and records what it owns in
axx-fixtures.manifest.yaml. Only files recorded there are ever touched; a managed
file whose content no longer matches its sha256 is a refused hand-edit.

Configure it in the fixtures section of axx.yaml. The spec file formats:
axx schema --kind factory|fixture|prototype.

Exit codes: 0 ok, 1 drift or a failed check/generation, 2 invalid configuration
or spec files, 4 git unavailable (untrack).

```text
Usage:
  axx fixtures [command]

Available Commands:
  adopt       Turn existing fixture files into factory sources, preserving every value
  check       Verify committed fixtures match their specs (drift) and conform to their schemas
  clean       Delete ignored generated outputs from disk (generate rematerializes them)
  explain     Say where a value of a generated fixture comes from
  generate    Expand the factory specs into fixture files, the manifest and generated lint rules
  untrack     Take ignored outputs that are still tracked out of the git index (git rm --cached)

Flags:
  -h, --help   help for fixtures

Global Flags:
      --compact         print only what matters (auto-enabled for coding agents)
  -c, --config string   path to axx.yaml (default: search upward from the working directory)
      --json            emit machine-readable JSON (stable envelope)
      --no-color        disable colored output
  -v, --verbose count   increase log verbosity (-v, -vv)

Use "axx fixtures [command] --help" for more information about a command.
```

## axx fixtures adopt

Adopt hand-written fixture files: the prototype takes the values every file
shares (--prototype common: each field's most common value), and each file
becomes a *.fixture.yaml carrying only its differences. String fields whose value
is distinct in every file are proposed as identity candidates, with how many
files they were compared across; declare the ones that identify a fixture with
--identity (repeatable). Before anything is written the new spec is expanded and
every file must decode equal to its original; otherwise adoption refuses, lists
the paths that would change, and writes nothing. --dry-run does all of it and
writes nothing either.

  axx fixtures adopt --schema schemas/order.avsc --files 'kafka/orders/*.json' --factory orders --dry-run
  axx fixtures adopt --schema schemas/order.avsc --files 'kafka/orders/*.json' --factory orders --identity order_id
  axx fixtures adopt --into orders --files 'features/refunds/*.json'

Paths and globs are relative to fixtures.baseDir.

```text
Usage:
  axx fixtures adopt [flags]

Examples:
  axx fixtures adopt --family json --schema openapi/api.yaml#/components/schemas/Order \
    --files 'mocks/orders/*.json' --factory order-bodies

Flags:
  -D, --define stringArray     set a property for ${sys:name}, e.g. -D local.host=docker
      --dry-run                verify the adoption and report without writing anything
      --factory string         name of the new factory (written next to the adopted files)
      --family string          fixture family of the adopted files (default avro)
      --files string           glob of the files to adopt, relative to fixtures.baseDir
  -h, --help                   help for adopt
      --identity stringArray   declare an identity candidate as an identity (repeatable), e.g. --identity order_id
      --into string            adopt into this existing factory (name or root-relative path)
      --profile string         apply profiles.<name> / axx.<name>.yaml, several comma-separated in order, like watch,ios (env: AXX_PROFILE)
      --prototype string       what the prototype takes: shared (the values every file shares) or common (each field's most common value) (default "shared")
      --schema string          governing schema, relative to fixtures.baseDir
      --set stringArray        set a key of axx.yaml for this run, over its files and profiles, e.g. --set run.workers=1 or --set packs.<pack>.<key>=value

Global Flags:
      --compact         print only what matters (auto-enabled for coding agents)
  -c, --config string   path to axx.yaml (default: search upward from the working directory)
      --json            emit machine-readable JSON (stable envelope)
      --no-color        disable colored output
  -v, --verbose count   increase log verbosity (-v, -vv)
```

## axx fixtures check

Read-only verification: every managed file must equal what the factories
generate, the manifest must list exactly what they produce, and every file a
conformance rule matches must pass its family's schema oracle. Recorded
expression functions resolve from the committed pairings lock only.

Ignored outputs (fixtures.output.ignored) a checkout lacks pass when the
committed manifest records what the sources produce, so a fresh clone
checks clean; run `axx fixtures generate` after check to write them. Check
first: generate would bring a stale manifest up to date and hide it.

Exit codes: 0 all checks pass, 1 any failure (drift fails CI), 2 invalid
configuration or spec files.

```text
Usage:
  axx fixtures check [flags]

Flags:
  -D, --define stringArray   set a property for ${sys:name}, e.g. -D local.host=docker
  -h, --help                 help for check
      --profile string       apply profiles.<name> / axx.<name>.yaml, several comma-separated in order, like watch,ios (env: AXX_PROFILE)
      --set stringArray      set a key of axx.yaml for this run, over its files and profiles, e.g. --set run.workers=1 or --set packs.<pack>.<key>=value

Global Flags:
      --compact         print only what matters (auto-enabled for coding agents)
  -c, --config string   path to axx.yaml (default: search upward from the working directory)
      --json            emit machine-readable JSON (stable envelope)
      --no-color        disable colored output
  -v, --verbose count   increase log verbosity (-v, -vv)
```

## axx fixtures clean

Delete the ignored outputs (the gitignored derivations of factory sources) from
disk. Committed outputs, sources, the manifest, the pairings lock and the managed
.gitignore files are never touched; directories the deletion empties are removed.

```text
Usage:
  axx fixtures clean [flags]

Flags:
  -D, --define stringArray   set a property for ${sys:name}, e.g. -D local.host=docker
      --dry-run              list what would be deleted without deleting
  -h, --help                 help for clean
      --profile string       apply profiles.<name> / axx.<name>.yaml, several comma-separated in order, like watch,ios (env: AXX_PROFILE)
      --set stringArray      set a key of axx.yaml for this run, over its files and profiles, e.g. --set run.workers=1 or --set packs.<pack>.<key>=value

Global Flags:
      --compact         print only what matters (auto-enabled for coding agents)
  -c, --config string   path to axx.yaml (default: search upward from the working directory)
      --json            emit machine-readable JSON (stable envelope)
      --no-color        disable colored output
  -v, --verbose count   increase log verbosity (-v, -vv)
```

## axx fixtures explain

Say where the value at &lt;path&gt; in a generated fixture file comes from, and so
which source to edit: the fixture's own data, a prototype overlay, the factory's
prototype, a defaults: entry or the schema's default, with the file and the place
in it. A value that comes through a $ref, an expression or an identity says so,
then where that comes from.

&lt;file&gt; is a file `axx fixtures generate` writes (or its fixture's *.fixture.yaml),
from the working directory or the fixtures base dir. &lt;path&gt; is dotted, with
indices: recipient.postcode, items[0].sku; a dataset path starts with the table:
orders[0].status.

Read-only: recorded expression functions resolve from the committed pairings.

Exit codes: 0 explained, 1 the specs cannot be expanded, 2 a file the factory
does not generate or a path with no single value.

```text
Usage:
  axx fixtures explain <file> <path> [flags]

Examples:
  axx fixtures explain requests/order-7731.json recipient.country
  axx fixtures explain kafka/scan-delivered.json scanId --json

Flags:
  -D, --define stringArray   set a property for ${sys:name}, e.g. -D local.host=docker
  -h, --help                 help for explain
      --profile string       apply profiles.<name> / axx.<name>.yaml, several comma-separated in order, like watch,ios (env: AXX_PROFILE)
      --set stringArray      set a key of axx.yaml for this run, over its files and profiles, e.g. --set run.workers=1 or --set packs.<pack>.<key>=value

Global Flags:
      --compact         print only what matters (auto-enabled for coding agents)
  -c, --config string   path to axx.yaml (default: search upward from the working directory)
      --json            emit machine-readable JSON (stable envelope)
      --no-color        disable colored output
  -v, --verbose count   increase log verbosity (-v, -vv)
```

## axx fixtures generate

Expand every factory spec into canonical fixture bytes and write the files that
changed, the managed .gitignore entries for ignored outputs, the pairings lock of
recorded expression functions, the generated lint rules and the manifest.

A managed file whose content no longer matches the manifest is a hand-edit:
generate refuses to overwrite it (lift the change into the spec, or re-adopt the
file). There is no force option that discards edits.

```text
Usage:
  axx fixtures generate [flags]

Flags:
  -D, --define stringArray   set a property for ${sys:name}, e.g. -D local.host=docker
      --dry-run              report what would be written without writing anything
  -h, --help                 help for generate
      --profile string       apply profiles.<name> / axx.<name>.yaml, several comma-separated in order, like watch,ios (env: AXX_PROFILE)
      --set stringArray      set a key of axx.yaml for this run, over its files and profiles, e.g. --set run.workers=1 or --set packs.<pack>.<key>=value

Global Flags:
      --compact         print only what matters (auto-enabled for coding agents)
  -c, --config string   path to axx.yaml (default: search upward from the working directory)
      --json            emit machine-readable JSON (stable envelope)
      --no-color        disable colored output
  -v, --verbose count   increase log verbosity (-v, -vv)
```

## axx fixtures untrack

The one-time step after outputs become ignored: .gitignore rules only govern
untracked files, so previously committed copies must leave the index. Runs
git rm --cached for ignored outputs that are still tracked. Working-tree files are
never touched and the removal is staged, not committed; re-running is harmless.

```text
Usage:
  axx fixtures untrack [flags]

Flags:
  -D, --define stringArray   set a property for ${sys:name}, e.g. -D local.host=docker
      --dry-run              list what would be untracked without touching the index
  -h, --help                 help for untrack
      --profile string       apply profiles.<name> / axx.<name>.yaml, several comma-separated in order, like watch,ios (env: AXX_PROFILE)
      --set stringArray      set a key of axx.yaml for this run, over its files and profiles, e.g. --set run.workers=1 or --set packs.<pack>.<key>=value

Global Flags:
      --compact         print only what matters (auto-enabled for coding agents)
  -c, --config string   path to axx.yaml (default: search upward from the working directory)
      --json            emit machine-readable JSON (stable envelope)
      --no-color        disable colored output
  -v, --verbose count   increase log verbosity (-v, -vv)
```