Metadata-Version: 2.4
Name: behave-trace
Version: 1.2.0
Summary: Trace viewer and step-by-step debugger for Behave BDD.
Project-URL: Homepage, https://github.com/MathiasPaulenko/behave-trace
Project-URL: Repository, https://github.com/MathiasPaulenko/behave-trace
Project-URL: Documentation, https://mathiaspaulenko.github.io/behave-trace/
Project-URL: Issues, https://github.com/MathiasPaulenko/behave-trace/issues
Project-URL: Changelog, https://github.com/MathiasPaulenko/behave-trace/blob/main/CHANGELOG.md
Author-email: Mathias Paulenko <mathias@paulenko.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: bdd,behave,debugger,playwright,trace,viewer
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Testing :: BDD
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: behave>=1.2.6
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: watchdog>=3.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Provides-Extra: watch
Requires-Dist: watchdog>=3.0; extra == 'watch'
Description-Content-Type: text/markdown

# behave-trace

[![CI](https://github.com/MathiasPaulenko/behave-trace/actions/workflows/ci.yml/badge.svg)](https://github.com/MathiasPaulenko/behave-trace/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/behave-trace.svg)](https://pypi.org/project/behave-trace/)
[![Python versions](https://img.shields.io/pypi/pyversions/behave-trace.svg)](https://pypi.org/project/behave-trace/)
[![License: MIT](https://img.shields.io/pypi/l/behave-trace.svg)](https://github.com/MathiasPaulenko/behave-trace/blob/main/LICENSE)
[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v0.json)](https://github.com/astral-sh/ruff)

Trace viewer and step-by-step debugger for [Behave](https://github.com/behave/behave) BDD.

Captures execution data (steps, statuses, durations, screenshots, DOM snapshots, logs)
and visualizes them in a Playwright-inspired web viewer with timeline, filmstrip, and
per-step detail tabs.

## Quickstart

```bash
# 1. Install
pip install behave-trace

# 2. Register the formatter — add to behave.ini in your project root:
#    [behave.formatters]
#    behave-trace = behave_trace.formatter:TraceFormatter

# 3. Capture — run Behave with the formatter
behave --format behave-trace -o trace.json

# 4. Visualize — open the viewer
behave-trace show trace.json
```

The viewer opens in your browser at `http://127.0.0.1:<port>` with a dark-themed
SPA showing features, scenarios, steps, screenshots, and errors.

## How it works

```text
┌──────────┐     ┌──────────────┐     ┌───────────┐     ┌──────────────┐
│  Behave  │────▶│  Formatter   │────▶│  Serializer │────▶│  trace.json  │
│  runner  │     │  (collector) │     │  (JSON)    │     │              │
└──────────┘     └──────────────┘     └───────────┘     └──────┬───────┘
                                                            │
                   ┌────────────────────────────────────────┘
                   ▼
            ┌──────────────┐     ┌──────────────────┐
            │  behave-trace │────▶│  Browser SPA     │
            │  show         │     │  (Alpine.js)     │
            │  (HTTP server)│     │  Dark theme      │
            └──────────────┘     └──────────────────┘
```

**Two-phase model** (like Playwright Trace Viewer):

1. **Capture** — The `TraceFormatter` hooks into Behave's formatter API and
   collects execution events into a `Trace` data model. Attachments (screenshots,
   DOM, logs) are captured via `attach_screenshot()`, `attach_dom()`, and `log()`
   helpers in `environment.py`.

2. **Visualize** — `behave-trace show` loads the trace JSON, starts a local HTTP
   server (stdlib only, no dependencies), and opens the viewer SPA in a browser.

## Capturing attachments

Add to your `environment.py`:

```python
from behave_trace import attach_screenshot, attach_dom, attach_text, attach_network, log

def after_step(context, step):
    # Log the current URL after every step
    log(context, f"URL: {context.driver.current_url}")

    if step.status == "failed":
        attach_screenshot(context, context.driver, name="failure.png")
        attach_dom(context, context.driver, name="dom.html")
        log(context, f"Step failed: {step.name}", level="error")
```

The viewer will show screenshots in the filmstrip and detail tabs, with
before/after DOM snapshot toggling. See the
[attachments guide](https://mathiaspaulenko.github.io/behave-trace/attachments/) for the full API.

## CLI

```bash
# Show trace in browser
behave-trace show trace.json

# Show on specific port, don't open browser
behave-trace show trace.json --port 8080 --no-browser

# Run behave with the trace formatter, then open the viewer
behave-trace run features/

# Run with tags and watch mode
behave-trace run features/ --tags @smoke --watch

# Run from the UI (no initial trace required)
# The viewer opens even if behave fails. A "Run all" button lets you
# execute tests from scratch; selected scenarios can also be re-run.
behave-trace run --no-browser

# Version
behave-trace --version
```

## Run from the UI

`behave-trace run` starts the viewer even if the initial Behave run fails or no
features have been executed yet. The viewer then shows a **"Run all"** button in
the header (and in the empty state) that triggers a fresh Behave execution
(`POST /api/run`).

While tests are running the viewer receives real-time status updates via
Server-Sent Events (SSE), and the trace is reloaded automatically when the run
finishes. You can also select one or more scenarios and re-run only those with
**"Run selected"**.

When watch mode is active, the viewer header shows an **"Auto-run"** toggle.
Enable it to re-execute Behave automatically whenever the watched `*.feature` or
`*.py` files change (debounced 500ms). Disable it to keep the viewer running and
reload the trace manually.

## Development

```bash
# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Or use the Makefile shortcut
make dev

# Lint
ruff check .
ruff format --check .

# Type check
mypy --strict behave_trace

# Run tests
pytest tests/ -v

# E2E tests (meta: Behave testing Behave)
behave tests/e2e/

# Build
python -m build
```

## Requirements

- Python **3.11+** (tested on 3.11, 3.12, 3.13)
- `behave >= 1.2.6` (installed automatically)
- No other runtime dependencies (viewer uses only Python stdlib)

## Project structure

```text
behave_trace/
    __init__.py          # Public API, formatter registration
    __main__.py          # python -m behave_trace entry point
    formatter.py         # Behave formatter (TraceFormatter)
    collector.py         # Event collector → Trace model
    models.py            # Dataclasses: Trace, Feature, Scenario, Step, etc.
    serializer.py        # JSON load/save
    attach.py            # Attachment helpers (screenshot, DOM, text, network, log)
    runner.py            # Behave runner (subprocess wrapper)
    watcher.py           # File watcher for --watch mode
    utils.py             # Utilities (format_duration, safe_str)
    cli/
        app.py           # argparse CLI with `show` and `run` subcommands
    viewer/
        server.py        # stdlib HTTP server (ThreadingHTTPServer)
        browser.py       # Browser opener (Chrome app mode)
    assets/
        index.html       # SPA shell (Alpine.js from CDN)
        css/viewer.css   # Dark theme styles
        js/viewer.js     # Alpine.js component logic
```

## Documentation

Full documentation is available at
[mathiaspaulenko.github.io/behave-trace](https://mathiaspaulenko.github.io/behave-trace/).

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup,
commands, and the release process.

## License

MIT — see [LICENSE](LICENSE).
