syrupy

library6.0.0pypypi✓ verified 25d ago

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.

testing

pip install syrupy

github ↗package ↗

INSTALL

IMPORT

SIG · SYRUPY

syrupy

testingpythonv6.0.0

Install

2.7s avg

Import

—

Disk

30MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v6.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 31.6MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.7s · import 0.000s · 32MB

30MB installed

● package 30MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

snapshot

✓ def test_example(snapshot): # snapshot is a pytest fixture provided by syrupy

✗ import syrupy.snapshot

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):`

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`

syrupy --version

Debug

Known issues

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

affects: 5.0.0 and later

breakingThe 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`.

affects: 4.0.0 and later

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

affects: All versions

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

affects: All versions

Errors

Common errors & fixes

_pytest.fixtures.FixtureLookupError: Unknown name 'snapshot' for fixture

The Syrupy plugin is not installed or not correctly recognized by pytest in your environment.

fix

Install Syrupy using pip: `pip install syrupy`

ModuleNotFoundError: No module named 'syrupy'

The `syrupy` package has not been installed in your current Python environment.

fix

Install the library using pip: `pip install syrupy`

TypeError: Object of type datetime is not JSON serializable

The default JSON snapshot extension does not know how to serialize certain Python types like `datetime` objects.

fix

Use a different snapshot extension, such as `syrupy.extensions.amber.AmberExtension`, or extend `syrupy.extensions.json.JSONExtension` with a custom serializer for the problematic type (e.g., `datetime.isoformat()`).

Upgrade

Version history

6.0.0latest on PyPI · released Aug 22, 2026

Audit

Dependencies

pytestrequiredSyrupy is a pytest plugin and requires pytest to function.

richoptionalOptional for enhanced diff output in the console.

Agent activity

13 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/syrupy-project/syrupy ↗

packagehttps://pypi.org/project/syrupy/ ↗