Skip to main content

PyTest Snapshot Test Utility

Project description



All Contributors Maturity badge - level 2 Stage Slack workspace

Pypi Wheel PyPI - Python Version PyPI - Downloads PyPI - License

Build Status codecov


Syrupy is a pytest snapshot plugin. It enables developers to write tests which assert immutability of computed results.


The most popular snapshot test plugin compatible with pytest has some core limitations which this package attempts to address by upholding some key values:

  • Extensible: If a particular data type is not supported, users should be able to easily and quickly add support.
  • Idiomatic: Snapshot testing should fit naturally among other tests cases in pytest, e.g. assert x == snapshot vs. snapshot.assert_match(x).
  • Soundness: Snapshot tests should uncover even the most minute issues. Unlike other snapshot libraries, Syrupy will fail a test suite if a snapshot does not exist, not just on snapshot differences.


python -m pip install syrupy


Syrupy is a drop in replacement for snapshottest. If you already have snapshot tests written, it is as easy as:

pip uninstall snapshottest

This is neccessary to prevent argument conflicts.

there can only be one


Basic Usage

In a pytest test file

def test_foo(snapshot):
    actual = "Some computed value!"
    assert actual == snapshot

when you run pytest, the above test should fail due to a missing snapshot. Re-run pytest with the update snapshots flag like so:

pytest --snapshot-update

A snapshot file should be generated under a __snapshots__ directory in the same directory as The __snapshots__ directory and all its children should be committed along with your test code.

Usage Demo

Custom Objects

The default serializer supports all python built-in types and provides a sensible default for custom objects.

If you need to customise your object snapshot, is as easy as overriding the default __repr__ implementation.

def __repr__(self) -> str:
  return "MyCustomClass(...)"


These are the cli options exposed to pytest by the plugin.

Option Description
--snapshot-update When supplied updates existing snapshots of any run tests, as well as deleting unused and generating new snapshots.
--snapshot-warn-unused Syrupy default behaviour is to fail the test session when there any unused snapshots. This instructs the plugin not to fail.

Built-In Extensions

Syrupy comes with a few built-in preset configurations for you to choose from. You should also feel free to extend the AbstractSyrupyExtension if your project has a need not captured by one our built-ins.

  • AmberSnapshotExtension: This is the default extension which generates .ambr files. Serialization of most data types are supported, however non-sortable types such as frozenset are experimental.
  • SingleFileSnapshotExtension: Unlike the AmberSnapshotExtension, which groups all tests within a single test file into a singular snapshot file, and creates one .raw file per test case.
  • PNGSnapshotExtension: An extension of single file, this should be used to produce .png files.
  • SVGSnapshotExtension: Another extension of single file. This produces .svg files from an svg string.

Advanced Usage

By overriding the provided AbstractSnapshotExtension you can implement varied custom behaviours.

See examples of how syrupy can be used and extended in the test examples.

Extending Syrupy


pip uninstall syrupy


Feel free to open a PR. This project is still in a very early stage, and we're still figuring out what direction we want to move towards.

To develop locally, clone this repository and run . script/bootstrap to install test dependencies. You can then use invoke --list to see available commands.

See contributing guide



🚇 🤔 💻 📖 ⚠️

Emmanuel Ogbizi

💻 🎨 🚇 📖 ⚠️

Adam Lazzarato


This section is automatically generated via tagging the all-contributors bot in a PR:

@all-contributors please add <username> for <contribution type>


Syrupy is licensed under Apache License Version 2.0.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for syrupy, version 0.3.1
Filename, size File type Python version Upload date Hashes
Filename, size syrupy-0.3.1-py3-none-any.whl (23.5 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size syrupy-0.3.1.tar.gz (1.3 MB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page