Open-Source Testing · syrupy-project

syrupy

Syrupy is a lightweight pytest plugin for snapshot testing that lets developers assert immutability of computed results using simple assertions like `assert actual == snapshot`. It integrates directly into pytest with zero dependencies and supports custom object serialization.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/syrupy-project/syrupy

869

GitHub stars

Forks

Python

Primary language

MIT

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	syrupy-project/syrupy
Owner	syrupy-project
Primary language	Python
License	MIT — OSI-approved
Stars	869
Forks	58
Open issues	18
Latest release	v5.5.2 (2026-07-08)
Last updated	2026-07-08
Source	https://github.com/syrupy-project/syrupy

What syrupy is

Syrupy provides a pytest fixture-based snapshot testing framework with an idiomatic API, built-in Amber serialization format, and extensible serializers for custom data types. It enforces soundness by failing on missing snapshots, not just differences, and requires pytest >=8 and Python >=3.10 for current releases.

Quickstart

Get the syrupy source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/syrupy-project/syrupy.git2cd syrupy3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

Regression Testing Complex Computations

Capture output of data transformations, report generation, or complex business logic to detect unintended changes. Snapshots are committed to version control, making it easy to review behavioral changes in code review.

API Response Validation

Assert that API responses remain structurally and content-wise consistent across refactors. Useful for microservices and integration tests where response shape stability matters.

UI and Serialization Testing

Validate output of template rendering, JSON serialization, or formatted string generation without brittle string comparisons. Custom `__repr__` overrides allow precise control over what gets captured.

Implementation considerations

Snapshot files are stored in `__snapshots__/` directories adjacent to test files; these must be committed to version control for reproducibility.
Custom objects require either a sensible `__repr__` or use of serializer helpers like `AmberDataSerializer.object_as_named_tuple()` for reliable snapshots.
Use `exclude` and `include` filter functions or `__dir__` overrides to control which object attributes are serialized and reduce false positives.
CLI flags like `--snapshot-update-new-only` and `--snapshot-warn-unused` allow fine-grained control over snapshot lifecycle in CI/CD.
Snapshot diffs support multiple modes; PyCharm integration available via `--snapshot-patch-pycharm-diff` for better IDE visualization.

When to avoid it — and what to weigh

Non-Deterministic Output — Snapshot testing works best with deterministic results. If your code produces timestamps, UUIDs, or random data, you will need custom filters or exclusion logic, adding complexity.
Frequently Changing Expected Outputs — Snapshot tests require intentional updates with `--snapshot-update`. If specifications change frequently, manual snapshot maintenance becomes tedious and error-prone.
Very Large or Binary Data — Snapshots are stored as text (Amber format by default). Very large objects or binary data may be inefficient to serialize and difficult to review in diffs.
Tests Using Old pytest or Python — Current Syrupy v5.x requires pytest >=8 and Python >=3.10. Older environments must pin to Syrupy 4.x or earlier, which have limited support.

License & commercial use

Licensed under MIT (MIT License), a permissive OSI-approved license allowing unrestricted use, modification, and distribution with no copyleft obligations.

MIT license explicitly permits commercial use. No restrictions on using Syrupy in proprietary or commercial projects. No commercial support entity mentioned in provided data; contributions and community-driven.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Strong
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Strong
Assessment confidence	High

Security considerations

Snapshot files are committed to version control and human-readable; review for accidental secrets or sensitive data in serialized objects. No cryptographic or privileged operations. Standard Python deserialization risks apply if loading snapshots from untrusted sources (unlikely in practice).

Alternatives to consider

pytest-snapshot

Older snapshot plugin with similar API; less actively maintained and less tightly integrated with modern pytest. Syrupy has more extensible serialization.

SnapshotTest (Jest-like)

Language-specific to JavaScript/Node.js; Python alternatives like Syrupy offer native idiomatic integration without cross-language friction.

Manual golden-file comparison

Hand-maintained reference files offer full control but lack automation, diff visualization, and update tooling. Syrupy reduces boilerplate and maintenance burden.

Software development agency

Build on syrupy with DEV.co software developers

Install Syrupy via pip and start capturing test snapshots with simple assertions. Review our implementation guide to integrate with your CI/CD and code review workflows.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

inline-snapshot pytest-sugar pytest

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Testing Application Development API Development Custom Software Talk to DEV.co

syrupy FAQ

Do I need to commit snapshot files to version control?

Yes. Snapshots in `__snapshots__/` directories should be committed alongside test code. They serve as the source of truth for expected outputs and enable code review of behavioral changes.

Can I use Syrupy with Django TestCase or unittest?

Partially. Direct fixture injection in TestCase subclasses is limited by pytest/unittest constraints. README provides workarounds using `@pytest.mark.usefixtures` or class-level fixtures to inject the snapshot fixture as an instance attribute.

How do I handle dynamic or non-deterministic data in snapshots?

Use `exclude` or `include` filter functions to selectively remove timestamps, UUIDs, and other volatile fields before serialization. Alternatively, mock or patch non-deterministic sources in tests.

What Python and pytest versions does Syrupy support?

v5.x requires Python >=3.10 and pytest >=8. Older versions (4.x, 3.x, 2.x) support older Python and pytest; choose the version matching your environment from the compatibility table in the README.

Work with a software development agency

DEV.co is a software development agency delivering custom software development services to companies building on open source. Our software developers and web developers design, integrate, and ship production systems — spanning web development, APIs, AI, data, and cloud. If syrupy is part of your open-source testing roadmap, our team can implement, customize, migrate, and maintain it.

Ready to add robust snapshot testing to your pytest suite?

Install Syrupy via pip and start capturing test snapshots with simple assertions. Review our implementation guide to integrate with your CI/CD and code review workflows.

Talk to DEV.co Schedule a Consultation