Description

# syrupy <img align="right" width="100px" height="100px" src="https://user-images.githubusercontent.com/2528959/69500147-85d71400-0ec6-11ea-867a-277881278e57.png" alt="Logo"> [](#contributors) [](https://pypi.org/project/syrupy/) [](https://codecov.io/gh/syrupy-project/syrupy)  [](https://pypi.org/project/syrupy/) [](https://pypi.org/project/syrupy/)  [](https://pypi.org/project/syrupy/) [](./LICENSE) ## Overview Syrupy is a zero-dependency [pytest](https://docs.pytest.org/en/latest/) snapshot plugin. It enables developers to write tests which assert immutability of computed results. ## Motivation Syrupy upholds three principles: - 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 ```shell python -m pip install syrupy ``` ### Pytest and Python Compatibility Syrupy will always be compatible with the latest version of Python and Pytest. If you're running an old version of Python or Pytest, you will need to use an older major version of Syrupy: | Syrupy Version | Python Support | Pytest Support | | -------------- | -------------- | -------------- | | 5.x.x | >=3.10 | >=8 | | 4.x.x | >=3.8.1, | >=7, <9 | | 3.x.x | >=3.7, <4 | >=5.1, <8 | | 2.x.x | >=3.6, <4 | >=5.1, <8 | ## Usage ### Basic Usage In a pytest test file `test_file.py`: ```python 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: ```shell 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. #### Usage in `unittest.TestCase` subclasses [Due to limitations in `unittest` and `pytest`](https://docs.pytest.org/en/9.0.x/how-to/unittest.html#pytest-features-in-unittest-testcase-subclasses), the `snapshot` fixture is not directly usable in `TestCase` subclasses (including Django's `TestCase`). Possible workarounds include using marks: ```python from unittest import TestCase import pytest @pytest.fixture(scope="function") def snapshot_in_class(request, snapshot): """ Wraps snapshot fixture to provide instance snapshot property for unittest.TestCase tests """ request.cls.snapshot = snapshot class MyTest(TestCase): @pytest.mark.usefixtures("snapshot_in_class") def test_foo(self): actual = "Some computed value!" assert actual == self.snapshot ``` Or using a fixture with `autouse`: ```python from unittest import TestCase import pytest class MyTest(TestCase): @pytest.fixture(autouse=True) def setupSnapshot(self, snapshot): self.snapshot = snapshot def test_foo(self): actual = "Some computed value!" assert actual == self.snapshot ``` #### Custom Objects The default serializer supports all python built-in types and provides a sensible default for custom objects. #### Representation If you need to customise your object snapshot, it is as easy as overriding the default `__repr__` implementation. ```python def __repr__(self) -> str: return "MyCustomClass(...)" ``` If you need bypass a custom object representation to use the amber standard, it is easy using the following helpers. ```python def test_object_as_named_tuple(snapshot): assert snapshot == AmberDataSerializer.object_as_named_tuple(obj_with_custom_repr) ``` > See `test_snapshot_object_as_named_tuple_class` for an example on automatically doing this for all nested properties #### Attributes If you want to limit what properties are serialized at a class type level you could either: **A**. Provide a filter function to the snapshot [exclude](#exclude) configuration option. ```py def limit_foo_attrs(prop, path): allowed_foo_