syrupy 0.3.11

PyTest Snapshot Test Utility

syrupy

Overview

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

Motivation

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 test 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.

Installation

python -m pip install syrupy

Migration from snapshottest

You cannot use syrupy alongside snapshottest due to argument conflicts. To ease migration, we've made syrupy aware of snapshottest call syntax. Simply uninstall snapshottest and remove old snapshots:

pip uninstall snapshottest -y;
find . -type d ! -path '*/\.*' -name 'snapshots' | xargs rm -r

Usage

Basic Usage

In a pytest test file test_file.py:

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 test_file.py. The __snapshots__ directory and all its children should be committed along with your test code.

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, it is as easy as overriding the default __repr__ implementation.

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

Options

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

Option	Description	Default
--snapshot-update	Snapshots will be updated to match assertions and unused snapshots will be deleted.	False
--snapshot-warn-unused	Prints a warning on unused snapshots rather than fail the test suite.	False
--snapshot-default-extension	Use to change the default snapshot extension class.	syrupy.extensions.amber.AmberSnapshotExtension

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.
• SingleFileSnapshotExtension: Unlike the AmberSnapshotExtension, which groups all tests within a single test file into a singular snapshot file, this extension creates one .raw file per test case.
• PNGSnapshotExtension: An extension of single file, this should be used to produce .png files from a byte string.
• 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

• Custom snapshot directory
• Custom snapshot name
• Custom object snapshots
• JPEG image extension
• Built-in image extensions

Uninstalling

pip uninstall syrupy

If you have decided not to use Syrupy for your project after giving us a try, we'd love to get your feedback. Please create a GitHub issue if applicable, or drop a comment in our Slack channel.

Contributing

Feel free to open a PR or GitHub issue. Contributions welcome!

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

Contributors

Noah 🚇 🤔 💻 📖 ⚠️

Emmanuel Ogbizi 💻 🎨 🚇 📖 ⚠️

Adam Lazzarato 📖

Marc Cataford 💻 ⚠️

Michael Rose 💻 ⚠️

Jimmy Jia 💻 ⚠️

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

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

License

Syrupy is licensed under Apache License Version 2.0.