feat(run): --render live DBFit-style page view

Single .test.md renders as a flowing document (prose + syntax-highlighted SQL
+ expected tables); each fixture card lights up green/red in place via rich.Live
as the runner executes it, with the row diff inline on failure.

chore(release): 0.3.1

Author: Jürgen Zornig

CHANGELOG.md

@@ -7,6 +7,16 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.3.1] — 2026-06-08
+
+### Added
+
+- **`--render` / `-r` — live page rendering (DBFit-browser style).** For a single
+  `.test.md`, the page is rendered in the terminal (prose, syntax-highlighted SQL,
+  expected tables) and each fixture card lights up green/red *in place* as it runs, with
+  the row diff shown inline on failure. The closest terminal analogue to watching a DBFit
+  wiki page execute in the browser.
+
 ## [0.3.0] — 2026-06-08
 
 ### Added
@@ -149,7 +159,8 @@ with code paths in place for SQL Server and Oracle.
   reject `python-oracledb` thin-mode authentication. Configuration is via
   `DBRESSION_ORACLE_CLIENT_LIB_DIR`.
 
-[Unreleased]: https://github.com/angrydat/dbression/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/angrydat/dbression/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/angrydat/dbression/releases/tag/v0.3.1
 [0.3.0]: https://github.com/angrydat/dbression/releases/tag/v0.3.0
 [0.2.0]: https://github.com/angrydat/dbression/releases/tag/v0.2.0
 [0.1.2]: https://github.com/angrydat/dbression/releases/tag/v0.1.2

README.md

@@ -15,7 +15,7 @@ anywhere. `dbression` is a Python re-implementation in the spirit of the fantast
 
 ```text
 $ dbression run tests/
-dbression 0.3.0 — Suite: tests @ postgresql+psycopg://foo:***@db01/bar
+dbression 0.3.1 — Suite: tests @ postgresql+psycopg://foo:***@db01/bar
 
 ✓ HelloSql                                  0.004s
   CommonSuite/
@@ -242,6 +242,7 @@ dbression:
 ```bash
 dbression run <suite-path>                   # run an entire (sub-)suite (a directory)
 dbression run <path>/MyTest.test.md          # run a single test file (its SuiteSetUp/_root come along)
+dbression run <path>/MyTest.test.md -r       # --render: live DBFit-style page, cards light up green/red
 dbression run <path> -d                      # --details: print each fixture green/red as it runs
 dbression run <path> --no-progress           # disable the live spinner / x-of-y counter
 dbression run <path> -v                      # show every fixture table, not just the page line
@@ -259,6 +260,11 @@ A run shows a live spinner with an `x/y fixtures` counter and the currently-exec
 query (auto-disabled when piped or in CI). Add `-d`/`--details` to stream a colored
 pass/fail line per fixture — handy next to a `.test.md` you're previewing in `glow`.
 
+For a single `.test.md`, `-r`/`--render` goes further: it renders the whole page in the
+terminal (prose, SQL, expected tables) and lights each fixture card up green or red **in
+place** as it runs — the terminal answer to watching a DBFit wiki page execute in the
+browser. You see exactly where a page breaks, in document context.
+
 ## Status
 
 `dbression` is **WIP but already useful** — running production-scale DBFit suites today across

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dbression"
-version = "0.3.0"
+version = "0.3.1"
 description = "Rage-quit your flaky DB regressions — modern, lightweight, multi-DB regression testing."
 readme = "README.md"
 license = { text = "MIT" }

src/dbression/cli.py

@@ -15,6 +15,7 @@
     ProgressObserver,
     make_progress,
     print_suite_result,
+    render_run,
     write_json_report,
     write_junit_xml,
 )
@@ -67,6 +68,15 @@ def run(
             help="Print each fixture's result (green/red) live as it runs, DBFit-web-UI style",
         ),
     ] = False,
+    render: Annotated[
+        bool,
+        typer.Option(
+            "-r",
+            "--render",
+            help="Render a single .test.md page in the terminal, cards lighting up green/red "
+            "in place as fixtures run (DBFit-browser style). Single .test.md file only.",
+        ),
+    ] = False,
     progress: Annotated[
         bool | None,
         typer.Option(
@@ -103,6 +113,13 @@ def run(
 
     tag_filter = TagFilter(only=tuple(tag or ()), skip=tuple(skip_tag or ()))
 
+    if render and not (path.is_file() and path.name.endswith(".test.md")):
+        console.print(
+            "[red]--render works on a single .test.md file[/red] "
+            "(it renders one page as a live document)."
+        )
+        raise typer.Exit(2)
+
     if path.is_dir():
         suite = parse_suite(path)
         kind = "Suite"
@@ -128,7 +145,17 @@ def run(
     total = count_fixtures(suite, tag_filter)
 
     try:
-        if use_progress:
+        if render:
+            # Live DBFit-style page render — the document IS the output.
+            result = render_run(
+                console,
+                suite,
+                engine,
+                source=path.read_text(encoding="utf-8"),
+                commit_mode=commit_mode,  # type: ignore[arg-type]
+                tag_filter=tag_filter,
+            )
+        elif use_progress:
             with make_progress(console) as prog:
                 task = prog.add_task("starting…", total=total or None)
                 observer = ProgressObserver(console, prog, task, details=details)
@@ -151,7 +178,8 @@ def run(
             )
     finally:
         engine.dispose()
-    print_suite_result(result, console, verbose=verbose)
+    if not render:
+        print_suite_result(result, console, verbose=verbose)
 
     if junit_xml is not None:
         write_junit_xml(result, junit_xml)

src/dbression/report/__init__.py

@@ -9,11 +9,13 @@
 from dbression.report.json_report import write_json_report
 from dbression.report.junit import write_junit_xml
 from dbression.report.progress import ProgressObserver, make_progress
+from dbression.report.render import render_run
 
 __all__ = [
     "ProgressObserver",
     "make_progress",
     "print_suite_result",
+    "render_run",
     "write_json_report",
     "write_junit_xml",
 ]