Repository files navigation

A pytest plugin for snapshot testing Textual applications.

Install usingpip:

pip install pytest-textual-snapshot

After installing, thesnap_compare fixture will automatically be made available.

Apytest-textual-snapshot test saves an SVG screenshot of a running Textual app to disk.The next time the test runs, it takes another screenshot and compares it to the saved one.If the new screenshot differs from the old one, the test fails.This is a convenient way to quickly and automatically detect visual regressions in your applications.

You can run your tests usingpytest as normal. You can usepytest-xdist to run your tests in parallel.

If your snapshot test fails, it means that the screenshot taken during the test sessiondiffers from the last screenshot taken.This change is shown in the failure report, which you'll be given a linked to in the event of a failure.

If the diff shown in the failure report looks correct, you can update the snapshot on diskby runningpytest with the--snapshot-update flag.

Inject thesnap_compare fixture into your test and callit with an app instance or the path to the Textual app (the file containing theApp subclass).

deftest_my_app(snap_compare):app=MyTextualApp()# a *non-running* Textual `App` instanceassertsnap_compare(app)

deftest_something(snap_compare):assertsnap_compare("path/to/app.py")

Key presses can be simulated before the screenshot is taken.

deftest_something(snap_compare):assertsnap_compare("path/to/app.py",press=["tab","left","a"])

You can run some code before capturing a screenshot using therun_before parameter.

deftest_something(snap_compare):asyncdefrun_before(pilot:Pilot):awaitpilot.press("ctrl+p")# You can run arbitrary code before the screenshot occurs:awaitdisable_blink_for_active_cursors(pilot)awaitpilot.press(*"view")assertsnap_compare(MyApp(),run_before=run_before)

If you need to change the size of the terminal (for example to fit in more content or test layout-related code), you can adjust theterminal_size parameter.

deftest_another_thing(snap_compare):assertsnap_compare(MyApp(),terminal_size=(80,34))

If you passed a path tosnap_compare, you can quickly open the path in your editor by setting theTEXTUAL_SNAPSHOT_FILE_OPEN_PREFIX environment variable based on the editor you want to use. Clicking on the path in the snapshot report will open the path in your editor.

• file:// - default, most likely opening in your browser
• code://file/ - opens the path in VS Code
• cursor://file/ - opens the path in Cursor
• pycharm:// - opens the path in PyCharm