dbression 0.2.0__tar.gz → 0.3.1__tar.gz

{dbression-0.2.0 → dbression-0.3.1}/CHANGELOG.md

@@ -7,6 +7,33 @@ 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
+
+- **Single-file runs.** `dbression run path/to/MyTest.test.md` (or `.wiki`) now runs a
+  single test, mirroring DBFit: a file is one *Test* (many fixtures), a directory is a
+  *Suite*. The containing directory's `SuiteSetUp` / `SuiteTearDown` and `_root`
+  (connection + `DatabaseEnvironment`) are included automatically. A self-contained
+  `.test.md` carrying its own `<!-- dbression:env=… -->` / `<!-- dbression:connection=… -->`
+  directives runs standalone.
+- **Live progress.** Runs now show a spinner, an `x/y fixtures` counter, elapsed time, and
+  a status line naming the fixture/query currently executing. On by default at a TTY;
+  silenced automatically when output is piped or in CI. Toggle with `--progress` /
+  `--no-progress`.
+- **`--details` / `-d`.** Prints each fixture's result green/red as it runs (DBFit-web-UI
+  style), so a `.test.md` viewed in `glow` has a matching colored CLI run alongside it.
+
 ## [0.2.0] — 2026-06-01
 
 ### Added
@@ -21,15 +48,15 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [0.1.2] — 2026-06-01
 
-SQL Server live-verification release. A real-world MSSQL DBFit suite (WD-Gehsteig
-regression tests, stored-procedure-driven, square-bracket identifiers throughout)
+SQL Server live-verification release. A real-world MSSQL DBFit suite (regression tests,
+stored-procedure-driven, square-bracket identifiers throughout)
 runs end-to-end against an MSSQL Server 2019 via `pymssql` with no changes to the
 underlying `.wiki` files.
 
 ### Fixed
 
 - **Console reporter swallowed `[…]` in failure details.** Rich's inline-markup
-  parser interpreted MSSQL square-bracket identifiers like `[wdg].PLAENE` as
+  parser interpreted MSSQL square-bracket identifiers like `[dbo].ORDER` as
   style tags and stripped them from the displayed SQL — making failure output
   misleading. Reporter now prints fixture details with `markup=False`, so the
   SQL you see is the SQL that ran.
@@ -132,7 +159,9 @@ 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.2.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
 [0.1.1]: https://github.com/angrydat/dbression/releases/tag/v0.1.1

{dbression-0.2.0 → dbression-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dbression
-Version: 0.2.0
+Version: 0.3.1
 Summary: Rage-quit your flaky DB regressions — modern, lightweight, multi-DB regression testing.
 Project-URL: Homepage, https://angrydata.info/dbression
 Project-URL: Repository, https://github.com/angrydat/dbression
@@ -52,19 +52,19 @@ anywhere. `dbression` is a Python re-implementation in the spirit of the fantast
 
 ```text
 $ dbression run tests/
-dbression 0.2.0 — Suite: tests @ postgresql+psycopg://wlk:***@db01/wlk
+dbression 0.3.1 — Suite: tests @ postgresql+psycopg://foo:***@db01/bar
 
 ✓ HelloSql                                  0.004s
   CommonSuite/
-    MerklisteSuite/
+    ChangelistSuite/
       ✓ AAddBasicTest                       0.027s
       ✓ BAddNormalizationTest               0.029s
       ✓ CAddWhitelistTest                   0.025s
       ✓ DAddInvalidArgsTest                 0.014s
       ✓ ERemTest                            0.052s
-      ✓ FViewWbTest                         1.236s
-  EreignisSuite/
-    WaldbrandSuite/
+      ✓ FViewTest                           1.236s
+  EventsSuite/
+    FireSuite/
       ✓ LookupTest                          0.157s
       ✗ SchemaTest                          0.013s
 
@@ -277,7 +277,11 @@ dbression:
 ## CLI cheat sheet
 
 ```bash
-dbression run <suite-path>                   # run an entire (sub-)suite
+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
 dbression run <path> --tag critical          # only run pages tagged `critical`
 dbression run <path> --skip-tag NotOnCI      # skip pages tagged `NotOnCI`
@@ -289,37 +293,14 @@ dbression convert file.wiki -o out.test.md   # single file with explicit output
 dbression version
 ```
 
-## How it works
+A run shows a live spinner with an `x/y fixtures` counter and the currently-executing
+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`.
 
-```
-┌─────────────────────────────────────────────────────────┐
-│  CLI (typer)        dbression run tests/  [--flags]     │
-└─────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────┐  ┌───────────────────────────────┐
-│  Parser             │  │  Engine Factory (SQLAlchemy)  │
-│  Wiki → AST         │  │  ┌──────────┐ ┌──────────┐    │
-│  • !- -! escapes    │  │  │ psycopg  │ │ oracledb │    │
-│  • q'~ ~' quoting   │  │  │ (Postgres│ │  (thin)  │    │
-│  • Nested suites    │  │  └──────────┘ └──────────┘    │
-│  • YAML front matter│  │  ┌──────────────────────┐     │
-└─────────┬───────────┘  │  │ pymssql (SQL Server) │     │
-          │              │  └──────────────────────┘     │
-          ▼              └───────────┬───────────────────┘
-┌─────────────────────────────────────┴───────────────────┐
-│  Runner — one TX per suite, savepoints per test         │
-│  Symbol engine: >>capture, <<read, :bind, _:text-subst  │
-│  Fixture registry — pluggable via decorator             │
-└─────────────────────┬───────────────────────────────────┘
-                      ▼
-┌─────────────────────────────────────────────────────────┐
-│  Reporters                                              │
-│  • Rich console (default)                               │
-│  • JUnit XML (--junit-xml)                              │
-│  • JSON (--json)                                        │
-└─────────────────────────────────────────────────────────┘
-```
+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-0.2.0 → dbression-0.3.1}/README.md

@@ -15,19 +15,19 @@ anywhere. `dbression` is a Python re-implementation in the spirit of the fantast
 
 ```text
 $ dbression run tests/
-dbression 0.2.0 — Suite: tests @ postgresql+psycopg://wlk:***@db01/wlk
+dbression 0.3.1 — Suite: tests @ postgresql+psycopg://foo:***@db01/bar
 
 ✓ HelloSql                                  0.004s
   CommonSuite/
-    MerklisteSuite/
+    ChangelistSuite/
       ✓ AAddBasicTest                       0.027s
       ✓ BAddNormalizationTest               0.029s
       ✓ CAddWhitelistTest                   0.025s
       ✓ DAddInvalidArgsTest                 0.014s
       ✓ ERemTest                            0.052s
-      ✓ FViewWbTest                         1.236s
-  EreignisSuite/
-    WaldbrandSuite/
+      ✓ FViewTest                           1.236s
+  EventsSuite/
+    FireSuite/
       ✓ LookupTest                          0.157s
       ✗ SchemaTest                          0.013s
 
@@ -240,7 +240,11 @@ dbression:
 ## CLI cheat sheet
 
 ```bash
-dbression run <suite-path>                   # run an entire (sub-)suite
+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
 dbression run <path> --tag critical          # only run pages tagged `critical`
 dbression run <path> --skip-tag NotOnCI      # skip pages tagged `NotOnCI`
@@ -252,37 +256,14 @@ dbression convert file.wiki -o out.test.md   # single file with explicit output
 dbression version
 ```
 
-## How it works
+A run shows a live spinner with an `x/y fixtures` counter and the currently-executing
+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`.
 
-```
-┌─────────────────────────────────────────────────────────┐
-│  CLI (typer)        dbression run tests/  [--flags]     │
-└─────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────┐  ┌───────────────────────────────┐
-│  Parser             │  │  Engine Factory (SQLAlchemy)  │
-│  Wiki → AST         │  │  ┌──────────┐ ┌──────────┐    │
-│  • !- -! escapes    │  │  │ psycopg  │ │ oracledb │    │
-│  • q'~ ~' quoting   │  │  │ (Postgres│ │  (thin)  │    │
-│  • Nested suites    │  │  └──────────┘ └──────────┘    │
-│  • YAML front matter│  │  ┌──────────────────────┐     │
-└─────────┬───────────┘  │  │ pymssql (SQL Server) │     │
-          │              │  └──────────────────────┘     │
-          ▼              └───────────┬───────────────────┘
-┌─────────────────────────────────────┴───────────────────┐
-│  Runner — one TX per suite, savepoints per test         │
-│  Symbol engine: >>capture, <<read, :bind, _:text-subst  │
-│  Fixture registry — pluggable via decorator             │
-└─────────────────────┬───────────────────────────────────┘
-                      ▼
-┌─────────────────────────────────────────────────────────┐
-│  Reporters                                              │
-│  • Rich console (default)                               │
-│  • JUnit XML (--junit-xml)                              │
-│  • JSON (--json)                                        │
-└─────────────────────────────────────────────────────────┘
-```
+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-0.2.0 → dbression-0.3.1}/pyproject.toml

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

{dbression-0.2.0 → dbression-0.3.1}/src/dbression/cli.py

@@ -8,11 +8,18 @@ import typer
 from rich.console import Console
 
 from dbression import __version__
-from dbression.parser import parse_suite
+from dbression.parser import parse_suite, parse_test_file
 from dbression.parser.markdown_writer import page_to_markdown
 from dbression.parser.wiki import parse_wiki
-from dbression.report import print_suite_result, write_json_report, write_junit_xml
-from dbression.runner import TagFilter, build_engine_for_suite, run_suite
+from dbression.report import (
+    ProgressObserver,
+    make_progress,
+    print_suite_result,
+    render_run,
+    write_json_report,
+    write_junit_xml,
+)
+from dbression.runner import TagFilter, build_engine_for_suite, count_fixtures, run_suite
 
 app = typer.Typer(
     name="dbression",
@@ -37,7 +44,12 @@ def version() -> None:
 
 @app.command()
 def run(
-    path: Annotated[Path, typer.Argument(help="Path to the suite (directory containing _root.wiki)")],
+    path: Annotated[
+        Path,
+        typer.Argument(
+            help="A suite directory (with _root.wiki) OR a single test file (.test.md / .wiki)"
+        ),
+    ],
     commit_mode: Annotated[
         str,
         typer.Option(
@@ -48,6 +60,30 @@ def run(
     verbose: Annotated[
         bool, typer.Option("-v", "--verbose", help="Print every fixture table, not just the page line")
     ] = False,
+    details: Annotated[
+        bool,
+        typer.Option(
+            "-d",
+            "--details",
+            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(
+            "--progress/--no-progress",
+            help="Live spinner + x/y fixture counter (default: on when stdout is a terminal)",
+        ),
+    ] = None,
     tag: Annotated[
         list[str] | None,
         typer.Option(
@@ -68,10 +104,7 @@ def run(
         typer.Option("--json", help="Write a JSON report to this path (LLM / tooling)"),
     ] = None,
 ) -> None:
-    """Run a dbression suite and produce pytest-style reporting."""
-    if not path.is_dir():
-        console.print(f"[red]Not a directory:[/red] {path}")
-        raise typer.Exit(2)
+    """Run a dbression test (single file) or suite (directory) with live progress."""
     if commit_mode not in ("test", "page"):
         console.print(
             f"[red]Invalid commit-mode: {commit_mode!r} (allowed: test, page)[/red]"
@@ -80,17 +113,73 @@ def run(
 
     tag_filter = TagFilter(only=tuple(tag or ()), skip=tuple(skip_tag or ()))
 
-    suite = parse_suite(path)
+    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"
+    elif path.is_file():
+        try:
+            suite = parse_test_file(path)
+        except ValueError as e:
+            console.print(f"[red]{e}[/red]")
+            raise typer.Exit(2)
+        kind = "Test"
+    else:
+        console.print(f"[red]Path does not exist:[/red] {path}")
+        raise typer.Exit(2)
+
     engine = build_engine_for_suite(suite)
     console.print(
-        f"dbression {__version__} — Suite: [bold]{suite.name}[/bold] @ "
+        f"dbression {__version__} — {kind}: [bold]{suite.name}[/bold] @ "
         f"{engine.url.render_as_string(hide_password=True)}\n"
     )
+
+    # Progress is on by default at a TTY; --progress / --no-progress override.
+    use_progress = console.is_terminal if progress is None else progress
+    total = count_fixtures(suite, tag_filter)
+
     try:
-        result = run_suite(suite, engine, commit_mode=commit_mode, tag_filter=tag_filter)  # type: ignore[arg-type]
+        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)
+                result = run_suite(
+                    suite,
+                    engine,
+                    commit_mode=commit_mode,  # type: ignore[arg-type]
+                    tag_filter=tag_filter,
+                    observer=observer,
+                )
+        else:
+            # No live bar (piped / CI). Still stream colored detail lines if asked.
+            observer = ProgressObserver(console, details=details) if details else None
+            result = run_suite(
+                suite,
+                engine,
+                commit_mode=commit_mode,  # type: ignore[arg-type]
+                tag_filter=tag_filter,
+                observer=observer,
+            )
     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)

dbression-0.3.1/src/dbression/parser/__init__.py

@@ -0,0 +1,12 @@
+from dbression.parser.ast import Directive, Page, Suite, Table
+from dbression.parser.wiki import parse_suite, parse_test_file, parse_wiki
+
+__all__ = [
+    "Directive",
+    "Page",
+    "Suite",
+    "Table",
+    "parse_suite",
+    "parse_test_file",
+    "parse_wiki",
+]

{dbression-0.2.0 → dbression-0.3.1}/src/dbression/parser/wiki.py

@@ -203,3 +203,66 @@ def parse_suite(root: Path) -> Suite:
     # Stable, deterministic order of test pages (alphabetical).
     suite.pages.sort(key=lambda p: p.name)
     return suite
+
+
+def _discover_special_pages(root: Path) -> dict[str, Page]:
+    """Parse only ``_root`` / ``SuiteSetUp`` / ``SuiteTearDown`` in `root` (md > wiki).
+
+    Used by single-file runs to pull in the surrounding directory's connection config
+    and setup/teardown without dragging in sibling test pages.
+    """
+    from dbression.parser.markdown import MARKDOWN_TEST_SUFFIX, parse_markdown
+
+    wanted = {"_root", "SuiteSetUp", "SuiteTearDown"}
+    if not root.is_dir():
+        return {}
+    found: dict[str, tuple[Path, str]] = {}
+    for entry in sorted(root.iterdir()):
+        if entry.is_dir():
+            continue
+        if entry.name.endswith(MARKDOWN_TEST_SUFFIX):
+            pn = entry.name[: -len(MARKDOWN_TEST_SUFFIX)]
+            if pn in wanted:
+                found[pn] = (entry, "md")
+        elif entry.suffix == ".wiki":
+            pn = entry.stem
+            if pn in wanted:
+                found.setdefault(pn, (entry, "wiki"))
+    out: dict[str, Page] = {}
+    for pn, (p, fmt) in found.items():
+        out[pn] = parse_markdown(p) if fmt == "md" else parse_wiki(p)
+    return out
+
+
+def parse_test_file(path: Path) -> Suite:
+    """Parse a single test FILE (``.test.md`` or ``.wiki``) into a runnable one-page Suite.
+
+    DBFit semantics: a file is one **Test** (many fixtures/assertions); a directory is a
+    **Suite**. When a single test is run, the surrounding directory's ``SuiteSetUp`` /
+    ``SuiteTearDown`` and ``_root`` (``DatabaseEnvironment`` + ``ConnectUsingFile``) are
+    included — just like opening a single page in the DBFit web UI runs its SuiteSetUp.
+
+    A self-contained ``.test.md`` that carries its own ``<!-- dbression:env=… -->`` /
+    ``<!-- dbression:connection=… -->`` directives runs standalone: those become the
+    suite's engine config (resolved relative to the file's directory).
+    """
+    from dbression.parser.markdown import MARKDOWN_TEST_SUFFIX, parse_markdown
+
+    if not path.is_file():
+        raise ValueError(f"Not a file: {path}")
+    if path.name.endswith(MARKDOWN_TEST_SUFFIX):
+        page = parse_markdown(path)
+    elif path.suffix == ".wiki":
+        page = parse_wiki(path)
+    else:
+        raise ValueError(f"Not a runnable test file (expected .test.md or .wiki): {path}")
+
+    root = path.parent
+    suite = Suite(root=root, name=page.name, pages=[page])
+    specials = _discover_special_pages(root)
+    suite.setup = specials.get("SuiteSetUp")
+    suite.teardown = specials.get("SuiteTearDown")
+    # Engine config precedence: a real `_root` in the directory wins; otherwise the test
+    # file's own env/connection directives make it self-contained.
+    suite.root_page = specials.get("_root") or page
+    return suite

{dbression-0.2.0 → dbression-0.3.1}/src/dbression/report/__init__.py

@@ -1,11 +1,21 @@
 """Reporters for SuiteResult data.
 
 * `console`     — pytest-style rich output (default CLI output)
+* `progress`    — live spinner + x/y counter + per-fixture detail lines (`--details`)
 * `junit`       — JUnit XML for Bitbucket Pipelines, Jenkins, GitLab, etc.
 * `json_report` — JSON for LLM tooling, custom dashboards, diff analyses
 """
 from dbression.report.console import print_suite_result
 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__ = ["print_suite_result", "write_json_report", "write_junit_xml"]
+__all__ = [
+    "ProgressObserver",
+    "make_progress",
+    "print_suite_result",
+    "render_run",
+    "write_json_report",
+    "write_junit_xml",
+]

dbression-0.3.1/src/dbression/report/progress.py

@@ -0,0 +1,113 @@
+"""Live progress + optional per-fixture detail output for ``dbression run``.
+
+Two things this module provides:
+
+* :func:`make_progress` — a Rich ``Progress`` with a spinner, an ``x/y`` fixture counter,
+  the elapsed time, and a status line showing which fixture/query is currently running.
+* :class:`ProgressObserver` — a :class:`~dbression.runner.RunObserver` that drives the
+  progress bar and, in ``--details`` mode, prints a colored pass/fail line per fixture
+  (DBFit-web-UI style) above the live bar.
+
+The observer is deliberately defensive about Rich markup: fixture names and SQL contain
+``[…]`` (MSSQL identifiers, array literals) which Rich would otherwise interpret as style
+tags. All dynamic text is rendered through ``rich.text.Text`` (no markup parsing).
+"""
+from __future__ import annotations
+
+from rich.console import Console
+from rich.progress import (
+    BarColumn,
+    MofNCompleteColumn,
+    Progress,
+    SpinnerColumn,
+    TextColumn,
+    TimeElapsedColumn,
+)
+from rich.text import Text
+
+from dbression.fixtures.base import FixtureResult
+from dbression.parser.ast import Table
+from dbression.runner import RunObserver
+
+
+def make_progress(console: Console) -> Progress:
+    """Build the live progress display (spinner + status + x/y counter + elapsed)."""
+    return Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(bar_width=None),
+        MofNCompleteColumn(),
+        TextColumn("fixtures"),
+        TimeElapsedColumn(),
+        console=console,
+        transient=True,  # clear the bar when done so the summary stands alone
+    )
+
+
+def _fixture_preview(table: Table, maxlen: int = 72) -> str:
+    """A one-line, whitespace-collapsed preview of what this fixture runs."""
+    text = " ".join(str(a) for a in table.header_args)
+    text = " ".join(text.split())
+    if len(text) > maxlen:
+        text = text[: maxlen - 1] + "…"
+    return text
+
+
+class ProgressObserver(RunObserver):
+    """Drive a Rich ``Progress`` task and optionally print per-fixture detail lines.
+
+    Works in two modes:
+
+    * with a ``progress``/``task_id`` (TTY): updates the live bar and, if ``details``,
+      prints detail lines above it via the progress console.
+    * without a progress bar (non-TTY but ``details`` requested): prints detail lines
+      straight to ``console``.
+    """
+
+    def __init__(
+        self,
+        console: Console,
+        progress: Progress | None = None,
+        task_id: int | None = None,
+        *,
+        details: bool = False,
+    ) -> None:
+        self.console = console
+        self.progress = progress
+        self.task_id = task_id
+        self.details = details
+
+    def _out(self) -> Console:
+        return self.progress.console if self.progress is not None else self.console
+
+    def on_fixture_start(self, page_name: str, table: Table) -> None:
+        if self.progress is None or self.task_id is None:
+            return
+        preview = _fixture_preview(table)
+        label = f"{page_name} › {table.name}"
+        if preview:
+            label += f": {preview}"
+        # Description is rendered with markup; Text() keeps brackets literal.
+        self.progress.update(self.task_id, description=Text(label, style="cyan"))
+
+    def on_fixture_end(
+        self, page_name: str, table: Table, result: FixtureResult, duration: float
+    ) -> None:
+        if self.progress is not None and self.task_id is not None:
+            self.progress.advance(self.task_id)
+        if not self.details:
+            return
+        line = Text()
+        if result.passed:
+            line.append("✓ ", style="bold green")
+        else:
+            line.append("✗ ", style="bold red")
+        line.append(page_name, style="bold")
+        line.append(" › ")
+        line.append(table.name, style="" if result.passed else "red")
+        line.append(f"  {duration * 1000:.0f}ms", style="dim")
+        self._out().print(line)
+        if result.message:
+            self._out().print(
+                Text("    " + result.message, style="dim" if result.passed else "red")
+            )