pytest-textual-snapshot

1.1.0 verified Mon Apr 27 auth: no python

Snapshot testing plugin for pytest that enables visual regression testing of Textual terminal applications. Version 1.1.0 requires Python >=3.8.1, <4.0.0. Regular releases.

pip install pytest-textual-snapshot

Common errors

error ModuleNotFoundError: No module named 'pytest_textual_snapshot' ↓

cause The package is not installed or incorrectly imported.

fix

Install the package: pip install pytest-textual-snapshot; then import as from pytest_textual_snapshot import snapshot_app.

error TypeError: snapshot_app() missing 1 required positional argument: 'app' ↓

cause Calling snapshot_app without passing the Textual app instance.

fix

Ensure you pass your app instance: snapshot_app(app).

error AttributeError: 'App' object has no attribute 'run_test' ↓

cause Using an older version of Textual that does not have run_test method or not using an async context.

fix

Upgrade Textual: pip install -U textual and ensure the test is async: async with app.run_test() as pilot:.

Warnings

gotcha The snapshot_app fixture must be used within an async context (e.g., app.run_test()) otherwise it will fail. ↓

fix Ensure the test is async and uses `async with app.run_test() as pilot:` before calling snapshot_app.

gotcha Snapshots are stored as SVG files in a `__snapshots__` directory. If the test environment differs (e.g., different terminal width), snapshots may mismatch. ↓

fix Set fixed terminal dimensions in your test using `app.run_test(size=(80, 24))` to ensure reproducibility.

Imports

snapshot_app

wrong

from textual.testing import snapshot_app

correct

from pytest_textual_snapshot import snapshot_app

snapshot_app is provided by the plugin, not by textual itself

Quickstart

Minimal test using the snapshot_app fixture to capture a Textual app's render.

import pytest
from textual.app import App, ComposeResult
from textual.widgets import Static
from pytest_textual_snapshot import snapshot_app

class SimpleApp(App):
    def compose(self) -> ComposeResult:
        yield Static("Hello, World!")

def test_snapshot(snapshot_app):
    app = SimpleApp()
    async with app.run_test() as pilot:
        # Use snapshot_app fixture to capture the app's render
        snapshot_app(app)