AkurAI-Framework / AGENTS_TESTING.md

Latest change 4ed55d17e0979479dc70291811217113b6062fa0 - docs: split AGENTS.md into domain-indexed subfiles + add breaking-changes guide by Ólafur Búi Ólafsson

# AGENTS_TESTING.md — testing & the batch workflow

> TDD is constitutional (principle #7) and performance is a gate, not a hope
> (#8). This file is the green gate, the test conventions, and the worktree-agent
> batch recipe that work lands through.

## TDD discipline

**Failing test first, every phase.** No subsystem advances without its test
layer. The layers, innermost out:

- **Unit** — inline `#[cfg(test)] mod tests` per module. Pure logic, no I/O.
- **Property / fuzz** — proptest against invariants (SQL parser round-trips,
  B+tree invariants). Dev-dependency only — never enters the binary.
- **Integration** — `tests/` per crate against real artifacts: real DB files,
  real sockets, real HTTP (e.g. `crates/storage/tests/tree.rs`,
  `crates/http/tests/middleware.rs`, `crates/sqlexec/tests/end_to_end.rs`).
- **E2E / visual** — Playwright in `tests/e2e/` with screenshot snapshots;
  locally also verify with Interceptor (real Chrome). Node tooling here is
  dev-only and never ships.
- **Perf** — `bench/` (criterion + a load generator); budgets enforced as a
  release gate.

## The green gate

Everything must be green before a commit lands or a release cuts. `deploy.sh`
runs exactly this (see [`AGENTS_DEPLOY.md`](./AGENTS_DEPLOY.md)) and dies on the
first failure:

```
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace
```

`-D warnings` means **clippy warnings are errors** — fix them, don't `#[allow]`
them away without a documented reason. Run the gate locally before opening a PR;
don't make the orchestrator discover a red gate at integration time.

## Test conventions

- **FS tests use `CARGO_TARGET_TMPDIR`, never `/tmp`.** Every test that touches
  the filesystem (DB files, pager round-trips) writes under the per-crate
  `env!("CARGO_TARGET_TMPDIR")` so runs are isolated, parallel-safe, and
  auto-cleaned. Never hardcode `/tmp` or a repo path.
- **Tests never touch the network.** `vector`'s pure parts (endpoint parse,
  request build, response split) are unit-tested against hand-written strings;
  the actual socket round-trip is not exercised in tests.
- **Never panic on bad data.** Parsers and decoders return positioned errors or
  `None`/`Err` on malformed input — assert that, don't let it `unwrap`.
- **Files stay under 1000 lines.** One responsibility per file (principle #9). If
  a file grows a second concern, split it and index it in
  [`AGENTS_CRATES.md`](./AGENTS_CRATES.md). Big files are a smell, not a goal.

## The worktree-agent batch recipe

Work is built by **parallel worktree agents on DISJOINT file sets**, then an
orchestrator integrates. The rules that keep it conflict-free:

1. **A batch = up to 3 features**, each built by its own worktree agent on a file
   set that does **not overlap** any sibling's.
2. **At most ONE cli-touching feature per batch.** `crates/cli/**` is the shared
   integration seam; two agents editing it collide. The other features in a batch
   must be a **new crate** or **frontend-JS-only**. Agents may *read* the CLI
   freely; only the one cli-owning agent writes it.
3. **The orchestrator integrates** — merges the agents' branches, runs the green
   gate, wires nav/docs/changelog/roadmap (which agents do **not** touch — see
   the forbidden list in [`AGENTS_DOCS.md`](./AGENTS_DOCS.md)), verifies, and runs
   `./deploy.sh minor`.
4. **Descope honestly.** Anything `std` genuinely can't do (TLS clients,
   from-scratch image/raster codecs) is documented and descoped, never faked.

Each agent still follows TDD and lands its own tests; the green gate is the merge
contract.

## `BATCHES.md` — the live ledger

[`BATCHES.md`](./BATCHES.md) is the canonical roadmap ledger: every batch, its
target version, its feature breakdown (which is a new crate vs. cli vs.
frontend-only), and status (✅ done · 🔄 in progress · ⬜ queued). Read it before
starting work to claim a disjoint slice; update its status as a batch ships. The
user-facing roadmap (`site/content/docs/roadmap.md`) is the orchestrator's mirror
of it.