# Write Snapshot Tests for a Textual App

Yes. An agent adds pytest-textual-snapshot to a Textual app, writes snapshot tests on a fixture log file and unit tests for its parsers, and opens a PR with SVGs.

[Run this on Rush](https://cloud.getrush.ai/run/write-snapshot-tests/textual/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the app is built and started before deciding what a snapshot can capture. In a project like Textualize/toolong, `pyproject.toml` is a Poetry project on Python 3.8 or later with `textual` 0.58, `click` and `typing-extensions` as dependencies, `textual-dev` as the only dev dependency, and a `tl` script pointing at `toolong.cli:run`. There is no `tests/` directory, no pytest and no CI. `cli.py` is a Click command that takes file paths, a `--merge` flag and `--output-merge`, and constructs `UI(files, merge=..., save_merge=...)` from `ui.py`; when stdin is a pipe it spawns a child process instead, which no test should go near. `UI` is the `App`: it sorts the paths, builds a watcher, and on mount pushes a `LogScreen` whose `TabbedContent` holds one `LogView` per file and binds F1 to a `HelpScreen`. `LogView` in `log_view.py` binds tail toggling, a find dialog and a go-to-line action, and `format_parser.py` and `timestamps.py` hold the pure code: `CommonLogFormat`, `CombinedLogFormat`, `JSONLogFormat`, `FormatParser.parse`, `parse_timestamp` and `TimestampScanner`.

Snapshot tests come first because they cover the most with the least. The agent adds `pytest` and `pytest-textual-snapshot` to the dev group, writes `tests/fixtures/access.log` with a handful of Apache combined lines and `tests/fixtures/app.jsonl` with a few JSON lines, and writes `tests/test_snapshots.py` using the `snap_compare` fixture the plugin provides. Each test builds a non-running `UI([path])` and passes it with a fixed `terminal_size` so the SVG is the same on every machine: the viewer on the access log, the viewer on the JSONL file with its pretty-printed lines, the help screen after `press=["f1"]`, and the find dialog after its key, with a `run_before` that waits for the lines to load. Two files opened together produce the tabs snapshot, and `--merge` produces the merged view.

The parsers get ordinary unit tests in `tests/test_format_parser.py` and `tests/test_timestamps.py`: a combined log line parses to the expected fields and is highlighted by the right format, a JSON line round-trips, a line no format matches falls back to `DefaultLogFormat`, and `TimestampScanner.scan` finds an ISO 8601 and a syslog-style timestamp and returns `None` for a line without one. These need no terminal and run in milliseconds.

The agent runs `pytest` once with `--snapshot-update` to write the SVGs under `tests/__snapshots__/`, reads each one to confirm it shows what the test name says rather than an empty frame, then runs `pytest` again without the flag to prove the comparison passes. It adds `[tool.pytest.ini_options]` with `testpaths = ["tests"]` to `pyproject.toml`, refreshes `poetry.lock`, and opens the pull request with the snapshot images attached so a reviewer sees the screens without checking out the branch.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Write snapshot and unit tests for this Textual application. Read pyproject.toml, src/toolong/cli.py, ui.py, log_view.py, log_lines.py, format_parser.py, timestamps.py and help.py first. Add pytest and pytest-textual-snapshot to the Poetry dev group and a testpaths setting in pyproject.toml. Create tests/fixtures/access.log with a few Apache combined log lines and tests/fixtures/app.jsonl with a few JSON lines. In tests/test_snapshots.py use the snap_compare fixture with a fixed terminal_size on a non-running UI instance for: the viewer on the access log, the viewer on the JSONL file, the help screen after pressing f1, the find dialog after its key, two files as tabs, and two files merged, using run_before to wait for lines to load where needed. In tests/test_format_parser.py and tests/test_timestamps.py write unit tests for the combined, JSON and default formats and for TimestampScanner. Never test the stdin piping path in cli.py. Run pytest --snapshot-update once, inspect every SVG under tests/__snapshots__, run pytest again without the flag, refresh poetry.lock, and open a pull request that lists each test and attaches the snapshots.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that adds `tests/` with the three test modules, two fixture files and the SVG snapshots under `tests/__snapshots__/`, and changes `pyproject.toml` and `poetry.lock` for the two dev dependencies and the pytest settings. The description lists each snapshot with its image, names the parser cases the unit tests pin, and explains why the piping branch of `cli.py` is left untested.

The run's record keeps both pytest runs, the one that wrote the snapshots and the one that compared against them, and the agent's look at each SVG, so a reviewer can see that the screens captured are the viewer, the help and the dialog and not a blank terminal.

Before merging, a reviewer opens the SVGs in the pull request, checks that the fixture log lines look like their real logs, and decides whether to add a workflow that runs `pytest` on pull requests, which the repository lacks and the pull request offers as a follow-up.

## Run it on every pull request changing a screen or widget

Once snapshots exist they are only useful if they stay current. An automation on the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and the prompt "run pytest; if only snapshot tests fail, inspect the diff report, and if the change matches what the pull request describes, run pytest --snapshot-update and push the new SVGs to this branch" does that review. The trigger puts the pull request after the prompt; only pushes by an owner, member or collaborator fire it, never a fork's.

For several Textual apps, send one `POST /o/{org}/sessions` per repository from your own server with that repository in `resources` and a `request_id` that is a UUID v5 of its full name, so a retried call returns the run already started rather than a second set of snapshots.

## Why run it on Rush?

Snapshot tests for a terminal app depend on the terminal: a different width, a different font fallback or a shell theme changes the SVG and the test fails for nothing. The agent writes them with a fixed `terminal_size` on a clean sandbox, which is also what CI looks like, so the snapshots it commits are the ones that pass on a runner rather than ones that pass only on the author's machine.

The run keeps both pytest runs and the images, so the pull request can show the screens and the passing comparison rather than asking a reviewer to install Textual, generate the snapshots and look at them locally.

## Frequently asked questions

### Why snapshot tests instead of asserting on widget state?

A log viewer's job is what it shows, and a snapshot captures the rendered screen in one assertion: highlighting, layout, the footer, the tabs. Widget-state assertions are added where they are cheaper and more precise, which here is the parsers and the timestamp scanner.

### What happens when I change the UI on purpose?

The test fails and the plugin's report shows the old and new screens side by side. After checking that the difference is the intended one, run `pytest --snapshot-update` and commit the new SVGs; the pull request describes this so nobody updates blindly.

### Why does the agent fix the terminal size?

Without it the snapshot is taken at whatever size the running terminal reports, so the same test produces different SVGs on a laptop and in CI. Passing `terminal_size` to `snap_compare` makes the output deterministic.

### Why is the stdin piping path not tested?

When stdin is not a terminal, `cli.py` writes the input to a temporary file and spawns a second `tl` process attached to `/dev/tty`. That needs a real controlling terminal, which a test runner does not have, so the agent leaves it out and says so.

## More Textual jobs

- [Add Command Palette Commands to a Textual App](https://getrush.ai/run/add-command-palette/textual/)
- [Add a Config File to a Textual App](https://getrush.ai/run/add-config-file/textual/)
- [Add Dependabot to a Textual App](https://getrush.ai/run/add-dependabot/textual/)

## More jobs like this: Write the missing tests

- [Write Tests for Scrapy Spiders](https://getrush.ai/run/write-spider-tests/scrapy/)
- [Write Supertest Tests for an Express API](https://getrush.ai/run/write-supertest-tests/express/)
- [Write Supertest Tests for a Koa App](https://getrush.ai/run/write-supertest-tests/koa/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
