# thea-recorder

**Record your E2E browser tests as MP4 videos with live panel overlays and interactive HTML reports.**

Your tests already prove your app works. But when they fail at 3am in CI, you're left staring at a stack trace trying to imagine what the browser was doing. thea-recorder captures everything — the browser, your test steps, custom status panels — as a video, then generates a report where you can click any step and watch exactly what happened.

## Why

E2E tests are the most expensive tests you write. They're slow, flaky, and when they break, they're the hardest to debug. The typical debugging cycle looks like:

1. Read the failure log
2. Try to reproduce locally
3. Add more logging
4. Push, wait for CI, read logs again
5. Repeat

This is absurd. Your browser was *right there* doing the thing. You just weren't watching.

thea-recorder fixes this by recording the virtual display during test execution. Every scenario gets its own MP4. The panel overlay shows you which step is running, the current status, and any custom context you want. The HTML report lets you click a step and the video seeks to that exact moment.

**You stop guessing. You start watching.**

## Features

- **HTTP server + native SDKs** — use from Go, Python, Ruby, TypeScript, or Java
- **CLI** — server mode and client mode, scriptable from any language
- **Panel overlay system** — named columns below the viewport with live-updating text
- **Smart scrolling** — panels auto-scroll to keep the active content visible
- **Interactive HTML reports** — embedded videos with clickable step timelines
- **Framework agnostic** — works with any test runner in any language
- **Docker ready** — example Dockerfile and E2E test suite included

## Install

```bash
pip install thea-recorder
```

System dependencies (in your Docker image or CI runner):
```bash
apt install xvfb ffmpeg x11-xserver-utils fonts-dejavu-core
```

## Quick start — HTTP server

Start the server:
```bash
thea serve --port 9123
```

Then use any SDK:

**Go**
```go
client := recorder.NewClient("http://localhost:9123")
client.StartDisplay(ctx)
stop, _ := client.Recording(ctx, "login_test")
defer stop()
// ... run your browser test ...
```

**Python**
```python
from thea import RecorderClient
client = RecorderClient("http://localhost:9123")
client.start_display()
with client.recording("login_test"):
    # ... run your browser test ...
    pass
```

**TypeScript**
```typescript
const client = new RecorderClient({ url: "http://localhost:9123" });
await client.startDisplay();
await client.recording("login_test", async () => {
  // ... run your Playwright test ...
});
```

**Ruby**
```ruby
client = Recorder::Client.new("http://localhost:9123")
client.start_display
client.recording("login_test") do
  # ... run your browser test ...
end
```

**Java**
```java
try (var client = new RecorderClient("http://localhost:9123")) {
    client.startDisplay();
    client.recording("login_test", c -> {
        // ... run your Selenium test ...
    });
}
```

## Quick start — Python library

```python
from recorder import Recorder, generate_report

recorder = Recorder(output_dir="./recordings", display=99)
recorder.add_panel("status", title="Status", width=120)
recorder.add_panel("steps", title="Steps")
recorder.start_display()

recorder.start_recording("login_test")
recorder.update_panel("status", "Running")
recorder.update_panel("steps", "  Given a user\n* When I log in\n  Then I see the dashboard")

# ... run your browser automation here (on DISPLAY :99) ...

video = recorder.stop_recording()

generate_report(
    videos=[{
        "feature": "Authentication",
        "scenario": "Login",
        "status": "passed",
        "video": video,
        "steps": [
            {"keyword": "Given", "name": "a user", "status": "passed", "offset": 0.0},
            {"keyword": "When", "name": "I log in", "status": "passed", "offset": 2.5},
            {"keyword": "Then", "name": "I see the dashboard", "status": "passed", "offset": 5.0},
        ],
    }],
    output_dir="./recordings",
    title="My Test Report",
)

recorder.cleanup()
```

## CLI

```bash
# Server mode
thea serve --port 9123 --output-dir ./recordings --cors

# Client mode (talks to running server)
thea --server http://localhost:9123 start-display
thea --server http://localhost:9123 add-panel --name editor --title "Code" --width 80
thea --server http://localhost:9123 start-recording --name login_test
thea --server http://localhost:9123 stop-recording
thea --server http://localhost:9123 list-recordings
thea --server http://localhost:9123 health
```

Set `RECORDER_URL` to avoid repeating `--server`:
```bash
export RECORDER_URL=http://localhost:9123
thea health
thea start-display
thea start-recording --name my-test
```

## Docker

```dockerfile
FROM python:3.12-slim

RUN apt-get update && apt-get install -qyy --no-install-recommends \
    chromium-driver xvfb ffmpeg x11-xserver-utils fonts-dejavu-core \
    && rm -rf /var/lib/apt/lists/*

RUN pip install thea-recorder
EXPOSE 9123
CMD ["thea", "serve", "--host", "0.0.0.0", "--port", "9123"]
```

## Panel system

Panels are named overlay columns rendered below the browser viewport in a dark bar. They update in real-time during recording.

```python
# Fixed-width panel
recorder.add_panel("status", title="Status", width=120)

# Auto-width panel (shares remaining space)
recorder.add_panel("log", title="Activity Log")

# Update content (atomically — no tearing in the video)
recorder.update_panel("log", "Line 1\nLine 2\nLine 3")

# Scroll to keep a specific line visible
recorder.update_panel("log", long_text, focus_line=current_step)
```

## Report

The HTML report is a single self-contained file with:

- Embedded MP4 video players per scenario
- Clickable step timelines that seek the video
- Video playback highlights the current step
- Feature/scenario grouping with pass/fail badges
- Dark theme, responsive layout
- Customisable title, subtitle, and logo

## Documentation

- [HTTP Server API](docs/server.md) — full endpoint reference
- [CLI Reference](docs/cli.md) — all commands and flags
- [SDK Quick Start](docs/sdks.md) — all 5 languages
- [Integration Guide](docs/integration-guide.md) — framework-specific examples

## API

### `Recorder(output_dir, display, browser_size, framerate, font, font_bold)`

| Param | Default | Description |
|---|---|---|
| `output_dir` | `/tmp/recordings` | Where MP4 files are saved |
| `display` | `99` | X11 display number |
| `browser_size` | `1920x1080` | Virtual display resolution |
| `framerate` | `15` | Recording FPS |
| `font` | auto-detect | Path to regular TTF font |
| `font_bold` | auto-detect | Path to bold TTF font |

### Methods

| Method | Description |
|---|---|
| `start_display()` | Launch Xvfb |
| `stop_display()` | Terminate Xvfb |
| `add_panel(name, title, width)` | Register a panel |
| `remove_panel(name)` | Remove a panel |
| `update_panel(name, text, focus_line)` | Update panel content |
| `start_recording(filename)` | Start ffmpeg capture |
| `stop_recording()` | Stop capture, return MP4 path |
| `recording_elapsed` | Seconds since recording started |
| `cleanup()` | Stop everything, remove temp files |

### `generate_report(videos, output_dir, title, subtitle, logo_text)`

Takes a list of video metadata dicts and writes `report.html`.

## License

MIT
