# test-driver

Agentic framework for integration, end-to-end, multi-user interaction and
security testing, driven by use cases.

Tests mature alongside the software they protect: fluid and agentic while
behaviour is changing, deterministic once it settles. See `INTENT.md` for the
thesis and `SCOPE.md` for boundaries.

**Status:** research prototype. Deterministic claims, heuristic discovery,
adaptation classification and crystallization run locally. Three synthetic
multi-user use cases and a 38-mutation catalogue exercise the model. Live-model
economics, browser-engine coverage and independent authoring-cost measurement
remain blocked in `workplans/TD-WP-0003-generalise-and-settle.md`.
See [readiness and interface decisions](docs/TestDriverGeneralisationReview.md).

## Run

```bash
python3 -m pytest -q          # the whole suite
python3 -m pytest -q tests/test_reference_scenario.py
```

No third-party dependencies. Python ≥ 3.11, pytest for the suite.

## Layout

```
src/testdriver/   the kernel — intent, world, actions, drivers,
                  observers, oracles, evidence, runner
usecases/         durable test intent, including not-yet-runnable use cases
lab/              the system under test
scenarios/        reference scenarios
research/         hypotheses, experiments, findings, fitness map
docs/             concept model, improvement loop, milestones, design notes
history/          assessments and completed-work write-ups
```

## Reading order

1. `INTENT.md` — the thesis
2. `docs/TestDriverConceptModel.md` — canonical concept set
3. `docs/TestDriverClassificationDesign.md` — why adaptation cannot normalize a
   defect, and where model judgment is and is not permitted
4. `docs/TestDriverInitialMilestones.md` — canonical milestones M0–M10