reportage

reportage is an explicit, runtime-agnostic, coverage-aware E2E scenario runner with shell-like actions.

It starts with CLI E2E tests, but the execution model is intentionally built around adapters and PATH shims so that other runtime targets, such as web framework processes, can be supported later.

reportage is inspired by Go's testscript, especially its lightweight script-oriented approach to E2E testing. It is not intended to be a compatible implementation. The v0 design focuses on explicit, structured scenarios with shell-like actions, per-case isolation, assertion blocks with checkpoint-based verification, case-local parameterized tests, and coverage-aware command execution through adapters.

Status

reportage is in early design. The documents in this repository describe the intended v0 direction and may change as implementation work validates or rejects specific choices.

Quick Start

curl -fsSL https://raw.githubusercontent.com/tooppoo/rellog/refs/heads/main/install.sh | sh

Documentation

• Philosophy: design principles and scope boundaries.
• Syntax: normative v0 syntax grammar, generated from crates/reportage-core/src/reportage.pest.
• Semantics: entry point for the semantics document set, plus language semantic rules such as value literals, expectations, and assertion evaluation.
• Execution Model: runner execution order, case workspace lifecycle, checkpoints, shell execution, and coverage adapter responsibilities.
• Testing: how reportage tests itself, self-testing, Rust integration tests, and Rust unit tests, and how to choose between them.
• Why reportage? / Why not reportage?: When does reportage work well, and when does it not?
• Design Principles: thin core, transparent shims, opt-in adapters, and evidence-first boundaries.
• v0 Technical Selection: implementation foundation and links to detailed technical specs.
• Configuration: KDL v2 config shape, commands, tests, and validation rules.
• Path Matching: path-like config value rules and test glob semantics.
• Artifacts: default artifact generation and early result layout.
• ADR: durable architecture and design decisions.
• TBD: intentionally deferred features and design topics.

v0 Direction

The v0 design is intentionally narrow. Items currently in the grammar (docs/syntax.md):

• POSIX shell execution for $ steps.
• Native Windows shell execution is out of scope; use WSL, a devcontainer, or Linux CI on Windows.
• One test file may contain multiple case blocks.
• Each concrete case runs in an isolated workspace.
• Registered commands are resolved through PATH shims.
• Coverage integration belongs to adapters and shims; reportage does not implement a coverage engine.

Planned for v0 but not yet declared in reportage.pest:

• before_each is optional, at most one per file, and runs before every concrete case.
• params are case-local in v0.
• Each parameter variant expands into a concrete case.
• assert ... jq ... uses external jq in v0.

Non-goals for v0

• No native Windows shell support.
• No before_all or after_all.
• No after_each unless a concrete need appears later.
• No module-scope parameters in v0.
• No embedded jq engine in v0.
• No full shell parser or shell rewriting.
• No hidden fixture namespace such as @fixture in v0.