# 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
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
```shell
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:
```shell
pip uninstall snapshottest -y;
find . -type d ! -path '*/\.*' -name 'snapshots' | xargs rm -r
```
### 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 |
| -------------- | -------------- | -------------- |
| 4.x.x | >3.8.1 | >=7 |
| 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.
#### 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_attrs = {"do", "not", "serialize", "these", "attrs"}
return isinstance(path[-1][1], Foo) and prop in allowed_foo_attrs
def test_bar(snapshot):
actual = Foo(...)
assert actual == snapshot(exclude=limit_foo_attrs)
```
**B**. Provide a filter function to the snapshot [include](#include) configuration option.
```py
def limit_foo_attrs(prop, path):
allowed_foo_attrs = {"only", "serialize", "these", "attrs"}
return isinstance(path[-1][1], Foo) and prop in allowed_foo_attrs
def test_bar(snapshot):
actual = Foo(...)
assert actual == snapshot(include=limit_foo_attrs)
```
**C**. Or override the `__dir__` implementation to control the attribute list.
```py
class Foo:
def __dir__(self):
return ["only", "serialize", "these", "attrs"]
def test_bar(snapshot):
actual = Foo(...)
assert actual == snapshot
```
Both options will generate equivalent snapshots but the latter is only viable when you have control over the class implementation and do not need to share the exclusion logic with other objects.
### CLI 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-details` | Includes details of unused snapshots (test name and snapshot location) in the final report. | `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. | [AmberSnapshotExtension](https://github.com/syrupy-project/syrupy/blob/main/src/syrupy/extensions/amber/__init__.py) |
| `--snapshot-no-colors` | Disable test results output highlighting. Equivalent to setting the environment variables `ANSI_COLORS_DISABLED` or `NO_COLOR` | Disabled by default if not in terminal. |
| `--snapshot-patch-pycharm-diff`| Override PyCharm's default diffs viewer when looking at snapshot diffs. See [IDE Integrations](#ide-integrations) | `False` |
| `--snapshot-diff-mode` | Configures how diffs are displayed on assertion failure. If working with very large snapshots, disabling the diff can improve performance. | `detailed` |
### Assertion Options
These are the options available on the `snapshot` assertion fixture.
Use of these options are one shot and do not persist across assertions.
For more persistent options see [advanced usage](#advanced-usage).
#### `matcher`
This allows you to match on a property path and value to control how specific object shapes are serialized.
The matcher is a function that takes two keyword arguments.
It should return the replacement value to be serialized or the original unmutated value.
| Argument | Description |
| -------- | ------------------------------------------------------------------------------------------------------------------ |
| `data` | Current serializable value being matched on |
| `path` | Ordered path traversed to the current value e.g. `(("a", dict), ("b", dict))` from `{ "a": { "b": { "c": 1 } } }`} |
**NOTE:** Do not mutate the value received as it could cause unintended side effects.
##### Built-In Matchers
Syrupy comes with built-in helpers that can be used to make easy work of using property matchers.
###### `path_type(mapping=None, *, types=(), strict=True, regex=False)`
Easy way to build a matcher that uses the path and value type to replace serialized data.
When strict, this will raise a `ValueError` if the types specified are not matched.
| Argument | Description |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `mapping` | Dict of path string to tuples of class types, including primitives e.g. (MyClass, UUID, datetime, int, str) |
| `types` | Tuple of class types used if none of the path strings from the mapping are matched |
| `strict` | If a path is matched but the value at the path does not match one of the class types in the tuple then a `PathTypeError` is raised |
| `regex` | If true, the `mapping` key is treated as a regular expression when matching paths |
| `replacer` | Called with any matched value and result is used as the replacement that is serialized. Defaults to the object type when not given |
```py
from syrupy.matchers import path_type
def test_bar(snapshot):
actual = {
"date_created": datetime.now(),
"value": "Some computed value!!",
}
assert actual == snapshot(matcher=path_type({
"date_created": (datetime,),
"nested.path.id": (int,),
}))
```
```py
# name: test_bar
dict({
'date_created': datetime,
'value': 'Some computed value!!',
})
# ---
```
> NOTE: When `regex` is `True` all matcher mappings are treated as regex patterns
###### `path_value(mapping=None, *, **kwargs)`
Shares the same `kwargs` as `path_type` matcher, with the exception of the `mapping` argument type.
Only runs replacement for objects at a matching path where the value of the mapping also matches the object data string repr.
| Argument | Description |
| --------- | ---------------------------------------------------------- |
| `mapping` | Dict of path string to object value string representations |
> See `test_regex_matcher_str_value` for example usage.
#### `exclude`
This allows you to filter out object properties from the serialized snapshot.
The exclude parameter takes a filter function that accepts two keyword arguments.
It should return `true` if the property should be excluded, or `false` if the property should be included.
| Argument | Description |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `prop` | Current property on the object, could be any hashable value that can be used to retrieve a value e.g. `1`, `"prop_str"`, `SomeHashableObject` |
| `path` | Ordered path traversed to the current value e.g. `(("a", dict), ("b", dict))` from `{ "a": { "b": { "c": 1 } } }`} |
##### Built-In Filters
Syrupy comes with built-in helpers that can be used to make easy work of using the filter options.
###### `props(prop_name, *prop_name)`
Easy way to build a filter that excludes based on string based property names.
Takes an argument list of property names, with support for indexed iterables.
```py
from syrupy.filters import props
def test_bar(snapshot):
actual = {
"id": uuid.uuid4(),
"list": [1,2,3],
}
assert actual == snapshot(exclude=props("id", "1"))
```
```py
# name: test_bar
dict({
'list': list([
1,
3,
]),
})
# ---
```
###### `paths(path_string, *path_strings)`
Easy way to build a filter that uses full path strings delimited with `.`.
Takes an argument list of path strings.
```py
from syrupy.filters import paths
def test_bar(snapshot):
actual = {
"date": datetime.now(),
"list": [1,2,3],
}
assert actual == snapshot(exclude=paths("date", "list.1"))
```
```py
# name: test_bar
dict({
'list': list([
1,
3,
]),
})
# ---
```
#### `include`
This allows you filter an object's properties to a subset using a predicate. This is the opposite of [exclude](#exclude). All the same property filters supporterd by [exclude](#exclude) are supported for `include`.
The include parameter takes a filter function that accepts two keyword arguments.
It should return `true` if the property should be include, or `false` if the property should not be included.
| Argument | Description |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `prop` | Current property on the object, could be any hashable value that can be used to retrieve a value e.g. `1`, `"prop_str"`, `SomeHashableObject` |
| `path` | Ordered path traversed to the current value e.g. `(("a", dict), ("b", dict))` from `{ "a": { "b": { "c": 1 } } }`}
Note that `include` has some caveats which make it a bit more difficult to use than `exclude`. Both `include` and `exclude` are evaluated for each key of an object before traversing down nested paths. This means if you want to include a nested path, you must include all parents of the nested path, otherwise the nested child will never be reached to be evaluated against the include predicate. For example:
```py
obj = {
"nested": { "key": True }
}
assert obj == snapshot(include=paths("nested", "nested.key"))
```
The extra "nested" is required, otherwise the nested dictionary will never be searched -- it'd get pruned too early.
To avoid adding duplicate path parts, we provide a convenient `paths_include` which supports a list/tuple instead of a string for each path to match:
```py
obj = {
"other": False,
"nested": { "key": True }
}
assert obj == snapshot(include=paths_include(["other"], ["nested", "key"]))
```
#### `extension_class`
This is a way to modify how the snapshot matches and serializes your data in a single assertion.
```py
def test_foo(snapshot):
actual_svg = "<svg></svg>"
assert actual_svg == snapshot(extension_class=SVGImageSnapshotExtension)
```
#### `diff`
This is an option to snapshot only the diff between the actual object and a previous snapshot, with the `diff` argument being the previous snapshot `index`/`name`.
```py
def test_diff(snapshot):
actual0 = [1,2,3,4]
actual1 = [0,1,3,4]
assert actual0 == snapshot
assert actual1 == snapshot(diff=0)
# This is equivalent to the lines above
# Must use the index name to diff when given
assert actual0 == snapshot(name='snap_name')
assert actual1 == snapshot(diff='snap_name')
```
##### 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.
- Line control characters are normalised when snapshots are generated i.e. `\r` and `\n` characters are all written as `\n`. This is to allow interoperability of snapshots between operating systems that use disparate line control characters.
- **`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.
- **`PNGImageSnapshotExtension`**: An extension of single file, this should be used to produce `.png` files from a byte string.
- **`SVGImageSnapshotExtension`**: Another extension of single file. This produces `.svg` files from an svg string.
- **`JSONSnapshotExtension`**: Another extension of single file. This produces `.json` files from dictionaries and lists.
#### `name`
By default, if you make multiple snapshot assertions within a single test case, an auto-increment identifier will be used to index the snapshots. You can override this behaviour by specifying a custom snapshot name to use in place of the auto-increment number.
```py
def test_case(snapshot):
assert "actual" == snapshot(name="case_a")
assert "other" == snapshot(name="case_b")
```
> _Warning_: If you use a custom name, you must make sure the name is not re-used within a test case.
### Advanced Usage
By overriding the provided [`AbstractSyrupyExtension`](https://github.com/syrupy-project/syrupy/tree/main/src/syrupy/extensions/base.py) you can implement varied custom behaviours.
See examples of how syrupy can be used and extended in the [test examples](https://github.com/syrupy-project/syrupy/tree/main/tests/examples).
#### Overriding defaults
It is possible to override `include`, `exclude`, `matchers` and `extension_class` on a more global level just once,
instead of every time per test. By default, after every assertion the modified values per snapshot assert are reverted
to their default values. However, it is possible to override those default values with ones you would like persisted,
which will be treated as the new defaults.
To achieve that you can use `snapshot.with_defaults`, which will create new instance of `SnapshotAssertion` with the provided values.
`snapshot.use_extension` is retained for compatibility. However, it is limited to only overriding the default extension class.
#### JSONSnapshotExtension
This extension can be useful when testing API responses, or when you have to deal with long dictionaries that are cumbersome to validate inside a test. For example:
```python
import pytest
from syrupy.extensions.json import JSONSnapshotExtension
@pytest.fixture
def snapshot_json(snapshot):
return snapshot.with_defaults(extension_class=JSONSnapshotExtension)
# or return snapshot.use_extension(JSONSnapshotExtension)
def test_api_call(client, snapshot_json):
resp = client.post("/endpoint")
assert resp.status_code == 200
assert snapshot_json == resp.json()
```
API responses often contain dynamic data, like IDs or dates. You can still validate and store other data of a response by leveraging syrupy matchers. For example:
```py
from datetime import datetime
from syrupy.matchers import path_type
def test_api_call(client, snapshot_json):
resp = client.post("/user", json={"name": "Jane"})
assert resp.status_code == 201
matcher = path_type({
"id": (int,),
"registeredAt": (datetime,)
})
assert snapshot_json(matcher=matcher) == resp.json()
```
The generated snapshot:
```json
{
"id": "<class 'int'>",
"registeredAt": "<class 'datetime'>",
"name": "Jane"
}
```
Or a case where the value needs to be replaced using a condition e.g. file path string
```py
import re
from syrupy.matchers import path_type
def test_matches_generated_string_value(snapshot, tmp_file):
matcher = path_value(
mapping={"file_path": r"\w+://(.*/)+dir/filename.txt"},
replacer=lambda _, match: match[0].replace(match[1], "<tmp-file-path>/"),
types=(str,),
)
assert snapshot(matcher=matcher) == tmp_file
```
The generated snapshot:
```json
{
"name": "Temp Files",
"file_path": "scheme://<tmp-file-path>/dir/filename.txt"
}
```
### Extending Syrupy
- [Custom defaults](https://github.com/syrupy-project/syrupy/tree/main/tests/examples/test_custom_defaults.py)
- [Custom snapshot directory 1](https://github.com/syrupy-project/syrupy/tree/main/tests/examples/test_custom_snapshot_directory.py)
- [Custom snapshot directory 2](https://github.com/syrupy-project/syrupy/tree/main/tests/examples/test_custom_snapshot_directory_2.py)
- [Custom snapshot name](https://github.com/syrupy-project/syrupy/tree/main/tests/examples/test_custom_snapshot_name.py)
- [Custom object snapshots](https://github.com/syrupy-project/syrupy/tree/main/tests/examples/test_custom_object_repr.py)
- [Custom comparator](https://github.com/syrupy-project/syrupy/tree/main/tests/integration/test_custom_comparator.py)
- [JPEG image extension](https://github.com/syrupy-project/syrupy/tree/main/tests/examples/test_custom_image_extension.py)
- [Built-in image extensions](https://github.com/syrupy-project/syrupy/blob/main/tests/syrupy/extensions/image/test_image_svg.py)
### Inline Snapshots
Syrupy does not support inline snapshots. For inline snapshots, we recommend checking out the [inline-snapshot](https://github.com/15r10nk/inline-snapshot) library.
## IDE Integrations
### PyCharm
The [PyCharm](https://www.jetbrains.com/pycharm/) IDE comes with a built-in tool for visualizing differences between expected and actual results in a test. To properly render Syrupy snapshots in the PyCharm diff viewer, we need to apply a patch to the diff viewer library. To do this, use the `--snapshot-patch-pycharm-diff` flag, e.g.:
In your `pytest.ini`:
```ini
[pytest]
addopts = --snapshot-patch-pycharm-diff
```
See [#675](https://github.com/syrupy-project/syrupy/issues/675) for the original issue.
## Known Limitations
- `pytest-xdist` support only partially exists. There is no issue when it comes to reads however when you attempt to run `pytest --snapshot-update`, if running with more than 1 process, the ability to detect unused snapshots is disabled. See [#535](https://github.com/syrupy-project/syrupy/issues/535) for more information.
_We welcome contributions to patch these known limitations._
## Uninstalling
```python
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.
## 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](https://github.com/syrupy-project/syrupy/tree/main/CONTRIBUTING.md)
## Contributors
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
<tbody>
<tr>
<td align="center" valign="top" width="14.28%"><a href="https://noahnu.com"><img src="https://avatars0.githubusercontent.com/u/1297096?v=4?s=100" width="100px;" alt="Noah"/><br /><sub><b>Noah</b></sub></a><br /><a href="#infra-noahnu" title="Infrastructure (Hosting, Build-Tools, etc)">π</a> <a href="#ideas-noahnu" title="Ideas, Planning, & Feedback">π€</a> <a href="https://github.com/syrupy-project/syrupy/commits?author=noahnu" title="Code">π»</a> <a href="https://github.com/syrupy-project/syrupy/commits?author=noahnu" title="Documentation">π</a> <a href="https://github.com/syrupy-project/syrupy/commits?author=noahnu" title="Tests">β οΈ</a></td>
<td align="center" valign="top" width="14.28%"><a href="http://emmanuel.ogbizi.com"><img src="https://avatars0.githubusercontent.com/u/2528959?v=4?s=100" width="100px;" alt="Emmanuel Ogbizi"/><br /><sub><b>Emmanuel Ogbizi</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/commits?author=iamogbz" title="Code">π»</a> <a href="#design-iamogbz" title="Design">π¨</a> <a href="#infra-iamogbz" title="Infrastructure (Hosting, Build-Tools, etc)">π</a> <a href="https://github.com/syrupy-project/syrupy/commits?author=iamogbz" title="Documentation">π</a> <a href="https://github.com/syrupy-project/syrupy/commits?author=iamogbz" title="Tests">β οΈ</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/adamlazz"><img src="https://avatars3.githubusercontent.com/u/453811?v=4?s=100" width="100px;" alt="Adam Lazzarato"/><br /><sub><b>Adam Lazzarato</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/commits?author=adamlazz" title="Documentation">π</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://mcataford.github.io"><img src="https://avatars2.githubusercontent.com/u/6210361?v=4?s=100" width="100px;" alt="Marc Cataford"/><br /><sub><b>Marc Cataford</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/commits?author=mcataford" title="Code">π»</a> <a href="https://github.com/syrupy-project/syrupy/commits?author=mcataford" title="Tests">β οΈ</a></td>
<td align="center" valign="top" width="14.28%"><a href="http://msrose.github.io"><img src="https://avatars3.githubusercontent.com/u/3495264?v=4?s=100" width="100px;" alt="Michael Rose"/><br /><sub><b>Michael Rose</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/commits?author=msrose" title="Code">π»</a> <a href="https://github.com/syrupy-project/syrupy/commits?author=msrose" title="Tests">β οΈ</a></td>
<td align="center" valign="top" width="14.28%"><a href="http://fashionablenonsense.com/"><img src="https://avatars0.githubusercontent.com/u/3112159?v=4?s=100" width="100px;" alt="Jimmy Jia"/><br /><sub><b>Jimmy Jia</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/commits?author=taion" title="Code">π»</a> <a href="https://github.com/syrupy-project/syrupy/commits?author=taion" title="Tests">β οΈ</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://stevenloria.com"><img src="https://avatars2.githubusercontent.com/u/2379650?v=4?s=100" width="100px;" alt="Steven Loria"/><br /><sub><b>Steven Loria</b></sub></a><br /><a href="#infra-sloria" title="Infrastructure (Hosting, Build-Tools, etc)">π</a></td>
</tr>
<tr>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/arturbalabanov"><img src="https://avatars1.githubusercontent.com/u/3062003?v=4?s=100" width="100px;" alt="Artur Balabanov"/><br /><sub><b>Artur Balabanov</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/commits?author=arturbalabanov" title="Code">π»</a></td>
<td align="center" valign="top" width="14.28%"><a href="http://huonw.github.io/"><img src="https://avatars1.githubusercontent.com/u/1203825?v=4?s=100" width="100px;" alt="Huon Wilson"/><br /><sub><b>Huon Wilson</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/commits?author=huonw" title="Code">π»</a> <a href="https://github.com/syrupy-project/syrupy/issues?q=author%3Ahuonw" title="Bug reports">π</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/eaculb"><img src="https://avatars.githubusercontent.com/u/31480498?v=4?s=100" width="100px;" alt="Elizabeth Culbertson"/><br /><sub><b>Elizabeth Culbertson</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/commits?author=eaculb" title="Code">π»</a> <a href="https://github.com/syrupy-project/syrupy/commits?author=eaculb" title="Tests">β οΈ</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/joakimnordling"><img src="https://avatars.githubusercontent.com/u/6637576?v=4?s=100" width="100px;" alt="Joakim Nordling"/><br /><sub><b>Joakim Nordling</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/issues?q=author%3Ajoakimnordling" title="Bug reports">π</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/bendidi"><img src="https://avatars.githubusercontent.com/u/22003440?v=4?s=100" width="100px;" alt="Ouail"/><br /><sub><b>Ouail</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/commits?author=bendidi" title="Code">π»</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/fbjorn"><img src="https://avatars.githubusercontent.com/u/9670990?v=4?s=100" width="100px;" alt="Denis"/><br /><sub><b>Denis</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/commits?author=fbjorn" title="Code">π»</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/N0124"><img src="https://avatars.githubusercontent.com/u/29734397?v=4?s=100" width="100px;" alt="N0124"/><br /><sub><b>N0124</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/commits?author=N0124" title="Code">π»</a></td>
</tr>
<tr>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/dtczest"><img src="https://avatars.githubusercontent.com/u/97055299?v=4?s=100" width="100px;" alt="dtczest"/><br /><sub><b>dtczest</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/issues?q=author%3Adtczest" title="Bug reports">π</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/spagh-eddie"><img src="https://avatars.githubusercontent.com/u/58013020?v=4?s=100" width="100px;" alt="Eddie Darling"/><br /><sub><b>Eddie Darling</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/commits?author=spagh-eddie" title="Documentation">π</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/darrenburns"><img src="https://avatars.githubusercontent.com/u/5740731?v=4?s=100" width="100px;" alt="darrenburns"/><br /><sub><b>darrenburns</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/commits?author=darrenburns" title="Documentation">π</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/mhwaage"><img src="https://avatars.githubusercontent.com/u/57612883?v=4?s=100" width="100px;" alt="Magnus Heskestad Waage"/><br /><sub><b>Magnus Heskestad Waage</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/issues?q=author%3Amhwaage" title="Bug reports">π</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/herb"><img src="https://avatars.githubusercontent.com/u/139780?v=4?s=100" width="100px;" alt="Herbert Ho"/><br /><sub><b>Herbert Ho</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/issues?q=author%3Aherb" title="Bug reports">π</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/tolgaeren"><img src="https://avatars.githubusercontent.com/u/794719?v=4?s=100" width="100px;" alt="Tolga Eren"/><br /><sub><b>Tolga Eren</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/issues?q=author%3Atolgaeren" title="Bug reports">π</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://johnkurkowski.com"><img src="https://avatars.githubusercontent.com/u/299487?v=4?s=100" width="100px;" alt="John Kurkowski"/><br /><sub><b>John Kurkowski</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/issues?q=author%3Ajohn-kurkowski" title="Bug reports">π</a></td>
</tr>
<tr>
<td align="center" valign="top" width="14.28%"><a href="https://www.atharvaarya.tech/"><img src="https://avatars.githubusercontent.com/u/55894364?v=4?s=100" width="100px;" alt="Atharva Arya"/><br /><sub><b>Atharva Arya</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/commits?author=atharva-2001" title="Code">π»</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/michaljelonek"><img src="https://avatars.githubusercontent.com/u/7791528?v=4?s=100" width="100px;" alt="MichaΕ Jelonek"/><br /><sub><b>MichaΕ Jelonek</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/commits?author=michaljelonek" title="Code">π»</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/ManiacDC"><img src="https://avatars.githubusercontent.com/u/1823305?v=4?s=100" width="100px;" alt="ManiacDC"/><br /><sub><b>ManiacDC</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/commits?author=ManiacDC" title="Code">π»</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://schemathesis.io/"><img src="https://avatars.githubusercontent.com/u/1236561?v=4?s=100" width="100px;" alt="Dmitry Dygalo"/><br /><sub><b>Dmitry Dygalo</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/commits?author=Stranger6667" title="Documentation">π</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://allanchain.github.io/"><img src="https://avatars.githubusercontent.com/u/36528777?v=4?s=100" width="100px;" alt="Allan Chain"/><br /><sub><b>Allan Chain</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/issues?q=author%3AAllanChain" title="Bug reports">π</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/UltimateLobster"><img src="https://avatars.githubusercontent.com/u/21122724?v=4?s=100" width="100px;" alt="Nir Schulman"/><br /><sub><b>Nir Schulman</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/commits?author=UltimateLobster" title="Code">π»</a></td>
<td align="center" valign="top" width="14.28%"><a href="http://joostlek.dev"><img src="https://avatars.githubusercontent.com/u/7083755?v=4?s=100" width="100px;" alt="Joost Lekkerkerker"/><br /><sub><b>Joost Lekkerkerker</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/commits?author=joostlek" title="Code">π»</a></td>
</tr>
<tr>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/epenet"><img src="https://avatars.githubusercontent.com/u/6771947?v=4?s=100" width="100px;" alt="epenet"/><br /><sub><b>epenet</b></sub></a><br /><a href="https://github.com/syrupy-project/syrupy/commits?author=epenet" title="Tests">β οΈ</a></td>
</tr>
</tbody>
</table>
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- ALL-CONTRIBUTORS-LIST:END -->
This section is automatically generated via tagging the all-contributors bot in a PR:
```text
@all-contributors please add <username> for <contribution type>
```
## License
Syrupy is licensed under [Apache License Version 2.0](https://github.com/syrupy-project/syrupy/tree/main/LICENSE).
Raw data
{
"_id": null,
"home_page": "https://github.com/syrupy-project/syrupy",
"name": "syrupy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8.1",
"maintainer_email": null,
"keywords": null,
"author": "Noah Ulster",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/57/54/07f40c1e9355c0eb6909b83abd8ea2c523a1e05b8257a575bbaa42df28de/syrupy-4.8.0.tar.gz",
"platform": null,
"description": "# syrupy\n\n<img align=\"right\" width=\"100px\" height=\"100px\" src=\"https://user-images.githubusercontent.com/2528959/69500147-85d71400-0ec6-11ea-867a-277881278e57.png\" alt=\"Logo\">\n\n[](#contributors) [](https://pypi.org/project/syrupy/) [](https://codecov.io/gh/syrupy-project/syrupy)\n\n [](https://pypi.org/project/syrupy/) [](https://pypi.org/project/syrupy/)  [](https://pypi.org/project/syrupy/) [](./LICENSE)\n\n## Overview\n\nSyrupy 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.\n\n## Motivation\n\nThe most popular snapshot test plugin compatible with pytest has some core limitations which this package attempts to address by upholding some key values:\n\n- Extensible: If a particular data type is not supported, users should be able to easily and quickly add support.\n- Idiomatic: Snapshot testing should fit naturally among other test cases in pytest, e.g. `assert x == snapshot` vs. `snapshot.assert_match(x)`.\n- 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.\n\n## Installation\n\n```shell\npython -m pip install syrupy\n```\n\n### Migration from snapshottest\n\nYou 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:\n\n```shell\npip uninstall snapshottest -y;\nfind . -type d ! -path '*/\\.*' -name 'snapshots' | xargs rm -r\n```\n\n### Pytest and Python Compatibility\n\nSyrupy 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:\n\n| Syrupy Version | Python Support | Pytest Support |\n| -------------- | -------------- | -------------- |\n| 4.x.x | >3.8.1 | >=7 |\n| 3.x.x | >=3.7, <4 | >=5.1, <8 |\n| 2.x.x | >=3.6, <4 | >=5.1, <8 |\n\n## Usage\n\n### Basic Usage\n\nIn a pytest test file `test_file.py`:\n\n```python\ndef test_foo(snapshot):\n actual = \"Some computed value!\"\n assert actual == snapshot\n```\n\nwhen you run `pytest`, the above test should fail due to a missing snapshot. Re-run pytest with the update snapshots flag like so:\n\n```shell\npytest --snapshot-update\n```\n\nA 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.\n\n#### Custom Objects\n\nThe default serializer supports all python built-in types and provides a sensible default for custom objects.\n\n#### Representation\n\nIf you need to customise your object snapshot, it is as easy as overriding the default `__repr__` implementation.\n\n```python\ndef __repr__(self) -> str:\n return \"MyCustomClass(...)\"\n```\n\nIf you need bypass a custom object representation to use the amber standard, it is easy using the following helpers.\n\n```python\ndef test_object_as_named_tuple(snapshot):\n assert snapshot == AmberDataSerializer.object_as_named_tuple(obj_with_custom_repr)\n```\n\n> See `test_snapshot_object_as_named_tuple_class` for an example on automatically doing this for all nested properties\n\n#### Attributes\n\nIf you want to limit what properties are serialized at a class type level you could either:\n\n**A**. Provide a filter function to the snapshot [exclude](#exclude) configuration option.\n\n```py\ndef limit_foo_attrs(prop, path):\n allowed_foo_attrs = {\"do\", \"not\", \"serialize\", \"these\", \"attrs\"}\n return isinstance(path[-1][1], Foo) and prop in allowed_foo_attrs\n\ndef test_bar(snapshot):\n actual = Foo(...)\n assert actual == snapshot(exclude=limit_foo_attrs)\n```\n\n**B**. Provide a filter function to the snapshot [include](#include) configuration option.\n\n```py\ndef limit_foo_attrs(prop, path):\n allowed_foo_attrs = {\"only\", \"serialize\", \"these\", \"attrs\"}\n return isinstance(path[-1][1], Foo) and prop in allowed_foo_attrs\n\ndef test_bar(snapshot):\n actual = Foo(...)\n assert actual == snapshot(include=limit_foo_attrs)\n```\n\n**C**. Or override the `__dir__` implementation to control the attribute list.\n\n```py\nclass Foo:\n def __dir__(self):\n return [\"only\", \"serialize\", \"these\", \"attrs\"]\n\ndef test_bar(snapshot):\n actual = Foo(...)\n assert actual == snapshot\n```\n\nBoth options will generate equivalent snapshots but the latter is only viable when you have control over the class implementation and do not need to share the exclusion logic with other objects.\n\n### CLI Options\n\nThese are the cli options exposed to `pytest` by the plugin.\n\n| Option | Description | Default |\n| ------------------------------ |--------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|\n| `--snapshot-update` | Snapshots will be updated to match assertions and unused snapshots will be deleted. | `False` |\n| `--snapshot-details` | Includes details of unused snapshots (test name and snapshot location) in the final report. | `False` |\n| `--snapshot-warn-unused` | Prints a warning on unused snapshots rather than fail the test suite. | `False` |\n| `--snapshot-default-extension` | Use to change the default snapshot extension class. | [AmberSnapshotExtension](https://github.com/syrupy-project/syrupy/blob/main/src/syrupy/extensions/amber/__init__.py) |\n| `--snapshot-no-colors` | Disable test results output highlighting. Equivalent to setting the environment variables `ANSI_COLORS_DISABLED` or `NO_COLOR` | Disabled by default if not in terminal. |\n| `--snapshot-patch-pycharm-diff`| Override PyCharm's default diffs viewer when looking at snapshot diffs. See [IDE Integrations](#ide-integrations) | `False` |\n| `--snapshot-diff-mode` | Configures how diffs are displayed on assertion failure. If working with very large snapshots, disabling the diff can improve performance. | `detailed` |\n\n### Assertion Options\n\nThese are the options available on the `snapshot` assertion fixture.\nUse of these options are one shot and do not persist across assertions.\nFor more persistent options see [advanced usage](#advanced-usage).\n\n#### `matcher`\n\nThis allows you to match on a property path and value to control how specific object shapes are serialized.\n\nThe matcher is a function that takes two keyword arguments.\nIt should return the replacement value to be serialized or the original unmutated value.\n\n| Argument | Description |\n| -------- | ------------------------------------------------------------------------------------------------------------------ |\n| `data` | Current serializable value being matched on |\n| `path` | Ordered path traversed to the current value e.g. `((\"a\", dict), (\"b\", dict))` from `{ \"a\": { \"b\": { \"c\": 1 } } }`} |\n\n**NOTE:** Do not mutate the value received as it could cause unintended side effects.\n\n##### Built-In Matchers\n\nSyrupy comes with built-in helpers that can be used to make easy work of using property matchers.\n\n###### `path_type(mapping=None, *, types=(), strict=True, regex=False)`\n\nEasy way to build a matcher that uses the path and value type to replace serialized data.\nWhen strict, this will raise a `ValueError` if the types specified are not matched.\n\n| Argument | Description |\n| ---------- | ---------------------------------------------------------------------------------------------------------------------------------- |\n| `mapping` | Dict of path string to tuples of class types, including primitives e.g. (MyClass, UUID, datetime, int, str) |\n| `types` | Tuple of class types used if none of the path strings from the mapping are matched |\n| `strict` | If a path is matched but the value at the path does not match one of the class types in the tuple then a `PathTypeError` is raised |\n| `regex` | If true, the `mapping` key is treated as a regular expression when matching paths |\n| `replacer` | Called with any matched value and result is used as the replacement that is serialized. Defaults to the object type when not given |\n\n```py\nfrom syrupy.matchers import path_type\n\ndef test_bar(snapshot):\n actual = {\n \"date_created\": datetime.now(),\n \"value\": \"Some computed value!!\",\n }\n assert actual == snapshot(matcher=path_type({\n \"date_created\": (datetime,),\n \"nested.path.id\": (int,),\n }))\n```\n\n```py\n# name: test_bar\n dict({\n 'date_created': datetime,\n 'value': 'Some computed value!!',\n })\n# ---\n```\n\n> NOTE: When `regex` is `True` all matcher mappings are treated as regex patterns\n\n###### `path_value(mapping=None, *, **kwargs)`\n\nShares the same `kwargs` as `path_type` matcher, with the exception of the `mapping` argument type.\nOnly runs replacement for objects at a matching path where the value of the mapping also matches the object data string repr.\n\n| Argument | Description |\n| --------- | ---------------------------------------------------------- |\n| `mapping` | Dict of path string to object value string representations |\n\n> See `test_regex_matcher_str_value` for example usage.\n\n#### `exclude`\n\nThis allows you to filter out object properties from the serialized snapshot.\n\nThe exclude parameter takes a filter function that accepts two keyword arguments.\nIt should return `true` if the property should be excluded, or `false` if the property should be included.\n\n| Argument | Description |\n| -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |\n| `prop` | Current property on the object, could be any hashable value that can be used to retrieve a value e.g. `1`, `\"prop_str\"`, `SomeHashableObject` |\n| `path` | Ordered path traversed to the current value e.g. `((\"a\", dict), (\"b\", dict))` from `{ \"a\": { \"b\": { \"c\": 1 } } }`} |\n\n##### Built-In Filters\n\nSyrupy comes with built-in helpers that can be used to make easy work of using the filter options.\n\n###### `props(prop_name, *prop_name)`\n\nEasy way to build a filter that excludes based on string based property names.\n\nTakes an argument list of property names, with support for indexed iterables.\n\n```py\nfrom syrupy.filters import props\n\ndef test_bar(snapshot):\n actual = {\n \"id\": uuid.uuid4(),\n \"list\": [1,2,3],\n }\n assert actual == snapshot(exclude=props(\"id\", \"1\"))\n```\n\n```py\n# name: test_bar\n dict({\n 'list': list([\n 1,\n 3,\n ]),\n })\n# ---\n```\n\n###### `paths(path_string, *path_strings)`\n\nEasy way to build a filter that uses full path strings delimited with `.`.\n\nTakes an argument list of path strings.\n\n```py\nfrom syrupy.filters import paths\n\ndef test_bar(snapshot):\n actual = {\n \"date\": datetime.now(),\n \"list\": [1,2,3],\n }\n assert actual == snapshot(exclude=paths(\"date\", \"list.1\"))\n```\n\n```py\n# name: test_bar\n dict({\n 'list': list([\n 1,\n 3,\n ]),\n })\n# ---\n```\n\n#### `include`\n\nThis allows you filter an object's properties to a subset using a predicate. This is the opposite of [exclude](#exclude). All the same property filters supporterd by [exclude](#exclude) are supported for `include`.\n\nThe include parameter takes a filter function that accepts two keyword arguments.\nIt should return `true` if the property should be include, or `false` if the property should not be included.\n\n| Argument | Description |\n| -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |\n| `prop` | Current property on the object, could be any hashable value that can be used to retrieve a value e.g. `1`, `\"prop_str\"`, `SomeHashableObject` |\n| `path` | Ordered path traversed to the current value e.g. `((\"a\", dict), (\"b\", dict))` from `{ \"a\": { \"b\": { \"c\": 1 } } }`}\n\nNote that `include` has some caveats which make it a bit more difficult to use than `exclude`. Both `include` and `exclude` are evaluated for each key of an object before traversing down nested paths. This means if you want to include a nested path, you must include all parents of the nested path, otherwise the nested child will never be reached to be evaluated against the include predicate. For example:\n\n```py\nobj = {\n \"nested\": { \"key\": True }\n}\nassert obj == snapshot(include=paths(\"nested\", \"nested.key\"))\n```\n\nThe extra \"nested\" is required, otherwise the nested dictionary will never be searched -- it'd get pruned too early.\n\nTo avoid adding duplicate path parts, we provide a convenient `paths_include` which supports a list/tuple instead of a string for each path to match:\n\n```py\nobj = {\n \"other\": False,\n \"nested\": { \"key\": True }\n}\nassert obj == snapshot(include=paths_include([\"other\"], [\"nested\", \"key\"]))\n```\n\n#### `extension_class`\n\nThis is a way to modify how the snapshot matches and serializes your data in a single assertion.\n\n```py\ndef test_foo(snapshot):\n actual_svg = \"<svg></svg>\"\n assert actual_svg == snapshot(extension_class=SVGImageSnapshotExtension)\n```\n\n#### `diff`\n\nThis is an option to snapshot only the diff between the actual object and a previous snapshot, with the `diff` argument being the previous snapshot `index`/`name`.\n\n```py\ndef test_diff(snapshot):\n actual0 = [1,2,3,4]\n actual1 = [0,1,3,4]\n\n assert actual0 == snapshot\n assert actual1 == snapshot(diff=0)\n # This is equivalent to the lines above\n # Must use the index name to diff when given\n assert actual0 == snapshot(name='snap_name')\n assert actual1 == snapshot(diff='snap_name')\n```\n\n##### Built-In Extensions\n\nSyrupy 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.\n\n- **`AmberSnapshotExtension`**: This is the default extension which generates `.ambr` files. Serialization of most data types are supported.\n - Line control characters are normalised when snapshots are generated i.e. `\\r` and `\\n` characters are all written as `\\n`. This is to allow interoperability of snapshots between operating systems that use disparate line control characters.\n- **`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.\n- **`PNGImageSnapshotExtension`**: An extension of single file, this should be used to produce `.png` files from a byte string.\n- **`SVGImageSnapshotExtension`**: Another extension of single file. This produces `.svg` files from an svg string.\n- **`JSONSnapshotExtension`**: Another extension of single file. This produces `.json` files from dictionaries and lists.\n\n#### `name`\n\nBy default, if you make multiple snapshot assertions within a single test case, an auto-increment identifier will be used to index the snapshots. You can override this behaviour by specifying a custom snapshot name to use in place of the auto-increment number.\n\n```py\ndef test_case(snapshot):\n assert \"actual\" == snapshot(name=\"case_a\")\n assert \"other\" == snapshot(name=\"case_b\")\n```\n\n> _Warning_: If you use a custom name, you must make sure the name is not re-used within a test case.\n\n### Advanced Usage\n\nBy overriding the provided [`AbstractSyrupyExtension`](https://github.com/syrupy-project/syrupy/tree/main/src/syrupy/extensions/base.py) you can implement varied custom behaviours.\n\nSee examples of how syrupy can be used and extended in the [test examples](https://github.com/syrupy-project/syrupy/tree/main/tests/examples).\n\n#### Overriding defaults\n\nIt is possible to override `include`, `exclude`, `matchers` and `extension_class` on a more global level just once,\ninstead of every time per test. By default, after every assertion the modified values per snapshot assert are reverted\nto their default values. However, it is possible to override those default values with ones you would like persisted,\nwhich will be treated as the new defaults.\n\nTo achieve that you can use `snapshot.with_defaults`, which will create new instance of `SnapshotAssertion` with the provided values.\n\n`snapshot.use_extension` is retained for compatibility. However, it is limited to only overriding the default extension class.\n\n#### JSONSnapshotExtension\n\nThis extension can be useful when testing API responses, or when you have to deal with long dictionaries that are cumbersome to validate inside a test. For example:\n\n```python\nimport pytest\n\nfrom syrupy.extensions.json import JSONSnapshotExtension\n\n@pytest.fixture\ndef snapshot_json(snapshot):\n return snapshot.with_defaults(extension_class=JSONSnapshotExtension)\n # or return snapshot.use_extension(JSONSnapshotExtension)\n\n\ndef test_api_call(client, snapshot_json):\n resp = client.post(\"/endpoint\")\n assert resp.status_code == 200\n assert snapshot_json == resp.json()\n```\n\nAPI responses often contain dynamic data, like IDs or dates. You can still validate and store other data of a response by leveraging syrupy matchers. For example:\n\n```py\nfrom datetime import datetime\n\nfrom syrupy.matchers import path_type\n\ndef test_api_call(client, snapshot_json):\n resp = client.post(\"/user\", json={\"name\": \"Jane\"})\n assert resp.status_code == 201\n\n matcher = path_type({\n \"id\": (int,),\n \"registeredAt\": (datetime,)\n })\n assert snapshot_json(matcher=matcher) == resp.json()\n```\n\nThe generated snapshot:\n\n```json\n{\n \"id\": \"<class 'int'>\",\n \"registeredAt\": \"<class 'datetime'>\",\n \"name\": \"Jane\"\n}\n```\n\nOr a case where the value needs to be replaced using a condition e.g. file path string\n\n```py\nimport re\n\nfrom syrupy.matchers import path_type\n\ndef test_matches_generated_string_value(snapshot, tmp_file):\n matcher = path_value(\n mapping={\"file_path\": r\"\\w+://(.*/)+dir/filename.txt\"},\n replacer=lambda _, match: match[0].replace(match[1], \"<tmp-file-path>/\"),\n types=(str,),\n )\n\n assert snapshot(matcher=matcher) == tmp_file\n```\n\nThe generated snapshot:\n\n```json\n{\n \"name\": \"Temp Files\",\n \"file_path\": \"scheme://<tmp-file-path>/dir/filename.txt\"\n}\n```\n\n### Extending Syrupy\n\n- [Custom defaults](https://github.com/syrupy-project/syrupy/tree/main/tests/examples/test_custom_defaults.py)\n- [Custom snapshot directory 1](https://github.com/syrupy-project/syrupy/tree/main/tests/examples/test_custom_snapshot_directory.py)\n- [Custom snapshot directory 2](https://github.com/syrupy-project/syrupy/tree/main/tests/examples/test_custom_snapshot_directory_2.py)\n- [Custom snapshot name](https://github.com/syrupy-project/syrupy/tree/main/tests/examples/test_custom_snapshot_name.py)\n- [Custom object snapshots](https://github.com/syrupy-project/syrupy/tree/main/tests/examples/test_custom_object_repr.py)\n- [Custom comparator](https://github.com/syrupy-project/syrupy/tree/main/tests/integration/test_custom_comparator.py)\n- [JPEG image extension](https://github.com/syrupy-project/syrupy/tree/main/tests/examples/test_custom_image_extension.py)\n- [Built-in image extensions](https://github.com/syrupy-project/syrupy/blob/main/tests/syrupy/extensions/image/test_image_svg.py)\n\n### Inline Snapshots\n\nSyrupy does not support inline snapshots. For inline snapshots, we recommend checking out the [inline-snapshot](https://github.com/15r10nk/inline-snapshot) library.\n\n## IDE Integrations\n\n### PyCharm\n\nThe [PyCharm](https://www.jetbrains.com/pycharm/) IDE comes with a built-in tool for visualizing differences between expected and actual results in a test. To properly render Syrupy snapshots in the PyCharm diff viewer, we need to apply a patch to the diff viewer library. To do this, use the `--snapshot-patch-pycharm-diff` flag, e.g.:\n\nIn your `pytest.ini`:\n\n```ini\n[pytest]\naddopts = --snapshot-patch-pycharm-diff\n```\n\nSee [#675](https://github.com/syrupy-project/syrupy/issues/675) for the original issue.\n\n## Known Limitations\n\n- `pytest-xdist` support only partially exists. There is no issue when it comes to reads however when you attempt to run `pytest --snapshot-update`, if running with more than 1 process, the ability to detect unused snapshots is disabled. See [#535](https://github.com/syrupy-project/syrupy/issues/535) for more information.\n\n_We welcome contributions to patch these known limitations._\n\n## Uninstalling\n\n```python\npip uninstall syrupy\n```\n\nIf 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.\n\n## Contributing\n\nFeel free to open a PR or GitHub issue. Contributions welcome!\n\nTo develop locally, clone this repository and run `. script/bootstrap` to install test dependencies. You can then use `invoke --list` to see available commands.\n\n### See contributing [guide](https://github.com/syrupy-project/syrupy/tree/main/CONTRIBUTING.md)\n\n## Contributors\n\n<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->\n<!-- prettier-ignore-start -->\n<!-- markdownlint-disable -->\n<table>\n <tbody>\n <tr>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://noahnu.com\"><img src=\"https://avatars0.githubusercontent.com/u/1297096?v=4?s=100\" width=\"100px;\" alt=\"Noah\"/><br /><sub><b>Noah</b></sub></a><br /><a href=\"#infra-noahnu\" title=\"Infrastructure (Hosting, Build-Tools, etc)\">\ud83d\ude87</a> <a href=\"#ideas-noahnu\" title=\"Ideas, Planning, & Feedback\">\ud83e\udd14</a> <a href=\"https://github.com/syrupy-project/syrupy/commits?author=noahnu\" title=\"Code\">\ud83d\udcbb</a> <a href=\"https://github.com/syrupy-project/syrupy/commits?author=noahnu\" title=\"Documentation\">\ud83d\udcd6</a> <a href=\"https://github.com/syrupy-project/syrupy/commits?author=noahnu\" title=\"Tests\">\u26a0\ufe0f</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"http://emmanuel.ogbizi.com\"><img src=\"https://avatars0.githubusercontent.com/u/2528959?v=4?s=100\" width=\"100px;\" alt=\"Emmanuel Ogbizi\"/><br /><sub><b>Emmanuel Ogbizi</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/commits?author=iamogbz\" title=\"Code\">\ud83d\udcbb</a> <a href=\"#design-iamogbz\" title=\"Design\">\ud83c\udfa8</a> <a href=\"#infra-iamogbz\" title=\"Infrastructure (Hosting, Build-Tools, etc)\">\ud83d\ude87</a> <a href=\"https://github.com/syrupy-project/syrupy/commits?author=iamogbz\" title=\"Documentation\">\ud83d\udcd6</a> <a href=\"https://github.com/syrupy-project/syrupy/commits?author=iamogbz\" title=\"Tests\">\u26a0\ufe0f</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://github.com/adamlazz\"><img src=\"https://avatars3.githubusercontent.com/u/453811?v=4?s=100\" width=\"100px;\" alt=\"Adam Lazzarato\"/><br /><sub><b>Adam Lazzarato</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/commits?author=adamlazz\" title=\"Documentation\">\ud83d\udcd6</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://mcataford.github.io\"><img src=\"https://avatars2.githubusercontent.com/u/6210361?v=4?s=100\" width=\"100px;\" alt=\"Marc Cataford\"/><br /><sub><b>Marc Cataford</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/commits?author=mcataford\" title=\"Code\">\ud83d\udcbb</a> <a href=\"https://github.com/syrupy-project/syrupy/commits?author=mcataford\" title=\"Tests\">\u26a0\ufe0f</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"http://msrose.github.io\"><img src=\"https://avatars3.githubusercontent.com/u/3495264?v=4?s=100\" width=\"100px;\" alt=\"Michael Rose\"/><br /><sub><b>Michael Rose</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/commits?author=msrose\" title=\"Code\">\ud83d\udcbb</a> <a href=\"https://github.com/syrupy-project/syrupy/commits?author=msrose\" title=\"Tests\">\u26a0\ufe0f</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"http://fashionablenonsense.com/\"><img src=\"https://avatars0.githubusercontent.com/u/3112159?v=4?s=100\" width=\"100px;\" alt=\"Jimmy Jia\"/><br /><sub><b>Jimmy Jia</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/commits?author=taion\" title=\"Code\">\ud83d\udcbb</a> <a href=\"https://github.com/syrupy-project/syrupy/commits?author=taion\" title=\"Tests\">\u26a0\ufe0f</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://stevenloria.com\"><img src=\"https://avatars2.githubusercontent.com/u/2379650?v=4?s=100\" width=\"100px;\" alt=\"Steven Loria\"/><br /><sub><b>Steven Loria</b></sub></a><br /><a href=\"#infra-sloria\" title=\"Infrastructure (Hosting, Build-Tools, etc)\">\ud83d\ude87</a></td>\n </tr>\n <tr>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://github.com/arturbalabanov\"><img src=\"https://avatars1.githubusercontent.com/u/3062003?v=4?s=100\" width=\"100px;\" alt=\"Artur Balabanov\"/><br /><sub><b>Artur Balabanov</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/commits?author=arturbalabanov\" title=\"Code\">\ud83d\udcbb</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"http://huonw.github.io/\"><img src=\"https://avatars1.githubusercontent.com/u/1203825?v=4?s=100\" width=\"100px;\" alt=\"Huon Wilson\"/><br /><sub><b>Huon Wilson</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/commits?author=huonw\" title=\"Code\">\ud83d\udcbb</a> <a href=\"https://github.com/syrupy-project/syrupy/issues?q=author%3Ahuonw\" title=\"Bug reports\">\ud83d\udc1b</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://github.com/eaculb\"><img src=\"https://avatars.githubusercontent.com/u/31480498?v=4?s=100\" width=\"100px;\" alt=\"Elizabeth Culbertson\"/><br /><sub><b>Elizabeth Culbertson</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/commits?author=eaculb\" title=\"Code\">\ud83d\udcbb</a> <a href=\"https://github.com/syrupy-project/syrupy/commits?author=eaculb\" title=\"Tests\">\u26a0\ufe0f</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://github.com/joakimnordling\"><img src=\"https://avatars.githubusercontent.com/u/6637576?v=4?s=100\" width=\"100px;\" alt=\"Joakim Nordling\"/><br /><sub><b>Joakim Nordling</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/issues?q=author%3Ajoakimnordling\" title=\"Bug reports\">\ud83d\udc1b</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://github.com/bendidi\"><img src=\"https://avatars.githubusercontent.com/u/22003440?v=4?s=100\" width=\"100px;\" alt=\"Ouail\"/><br /><sub><b>Ouail</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/commits?author=bendidi\" title=\"Code\">\ud83d\udcbb</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://github.com/fbjorn\"><img src=\"https://avatars.githubusercontent.com/u/9670990?v=4?s=100\" width=\"100px;\" alt=\"Denis\"/><br /><sub><b>Denis</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/commits?author=fbjorn\" title=\"Code\">\ud83d\udcbb</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://github.com/N0124\"><img src=\"https://avatars.githubusercontent.com/u/29734397?v=4?s=100\" width=\"100px;\" alt=\"N0124\"/><br /><sub><b>N0124</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/commits?author=N0124\" title=\"Code\">\ud83d\udcbb</a></td>\n </tr>\n <tr>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://github.com/dtczest\"><img src=\"https://avatars.githubusercontent.com/u/97055299?v=4?s=100\" width=\"100px;\" alt=\"dtczest\"/><br /><sub><b>dtczest</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/issues?q=author%3Adtczest\" title=\"Bug reports\">\ud83d\udc1b</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://github.com/spagh-eddie\"><img src=\"https://avatars.githubusercontent.com/u/58013020?v=4?s=100\" width=\"100px;\" alt=\"Eddie Darling\"/><br /><sub><b>Eddie Darling</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/commits?author=spagh-eddie\" title=\"Documentation\">\ud83d\udcd6</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://github.com/darrenburns\"><img src=\"https://avatars.githubusercontent.com/u/5740731?v=4?s=100\" width=\"100px;\" alt=\"darrenburns\"/><br /><sub><b>darrenburns</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/commits?author=darrenburns\" title=\"Documentation\">\ud83d\udcd6</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://github.com/mhwaage\"><img src=\"https://avatars.githubusercontent.com/u/57612883?v=4?s=100\" width=\"100px;\" alt=\"Magnus Heskestad Waage\"/><br /><sub><b>Magnus Heskestad Waage</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/issues?q=author%3Amhwaage\" title=\"Bug reports\">\ud83d\udc1b</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://github.com/herb\"><img src=\"https://avatars.githubusercontent.com/u/139780?v=4?s=100\" width=\"100px;\" alt=\"Herbert Ho\"/><br /><sub><b>Herbert Ho</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/issues?q=author%3Aherb\" title=\"Bug reports\">\ud83d\udc1b</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://github.com/tolgaeren\"><img src=\"https://avatars.githubusercontent.com/u/794719?v=4?s=100\" width=\"100px;\" alt=\"Tolga Eren\"/><br /><sub><b>Tolga Eren</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/issues?q=author%3Atolgaeren\" title=\"Bug reports\">\ud83d\udc1b</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://johnkurkowski.com\"><img src=\"https://avatars.githubusercontent.com/u/299487?v=4?s=100\" width=\"100px;\" alt=\"John Kurkowski\"/><br /><sub><b>John Kurkowski</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/issues?q=author%3Ajohn-kurkowski\" title=\"Bug reports\">\ud83d\udc1b</a></td>\n </tr>\n <tr>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://www.atharvaarya.tech/\"><img src=\"https://avatars.githubusercontent.com/u/55894364?v=4?s=100\" width=\"100px;\" alt=\"Atharva Arya\"/><br /><sub><b>Atharva Arya</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/commits?author=atharva-2001\" title=\"Code\">\ud83d\udcbb</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://github.com/michaljelonek\"><img src=\"https://avatars.githubusercontent.com/u/7791528?v=4?s=100\" width=\"100px;\" alt=\"Micha\u0142 Jelonek\"/><br /><sub><b>Micha\u0142 Jelonek</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/commits?author=michaljelonek\" title=\"Code\">\ud83d\udcbb</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://github.com/ManiacDC\"><img src=\"https://avatars.githubusercontent.com/u/1823305?v=4?s=100\" width=\"100px;\" alt=\"ManiacDC\"/><br /><sub><b>ManiacDC</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/commits?author=ManiacDC\" title=\"Code\">\ud83d\udcbb</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://schemathesis.io/\"><img src=\"https://avatars.githubusercontent.com/u/1236561?v=4?s=100\" width=\"100px;\" alt=\"Dmitry Dygalo\"/><br /><sub><b>Dmitry Dygalo</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/commits?author=Stranger6667\" title=\"Documentation\">\ud83d\udcd6</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://allanchain.github.io/\"><img src=\"https://avatars.githubusercontent.com/u/36528777?v=4?s=100\" width=\"100px;\" alt=\"Allan Chain\"/><br /><sub><b>Allan Chain</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/issues?q=author%3AAllanChain\" title=\"Bug reports\">\ud83d\udc1b</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://github.com/UltimateLobster\"><img src=\"https://avatars.githubusercontent.com/u/21122724?v=4?s=100\" width=\"100px;\" alt=\"Nir Schulman\"/><br /><sub><b>Nir Schulman</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/commits?author=UltimateLobster\" title=\"Code\">\ud83d\udcbb</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"http://joostlek.dev\"><img src=\"https://avatars.githubusercontent.com/u/7083755?v=4?s=100\" width=\"100px;\" alt=\"Joost Lekkerkerker\"/><br /><sub><b>Joost Lekkerkerker</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/commits?author=joostlek\" title=\"Code\">\ud83d\udcbb</a></td>\n </tr>\n <tr>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://github.com/epenet\"><img src=\"https://avatars.githubusercontent.com/u/6771947?v=4?s=100\" width=\"100px;\" alt=\"epenet\"/><br /><sub><b>epenet</b></sub></a><br /><a href=\"https://github.com/syrupy-project/syrupy/commits?author=epenet\" title=\"Tests\">\u26a0\ufe0f</a></td>\n </tr>\n </tbody>\n</table>\n\n<!-- markdownlint-restore -->\n<!-- prettier-ignore-end -->\n\n<!-- ALL-CONTRIBUTORS-LIST:END -->\n\nThis section is automatically generated via tagging the all-contributors bot in a PR:\n\n```text\n@all-contributors please add <username> for <contribution type>\n```\n\n## License\n\nSyrupy is licensed under [Apache License Version 2.0](https://github.com/syrupy-project/syrupy/tree/main/LICENSE).\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Pytest Snapshot Test Utility",
"version": "4.8.0",
"project_urls": {
"Homepage": "https://github.com/syrupy-project/syrupy",
"Repository": "https://github.com/syrupy-project/syrupy"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "edc78cd6b5fa8cc4a5c025d3d36a014dff44436fda8b3003a471253931c77f1b",
"md5": "fc755c9b3d00fe24c9941c93ec35ce9a",
"sha256": "544f4ec6306f4b1c460fdab48fd60b2c7fe54a6c0a8243aeea15f9ad9c638c3f"
},
"downloads": -1,
"filename": "syrupy-4.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fc755c9b3d00fe24c9941c93ec35ce9a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1",
"size": 49530,
"upload_time": "2024-11-23T23:34:34",
"upload_time_iso_8601": "2024-11-23T23:34:34.697620Z",
"url": "https://files.pythonhosted.org/packages/ed/c7/8cd6b5fa8cc4a5c025d3d36a014dff44436fda8b3003a471253931c77f1b/syrupy-4.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "575407f40c1e9355c0eb6909b83abd8ea2c523a1e05b8257a575bbaa42df28de",
"md5": "64b5680dbf0607acfa3a15f01385437b",
"sha256": "648f0e9303aaa8387c8365d7314784c09a6bab0a407455c6a01d6a4f5c6a8ede"
},
"downloads": -1,
"filename": "syrupy-4.8.0.tar.gz",
"has_sig": false,
"md5_digest": "64b5680dbf0607acfa3a15f01385437b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1",
"size": 49526,
"upload_time": "2024-11-23T23:34:36",
"upload_time_iso_8601": "2024-11-23T23:34:36.399685Z",
"url": "https://files.pythonhosted.org/packages/57/54/07f40c1e9355c0eb6909b83abd8ea2c523a1e05b8257a575bbaa42df28de/syrupy-4.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-23 23:34:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "syrupy-project",
"github_project": "syrupy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "syrupy"
}
JSON
