Cleaner test output, clearer APIs, and publish-ready docs#11
Merged
dcrockwell merged 1 commit intodevelopfrom Dec 27, 2025
Merged
Cleaner test output, clearer APIs, and publish-ready docs#11dcrockwell merged 1 commit intodevelopfrom
dcrockwell merged 1 commit intodevelopfrom
Conversation
## Why This Change Was Made - The framework needed a consistent, pipe-friendly public API across runners, reporters, Gherkin, and matchers. - Reporting needed a deterministic, parallel-safe model: live progress during execution, and traversal-ordered final results at the end. - Docs/examples needed to be “publish quality” and aligned with the actual API (no stale snippets, no imaginary hooks). ## What Was Changed - Runner/reporting architecture: - Introduced an event-driven runner model with a dedicated progress reporter during execution and results reporters rendered at end-of-run. - Added configurable output sinks (`runner.output(Output(out: ..., error: ...))`) and `runner.silent()`. - Ensured `RunFinished` carries traversal-ordered results for deterministic end reports. - Reporters: - Refactored BDD + JSON into end-of-run results reporters with `new()` + pipe-friendly toggles. - Added `bdd.color()` and improved failure rendering using structured failure payloads (not string pattern matching). - Added/updated progress reporter to consume events safely and stay accurate under hook failures. - Parallel execution correctness: - Fixed timeout/crash attribution to preserve original test metadata. - Fixed progress accounting when tests are synthesized (e.g. `before_all` failure cascades). - Gherkin: - Standardized step registry creation to `steps.new()` (renamed from `new_registry`) and updated all references. - Improved Gherkin scenario formatting and examples (inline DSL + `.feature` files). - Examples and docs: - Added `examples/failure_showcase` (intentionally failing demo project) and wired `make all` to run it without failing the whole build. - Updated all narrative docs, README, and snippet-backed examples to match the new v2 API and reporting model. - Added a “Custom reporters” section explaining current extensibility (output routing + post-run formatters). - Repo hygiene: - Removed tracked `.cursor/plans/*` files from git (plans are ignored and should not be versioned). ## Note to Future Engineer - The failure showcase is *supposed* to fail. If it ever turns green, either someone “fixed” the demo or reality has finally stopped producing bugs. - If you change reporter extensibility, update the docs first—future-you deserves fewer archeological digs through commit history.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Dream Test’s public surface had grown inconsistent across the runner, reporters, Gherkin, and matchers. Reporting also needed to stay readable under parallel execution while producing deterministic end-of-run output. Finally, the docs and examples needed to be “publish quality” and match reality.
What
bdd.color()), including more helpful, structured failure rendering.steps.new(); examples improved for both inline DSL and.featurefiles).make all.How
new()+ pipe-friendly toggles..cursor/plans/*from git.Notes