Test Format

YAML Schema

Each test is a YAML file in your axiomatic/ directory. Here is the full schema:

# Required: the condition to verify, in plain English
condition: >
  All exported functions have JSDoc comments with at least
  a @param tag for each parameter and a @returns tag.

# Optional: glob pattern(s) — used for cache invalidation and as agent starting points
on:
  - "src/**/*.ts"

# Optional: severity level (default: error)
severity: warning

# Optional: tags for filtering and organization
tags: [code-quality, documentation]

# Optional: override the provider for this test
provider: anthropic

# Optional: override the model for this test
model: claude-sonnet-4-6

# Optional: per-test timeout in seconds
timeout: 120

# Optional: maximum agent tool-use turns
max_iterations: 50

The `condition` Field

The condition is the most important part of a test. It describes a property that should be true about your codebase, written in plain English.

See Writing Tests for detailed guidance on writing effective conditions.

The `on` Field

The on field accepts an array of glob patterns that serve two purposes:

Cache invalidation -- Axiomatic hashes the content of matching files. If none changed since the last passing run, the test is skipped.
Investigation starting point -- the agent is told to start its investigation with these files. It can read any file in the repo from there.

# Single pattern
on:
  - "src/**/*.ts"

# Multiple patterns (matches any)
on:
  - "src/**/*.ts"
  - "src/**/*.tsx"

# Brace expansion
on:
  - "src/**/*.{ts,tsx,js,jsx}"

Glob Pattern Reference

Pattern	Matches
`src/*.ts`	TypeScript files directly in `src/`
`src/*/.ts`	TypeScript files anywhere under `src/`
`*/.yml`	YAML files anywhere in the repo
`src/*/.{ts,tsx}`	TypeScript and TSX files under `src/`

If on is omitted, the agent examines the entire project (excluding files in .gitignore). However, tests without on globs cannot be cached -- they run every time. Always add on patterns when possible.

Use axm validate to identify tests missing on patterns.

Severity Levels

Level	Behavior
`error`	Fails the test run (exit code 1). Use for critical invariants like security and data integrity.
`warning`	Reported but does not fail the run. Use for code quality and style guidelines.
`info`	Informational only. Use for metrics and audit trails.

Test Organization

Organize tests by concern using files and subdirectories:

axiomatic.yml              # Config at repo root
axiomatic/
  architecture.yml     # Layer boundaries, dependency rules
  security.yml         # Auth, input validation, secrets
  error-handling.yml   # Error wrapping, exit codes
  features/
    payments.yml       # Payment-specific invariants
    auth.yml           # Auth-specific invariants

All YAML files are discovered recursively. Hidden directories (starting with .) are skipped.