Syrupy

5.1.0 · active · verified Thu Apr 09

Syrupy is a pytest plugin for snapshot testing, enabling developers to capture the current output of a value and compare it against a previously stored snapshot. It's currently on version 5.1.0 and maintains an active release cadence, typically releasing minor/patch versions every 1-3 months.

Warnings

breaking Version 5.0.0 introduced significant breaking changes, including API changes for `SnapshotAssertion`, removal of `assert_match`, and a license change from MIT to Apache 2.0. The `pygments` dependency was also removed.
Fix: Review the official v5.0.0 release notes thoroughly. Update usage of `SnapshotAssertion` directly (e.g., `assert value == snapshot` instead of `snapshot.assert_match(value)`). Re-evaluate custom serializers and extensions.
breaking The project was renamed from `pytest-syrupy` to `syrupy` in version 4.0.0. Users upgrading from older installations (pre-4.0.0) will need to update their `pip install` commands and potentially package references.
Fix: Ensure your `requirements.txt` or `pyproject.toml` specifies `syrupy` instead of `pytest-syrupy`. Uninstall `pytest-syrupy` and install `syrupy`.
gotcha Snapshots will fail if the asserted value changes. To update snapshots to reflect new expected output, you must explicitly run pytest with the `--snapshot-update` flag or set the `SYRUPY_UPDATE_SNAPSHOTS` environment variable.
Fix: Run your tests with `pytest --snapshot-update` or `SYRUPY_UPDATE_SNAPSHOTS=1 pytest`. Be mindful of reviewing changes before committing updated snapshots.
gotcha Snapshot files are stored in `__snapshots__` directories by default, relative to the test file. Changing the default behavior (e.g., storing snapshots in a different directory) requires using the `--snapshot-dirname` option or a custom `PathResolver`.
Fix: Use the `pytest --snapshot-dirname my_custom_dir` command-line option, or configure a custom `PathResolver` if you need more complex logic. As of v5.0.0, `--snapshot-dirname` is available.

Install

pip install syrupy Install Syrupy

Imports

snapshot
```
def test_example(snapshot):
    # snapshot is a pytest fixture provided by syrupy
```
The 'snapshot' object is a pytest fixture, not a direct Python module import for basic usage. For type hinting, you might import `SnapshotAssertion`.
SnapshotAssertion
```
from syrupy.assertion import SnapshotAssertion
```
Useful for type hinting the 'snapshot' fixture in your tests, e.g., `def test_example(snapshot: SnapshotAssertion):`

Quickstart

This quickstart demonstrates a basic snapshot test using the `snapshot` pytest fixture. The first run creates a snapshot file, and subsequent runs verify the data against it. The `--snapshot-update` flag is crucial for updating snapshots when expected data changes.

import pytest

def test_data_snapshot(snapshot):
    data = {
        "id": 123,
        "name": "Example Item",
        "details": [
            {"key": "value1", "status": "active"},
            {"key": "value2", "status": "inactive"}
        ]
    }
    assert data == snapshot

# To run this test:
# 1. Save as `test_snapshot.py`
# 2. Run `pytest` in your terminal
# 3. On the first run, a snapshot file will be created (e.g., `__snapshots__/test_snapshot.ambr`).
# 4. On subsequent runs, it will compare against the snapshot.
# 5. To update snapshots, run `pytest --snapshot-update`

view raw JSON →