AgentSkillsCN

textual-snapshot-testing

借助 pytest-textual-snapshot，为 Textual TUI 应用实施视觉回归测试。自动截取 SVG 截图，并在不同测试运行之间进行对比，及时发现视觉上的回归问题。适用于测试界面外观、检测布局回归、跨终端尺寸验证响应式设计、检验 CSS 样式效果，或为视觉测试搭建 CI/CD 流水线。涵盖 snap_compare fixture、run_before 回调、快照管理、对易失性测试（如动画、光标、时间戳）的处理，以及与 CI 系统的深度集成。

SKILL.md
--- frontmatter
name: textual-snapshot-testing
description: |
  Visual regression testing for Textual TUI applications using pytest-textual-snapshot.
  Captures SVG screenshots and compares across test runs to detect visual regressions.
  Use when: testing visual appearance, detecting layout regressions, testing responsive
  designs across terminal sizes, verifying CSS styling effects, or setting up CI/CD
  for visual testing. Covers snap_compare fixture, run_before callbacks, snapshot
  management, flaky test handling (animations, cursors, timestamps), and CI integration.

Textual Snapshot Testing

Visual regression testing using pytest-textual-snapshot to capture and compare SVG screenshots.

Quick Reference

python
# Basic snapshot test
def test_app_visual(snap_compare):
    assert snap_compare(MyApp())

# With user interaction
def test_after_input(snap_compare):
    assert snap_compare(MyApp(), press=["tab", "enter"])

# With custom terminal size
def test_responsive(snap_compare):
    assert snap_compare(MyApp(), terminal_size=(120, 40))

# With pre-snapshot setup
def test_stable(snap_compare):
    async def run_before(pilot):
        pilot.app.query_one(Input).cursor_blink = False
    assert snap_compare(MyApp(), run_before=run_before)

Setup

bash
pip install pytest-textual-snapshot

The snap_compare fixture is automatically available after installation.

snap_compare API

python
def snap_compare(
    app: App | str | Path,           # App instance or path to app file
    *,
    press: list[str] | None = None,  # Keys to press before snapshot
    terminal_size: tuple[int, int] = (80, 24),  # Terminal dimensions
    run_before: Callable[[Pilot], Awaitable[None]] | None = None,  # Async setup
) -> bool

Workflow

  1. •First run: Snapshot generated, test fails (by design)
  2. •Review: Check HTML report, validate visual output
  3. •Approve: Run pytest --snapshot-update to save baseline
  4. •Subsequent runs: Compare against baseline, fail on differences
  5. •Regression: Visual diff shown in HTML report

Key Patterns

Disable Animations (Prevents Flaky Tests)

python
def test_stable_snapshot(snap_compare):
    async def run_before(pilot):
        for widget in pilot.app.query("*"):
            widget.can_animate = False
    assert snap_compare(MyApp(), run_before=run_before)

Disable Cursor Blink

python
def test_input_snapshot(snap_compare):
    async def run_before(pilot):
        pilot.app.query_one(Input).cursor_blink = False
    assert snap_compare(MyApp(), run_before=run_before)

Wait for Workers Before Snapshot

python
def test_data_loaded(snap_compare):
    async def run_before(pilot):
        await pilot.press("r")  # Trigger load
        await pilot.app.workers.wait_for_complete()
    assert snap_compare(DataApp(), run_before=run_before)

Mock Time (Stable Timestamps)

python
from unittest.mock import patch
from datetime import datetime

def test_timestamp(snap_compare):
    with patch("myapp.datetime") as mock_dt:
        mock_dt.now.return_value = datetime(2025, 1, 1, 12, 0, 0)
        assert snap_compare(TimestampApp())

Complex Interaction Sequence

python
def test_command_palette(snap_compare):
    async def run_before(pilot):
        await pilot.press("ctrl+p")
        await pilot.pause()
        await pilot.press(*"search term")
        await pilot.pause()
        pilot.app.query_one(Input).cursor_blink = False
    assert snap_compare(MyApp(), run_before=run_before)

Snapshot Management

Update Snapshots

bash
# Update all snapshots
pytest --snapshot-update

# Update specific test
pytest tests/test_app.py::test_specific --snapshot-update

Snapshot Storage

code
tests/
├── test_app.py
└── __snapshots__/
    └── test_app/
        └── test_my_feature.svg

Important: Commit __snapshots__/ to version control.

View Failure Reports

When tests fail, pytest generates HTML report with visual diff:

  • •Left: Current rendering
  • •Right: Historical baseline
  • •Toggle: Overlay mode for subtle differences

CI/CD Integration

GitHub Actions

yaml
- name: Run snapshot tests
  run: pytest tests/snapshot -v

- name: Upload report on failure
  if: failure()
  uses: actions/upload-artifact@v4
  with:
    name: snapshot-report
    path: snapshot_report.html

Manual Snapshot Update Workflow

yaml
# .github/workflows/update-snapshots.yml
name: Update Snapshots
on: workflow_dispatch

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pytest tests/snapshot --snapshot-update
      - run: |
          git add tests/__snapshots__/
          git commit -m "Update snapshot baselines"
          git push

Editor Integration

Open failed snapshots in your editor:

bash
# VS Code
export TEXTUAL_SNAPSHOT_FILE_OPEN_PREFIX="code://file/"

# Cursor
export TEXTUAL_SNAPSHOT_FILE_OPEN_PREFIX="cursor://file/"

# PyCharm
export TEXTUAL_SNAPSHOT_FILE_OPEN_PREFIX="pycharm://"

Common Pitfalls

ProblemSolution
Flaky: Animation frame variesDisable animations in run_before
Flaky: Cursor blink state variesSet cursor_blink = False
Flaky: Timestamps changeMock datetime.now()
Snapshots not in VCSAdd __snapshots__/ to git
Different results in CIUse explicit terminal_size

See Also