# axx fixtures

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

Source: https://axx.nimbusxr.us/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)
  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 modal value of every
field, each file becomes a *.fixture.yaml carrying only its deltas, and string
fields distinct across every file are proposed as identities. Before anything is
written the new spec is expanded and every file must decode equal to its
original; otherwise adoption refuses and writes nothing.

  axx fixtures adopt --schema schemas/order.avsc --files 'kafka/orders/*.json' --factory orders
  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
      --into string          adopt into this existing factory (name or root-relative path)
      --profile string       apply profiles.<name> / axx.<name>.yaml (env: AXX_PROFILE)
      --schema string        governing schema, relative to fixtures.baseDir

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.

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 (env: AXX_PROFILE)

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 (env: AXX_PROFILE)

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 (env: AXX_PROFILE)

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 (env: AXX_PROFILE)

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)
```