proef — documentation index
proef (Dutch: test, trial — and tasting) is a declarative, modular, multi-engine
end-to-end test runner, mostly Rust. Tests are Gherkin .feature files in business prose;
macro packs bind the prose to executable steps; a pluggable engine runs each step batch —
embedded Hurl for API testing (the seam admits future engines; none are scheduled).
This folder is the project corpus: the product requirements, the decision log, the
normative technical spec, the milestone plan, and the testing strategy. Written
2026-07-28 from a validated research round (a working spike ran 5/5 scenarios green
under both a prototype native runner and stock hurl 8.0.1 on identical generated
artifacts); implementation has since delivered milestones M0–M5 and everything after
them — through v0.19.0 (the 0.18 survey waves, then the gates that could not see
what they covered). Only M6 (a second
engine) is unscheduled. The repo-root CLAUDE.md carries the live status. This
corpus is also published as a website: https://emrecdr.github.io/proef/.
Reading order
| # | Document | What it answers | Audience |
|---|---|---|---|
| 0 | WRITING-SCENARIOS.md | Write prose against a vocabulary somebody else maintains: see the sentences, the dry-run loop, the two errors you will hit | P1 test authors |
| 0 | GETTING-STARTED.md | Your first suite in ten minutes — including the packs behind it | P2 pack maintainers |
| 0 | AUTHORING.md | The pack/feature reference from the author’s seat | P2 pack maintainers |
| 0 | EDITORS.md | Wiring proef lsp into Neovim/Helix/Emacs for live diagnostics, jump-to-macro, completion | P1/P2, whoever sets up the editor |
| 0 | TROUBLESHOOTING.md | Exit codes, glyphs, frequent failures, digging into runs | everyone |
| 0 | CONFIG.md | Every proef.toml key with defaults | P2 pack maintainers |
| 0 | DIAGNOSTICS.md | The greppable index of every diagnostic code | P2 pack maintainers |
| 0 | EVENTS.md | The events.jsonl wire schema for CI consumers | CI engineers |
| 1 | PRD.md | What are we building, for whom, and how do we know it works? | everyone |
| 2 | adr/ — ADR-0001 onward | Why is it built this way? Each decision, alternatives, consequences | engineers |
| 3 | TECH-SPEC.md | How exactly is it built? Types, pipeline, schemas, verified seam facts | implementers |
| 4 | IMPLEMENTATION-PLAN.md | In what order, with what acceptance criteria? M0–M6 task breakdown, risks, runbooks | implementers |
| 5 | TESTING-STRATEGY.md | How is every layer verified? | implementers |
| — | IMPROVEMENT-PLAN.md | Post-M5 competitive review: the feature roadmap, each item carrying a Status column (14 of 16 shipped) | maintainers |
| — | OPEN-FINDINGS.md | The worklist. Every open defect and gap, whichever review found it, plus what shipped against each | maintainers |
| — | RELEASING.md | Versioning policy and the release runbook | maintainers |
| — | CONTRIBUTING.md | Setup, gates, and the rules that are easy to trip over | contributors |
| — | SECURITY.md | Threat model and vulnerability reporting | everyone |
| — | CHANGELOG.md | Per-release change log (SemVer) | everyone |
| — | ../CLAUDE.md | Repo-root guidance for Claude Code: constraints, seam facts, commands, status | coding agents |
Decision log (ADR index)
| ADR | Decision | Status |
|---|---|---|
| 0001 | Embed hurl’s crates in-process as the API engine | Accepted |
| 0002 | Multi-engine core: EngineFactory/EngineSession seam, step-kind routing, batching | Accepted |
| 0003 | Exact pins + thin zero-diff fork as patch vehicle + upgrade canary | Accepted |
| 0004 | Packs = YAML skeleton + embedded raw Hurl blocks | Accepted |
| 0005 | ${…} author-time / {{…}} run-time variables; World; secrets | Accepted |
| 0006 | Engine traits are sync + dyn; no async machinery in v1 | Accepted |
| 0007 | Cooperative cancellation at batch boundaries + budgets (hurl has none) | Accepted |
| 0008 | Serde event enum = run record; decorator reporter stack; libtest-mimic mode | Accepted |
| 0009 | User/TestFailure/System → exit 2/1/3; miette at the CLI edge | Accepted |
| 0010 | Emitted .hurl artifacts are the executed input (same bytes) + sidecars | Accepted |
| 0011 | Fixture server is synchronous tiny_http, not axum (tokio-runtime ban) | Accepted |
| 0012 | Project config & environments in proef.toml ([url]/[vars]/[env.*], --env, deep-merge) | Accepted |
| 0013 | Typed macro parameters (params name→type map; best-effort literal-args lint) | Proposed (defer) |
| 0014 | Suite-level setup/teardown ([run] setup/teardown features, CLI-edge orchestration) | Accepted |
| 0015 | Injected run-relative timestamps + worker id (sink-stamped, sans-IO core) for the HTML timeline | Accepted |
| 0016 | OpenAPI → suite generator: one-shot seed allowed under a bright line; oracle/drift mode permanently rejected | Proposed (defer) |
| 0017 | proef lsp language server: sync lsp-server, whole-suite wholesale recompute, injectable-provider + collect-all front-end refactor | Accepted |
| 0018 | Named hurl fragments: ref: as a second macro body form, # @proef <name> in real .hurl files, explicit bind: scopes | Accepted |
| 0019 | Reserved tags and the authored skip: @skip[:reason] at the CLI edge, reasons in every sink, authored-vs-mechanical split for --rerun, quarantine aligned in JUnit | Accepted |
| 0020 | Run metadata is explicit-injection-only: --meta/[meta]/[env.<name>.meta], run_started gains env/metadata/shuffled, harvested-vs-handed-over is the boundary | Accepted |
| 0021 | Run discovery and rotation are separate questions: a directory is a record because it holds one, rotation still deletes only uuid-named dirs, ordering follows the uuid-v7 timestamp, then mtime | Accepted |
Naming & identifiers
Project/binary proef · crates proef-core, proef-engine-hurl, proef-cli,
proef-fixture, proef-harness, proef-lsp
· run records .proef-runs/ · persistent
World .proef-state.json · config proef.toml. The crates.io names
proef, proef-core, proef-engine-hurl, and proef-lsp are published and owned.
Provenance
Grounded in two verified sources: (1) hurl master (Orange-OpenSource) — source-level verification of every library seam used, with file:line citations in TECH-SPEC §5; (2) a working spike proving the front end and artifact contract end to end (the spike predates this repo). Ecosystem practices are drawn from cargo-nextest, cucumber-rs, sqlx, rustls, probe-rs, and current (2026) Rust guidance.