# pytest-insta
[](https://pypi.org/project/pytest-insta/)
[](https://pypi.org/project/pytest-insta/)
[](https://github.com/ambv/black)
> A practical snapshot testing plugin for pytest.
<img align="right" width="50%" src="https://raw.githubusercontent.com/vberlier/pytest-insta/main/demo.svg?sanitize=true">
```python
assert snapshot() == "awesome!"
```
## Introduction
Snapshot testing makes it easy to monitor and approve changes by comparing the result of an operation against a previous reference value.
This project borrows from a lot of other implementations to provide a pythonic, batteries included snapshot testing solution. It also tries to feel as native to [`pytest`](https://docs.pytest.org/en/stable/) as possible with its integrated review tool.
### Features
- Expressive and familiar assertion syntax
- Can format text, binary, hexdump, json and pickle snapshots out-of-the-box
- Can be extended with custom snapshot formats
- Interactive review tool for inspecting and approving changes
### Credits
- [`insta`](https://github.com/mitsuhiko/insta) (rust)
Armin's work was the initial motivation for this project and inspired the reviewing workflow.
- [`jest`](https://jestjs.io/docs/en/snapshot-testing) (javascript)
Jest enabled the mass adoption of snapshot testing throughout the JavaScript ecosystem and now basically stands as the reference when it comes to what snapshot testing is supposed to look like.
## Installation
The package can be installed with `pip`.
```bash
$ pip install pytest-insta
```
## Getting Started
The `snapshot` fixture is a function that returns the current value of a snapshot.
```python
def test_hello_world(snapshot):
assert snapshot() == "hello"
```
```bash
$ pytest
...
CREATE snapshots/<prefix>__hello_world__0.txt
```
Running this test will create a new text file in the `snapshots` directory. The next time pytest runs, the test will load the snapshot and compare it to the actual value.
The return value of the `snapshot` function can be assigned to a variable and used multiple times.
```python
def test_hello_world(snapshot):
expected = snapshot()
assert expected == "hello"
assert expected.upper() == "HELLO"
```
By default, each invocation of the `snapshot` function will generate its own snapshot.
```python
def test_hello_world(snapshot):
assert snapshot() == "hello"
assert snapshot() == "world"
```
```bash
$ pytest
...
CREATE snapshots/<prefix>__hello_world__0.txt
CREATE snapshots/<prefix>__hello_world__1.txt
```
You can also name snapshots explicitly. This makes it possible to load a snapshot multiple times during the same test.
```python
def test_hello_world(snapshot):
assert snapshot("message.txt") == "hello"
assert snapshot("message.txt") == "hello"
```
```bash
$ pytest
...
CREATE snapshots/<prefix>__hello_world__message.txt
```
## Snapshot Formats
By default, the `snapshot` fixture will store snapshots as `.txt` files. By providing a filename or just a specific file extension, you can create snapshots using various formats supported out-of-the-box.
```python
def test_hello_world(snapshot):
assert snapshot("json") == {"hello": "world"}
assert snapshot("expected.json") == {"hello": "world"}
```
```bash
$ pytest
...
CREATE snapshots/<prefix>__hello_world__0.json
CREATE snapshots/<prefix>__hello_world__expected.json
```
Note that the plugin doesn't diff the snapshot files themselves but actually loads snapshots back into the interpreter and performs comparisons on live python objects. This makes it possible to use snapshot formats that aren't directly human-readable like pure binary files and pickle.
| Built-in Formats | Extension | Supported Types |
| ---------------- | ---------- | -------------------------------------------- |
| Plain text | `.txt` | `str` |
| Binary | `.bin` | `bytes` |
| Hexdump | `.hexdump` | `bytes` |
| Json | `.json` | Any object serializable by the json module |
| Pickle | `.pickle` | Any object serializable by the pickle module |
The built-in formats should get you covered most of the time but you can also really easily implement your own snapshot formats.
```python
from dataclasses import dataclass
from pathlib import Path
from pytest_insta import Fmt
@dataclass
class Point:
x: int
y: int
class FmtPoint(Fmt[Point]):
extension = ".pt"
def load(self, path: Path) -> Point:
return Point(*map(int, path.read_text().split()))
def dump(self, path: Path, value: Point):
path.write_text(f"{value.x} {value.y}")
def test_hello_world(snapshot):
assert snapshot("pt") == Point(4, 2)
```
You can create a custom formatter by inheriting from the `Fmt` class and defining custom `load` and `dump` methods. The `extension` attribute associates the custom formatter to the specified file extension.
Custom formatters can be defined anywhere in your test suite but it's recommended to keep them in `conftest.py` if they're meant to be used across multiple files.
## Command-line Options
The plugin extends the `pytest` cli with a new `--insta` option that accommodates the snapshot-testing workflow. The option can be set to one of the following strategies:
- `update` - Record and update differing snapshots
- `update-new` - Record and create snapshots that don't already exist
- `update-none` - Don't record or update anything
- `record` - Record and save differing snapshots to be reviewed later
- `review` - Record and save differing snapshots then bring up the review tool
- `review-only` - Don't run tests and only bring up the review tool
- `clear` - Don't run tests and clear all the snapshots to review
If the option is not specified, the strategy will default to `update-none` if `pytest` is running in a CI environment and `update-new` otherwise. This makes sure that your pipeline properly catches any snapshot you might forget to push while keeping the development experience seamless by automatically creating snapshots as you're writing tests.
The `record` option is useful if you're in the middle of something and your snapshots keep changing. Differing snapshots won't cause tests to fail and will instead be recorded and saved.
```bash
$ pytest --insta record
...
RECORD .pytest_cache/d/insta/<prefix>__hello_world__0.txt
NOTICE 1 snapshot to review
```
When you're done making changes you can use the `review` option to bring up the review tool after running your tests. Each differing snapshot will display a diff and let you inspect the new value and the old value in a python repl.
```bash
$ pytest --insta review
...
_____________________________ [1/1] _____________________________
old: snapshots/example_hello_world__0.txt
new: .pytest_cache/d/insta/example_hello_world__0.txt
> assert old == new
E assert 'hello' == 'world'
E - world
E + hello
test_example.py:1: test_hello_world
a: accept, r: reject, s: skip
>>>
```
Finally, the `update` option will let you update any differing snapshot according to the current test run, without going through the review tool.
```bash
$ pytest --insta update
...
UPDATE snapshots/<prefix>__hello_world__0.txt
```
It's worth mentioning that the updating, recording and reviewing strategies take into account any filter you might specify with the `-k` or `-m` options.
## Caveats
The `snapshot` fixture hijacks equality checks to record changes. This keeps assertions expressive and readable but introduces two caveats that you need to be aware of.
- **Right-sided snapshots ❌**
If an object's `__eq__` method doesn't return `NotImplemented` when its type doesn't match the compared object, the snapshot won't be able to record the updated value if it's placed on the right side of the comparison.
<details>
<summary>
Explanation
</summary>
***
Strings return `NotImplemented` when compared to non-string objects so the following test will behave as expected.
```python
def test_bad(snapshot):
assert "hello" == snapshot() # This works
```
However, dataclasses return `False` when compared to objects of different types and won't let the snapshot record any changes when placed on the left-side of the comparison.
```python
from dataclasses import dataclass
from pathlib import Path
from pytest_insta import Fmt
@dataclass
class Point:
x: int
y: int
class FmtPoint(Fmt[Point]):
extension = ".pt"
def load(self, path: Path) -> Point:
return Point(*map(int, path.read_text().split()))
def dump(self, path: Path, value: Point):
path.write_text(f"{value.x} {value.y}")
def test_bad(snapshot):
assert Point(4, 2) == snapshot("pt") # This doesn't work
```
</details>
**Recommendation ✅**
To avoid confusion and keep things consistent, always put snapshots on the left-side of the comparison.
```python
def test_good(snapshot):
assert snapshot() == "hello"
```
```python
def test_good(snapshot):
assert snapshot("pt") == Point(4, 2)
```
- **Not comparing snapshots ❌**
Snapshots should first be compared to their actual value before being used in other expressions and assertions.
<details>
<summary>
Explanation
</summary>
***
The comparison records the current value if the snapshot doesn't exist yet. In the following example, the test will fail before the actual comparison and the snapshot will not be generated.
```python
def test_bad(snapshot):
expected = snapshot()
assert expected.upper() == "HELLO" # This doesn't work
assert expected == "hello"
```
```bash
$ pytest
...
> assert expected.upper() == "HELLO"
E AttributeError: 'SnapshotNotfound' object has no attribute 'upper'
```
</details>
**Recommendation ✅**
Always compare the snapshot to its actual value first and only perform additional operations afterwards.
```python
def test_good(snapshot):
expected = snapshot()
assert expected == "hello"
assert expected.upper() == "HELLO"
```
## Contributing
Contributions are welcome. Make sure to first open an issue discussing the problem or the new feature before creating a pull request. The project uses [`poetry`](https://python-poetry.org).
```bash
$ poetry install
```
You can run the tests with `poetry run pytest`.
```bash
$ poetry run pytest
```
The project must type-check with [`pyright`](https://github.com/microsoft/pyright). If you're using VSCode the [`pylance`](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) extension should report diagnostics automatically. You can also install the type-checker locally with `npm install` and run it from the command-line.
```bash
$ npm run watch
$ npm run check
```
The code follows the [`black`](https://github.com/psf/black) code style. Import statements are sorted with [`isort`](https://pycqa.github.io/isort/).
```bash
$ poetry run isort pytest_insta tests
$ poetry run black pytest_insta tests
$ poetry run black --check pytest_insta tests
```
---
License - [MIT](https://github.com/vberlier/pytest-insta/blob/master/LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/vberlier/pytest-insta",
"name": "pytest-insta",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "pytest-plugin,pytest,testing,snapshot,snapshot-testing",
"author": "Valentin Berlier",
"author_email": "berlier.v@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d0/5b/6ca4baca60c3f8361415501668cde3abd94dbad44293325833fd89d1a7c1/pytest_insta-0.3.0.tar.gz",
"platform": null,
"description": "# pytest-insta\n\n\n[](https://pypi.org/project/pytest-insta/)\n[](https://pypi.org/project/pytest-insta/)\n[](https://github.com/ambv/black)\n\n> A practical snapshot testing plugin for pytest.\n\n<img align=\"right\" width=\"50%\" src=\"https://raw.githubusercontent.com/vberlier/pytest-insta/main/demo.svg?sanitize=true\">\n\n```python\nassert snapshot() == \"awesome!\"\n```\n\n## Introduction\n\nSnapshot testing makes it easy to monitor and approve changes by comparing the result of an operation against a previous reference value.\n\nThis project borrows from a lot of other implementations to provide a pythonic, batteries included snapshot testing solution. It also tries to feel as native to [`pytest`](https://docs.pytest.org/en/stable/) as possible with its integrated review tool.\n\n### Features\n\n- Expressive and familiar assertion syntax\n- Can format text, binary, hexdump, json and pickle snapshots out-of-the-box\n- Can be extended with custom snapshot formats\n- Interactive review tool for inspecting and approving changes\n\n### Credits\n\n- [`insta`](https://github.com/mitsuhiko/insta) (rust)\n\n Armin's work was the initial motivation for this project and inspired the reviewing workflow.\n\n- [`jest`](https://jestjs.io/docs/en/snapshot-testing) (javascript)\n\n Jest enabled the mass adoption of snapshot testing throughout the JavaScript ecosystem and now basically stands as the reference when it comes to what snapshot testing is supposed to look like.\n\n## Installation\n\nThe package can be installed with `pip`.\n\n```bash\n$ pip install pytest-insta\n```\n\n## Getting Started\n\nThe `snapshot` fixture is a function that returns the current value of a snapshot.\n\n```python\ndef test_hello_world(snapshot):\n assert snapshot() == \"hello\"\n```\n\n```bash\n$ pytest\n...\nCREATE snapshots/<prefix>__hello_world__0.txt\n```\n\nRunning this test will create a new text file in the `snapshots` directory. The next time pytest runs, the test will load the snapshot and compare it to the actual value.\n\nThe return value of the `snapshot` function can be assigned to a variable and used multiple times.\n\n```python\ndef test_hello_world(snapshot):\n expected = snapshot()\n assert expected == \"hello\"\n assert expected.upper() == \"HELLO\"\n```\n\nBy default, each invocation of the `snapshot` function will generate its own snapshot.\n\n```python\ndef test_hello_world(snapshot):\n assert snapshot() == \"hello\"\n assert snapshot() == \"world\"\n```\n\n```bash\n$ pytest\n...\nCREATE snapshots/<prefix>__hello_world__0.txt\nCREATE snapshots/<prefix>__hello_world__1.txt\n```\n\nYou can also name snapshots explicitly. This makes it possible to load a snapshot multiple times during the same test.\n\n```python\ndef test_hello_world(snapshot):\n assert snapshot(\"message.txt\") == \"hello\"\n assert snapshot(\"message.txt\") == \"hello\"\n```\n\n```bash\n$ pytest\n...\nCREATE snapshots/<prefix>__hello_world__message.txt\n```\n\n## Snapshot Formats\n\nBy default, the `snapshot` fixture will store snapshots as `.txt` files. By providing a filename or just a specific file extension, you can create snapshots using various formats supported out-of-the-box.\n\n```python\ndef test_hello_world(snapshot):\n assert snapshot(\"json\") == {\"hello\": \"world\"}\n assert snapshot(\"expected.json\") == {\"hello\": \"world\"}\n```\n\n```bash\n$ pytest\n...\nCREATE snapshots/<prefix>__hello_world__0.json\nCREATE snapshots/<prefix>__hello_world__expected.json\n```\n\nNote that the plugin doesn't diff the snapshot files themselves but actually loads snapshots back into the interpreter and performs comparisons on live python objects. This makes it possible to use snapshot formats that aren't directly human-readable like pure binary files and pickle.\n\n| Built-in Formats | Extension | Supported Types |\n| ---------------- | ---------- | -------------------------------------------- |\n| Plain text | `.txt` | `str` |\n| Binary | `.bin` | `bytes` |\n| Hexdump | `.hexdump` | `bytes` |\n| Json | `.json` | Any object serializable by the json module |\n| Pickle | `.pickle` | Any object serializable by the pickle module |\n\nThe built-in formats should get you covered most of the time but you can also really easily implement your own snapshot formats.\n\n```python\nfrom dataclasses import dataclass\nfrom pathlib import Path\n\nfrom pytest_insta import Fmt\n\n@dataclass\nclass Point:\n x: int\n y: int\n\nclass FmtPoint(Fmt[Point]):\n extension = \".pt\"\n\n def load(self, path: Path) -> Point:\n return Point(*map(int, path.read_text().split()))\n\n def dump(self, path: Path, value: Point):\n path.write_text(f\"{value.x} {value.y}\")\n\ndef test_hello_world(snapshot):\n assert snapshot(\"pt\") == Point(4, 2)\n```\n\nYou can create a custom formatter by inheriting from the `Fmt` class and defining custom `load` and `dump` methods. The `extension` attribute associates the custom formatter to the specified file extension.\n\nCustom formatters can be defined anywhere in your test suite but it's recommended to keep them in `conftest.py` if they're meant to be used across multiple files.\n\n## Command-line Options\n\nThe plugin extends the `pytest` cli with a new `--insta` option that accommodates the snapshot-testing workflow. The option can be set to one of the following strategies:\n\n- `update` - Record and update differing snapshots\n- `update-new` - Record and create snapshots that don't already exist\n- `update-none` - Don't record or update anything\n- `record` - Record and save differing snapshots to be reviewed later\n- `review` - Record and save differing snapshots then bring up the review tool\n- `review-only` - Don't run tests and only bring up the review tool\n- `clear` - Don't run tests and clear all the snapshots to review\n\nIf the option is not specified, the strategy will default to `update-none` if `pytest` is running in a CI environment and `update-new` otherwise. This makes sure that your pipeline properly catches any snapshot you might forget to push while keeping the development experience seamless by automatically creating snapshots as you're writing tests.\n\nThe `record` option is useful if you're in the middle of something and your snapshots keep changing. Differing snapshots won't cause tests to fail and will instead be recorded and saved.\n\n```bash\n$ pytest --insta record\n...\nRECORD .pytest_cache/d/insta/<prefix>__hello_world__0.txt\n\nNOTICE 1 snapshot to review\n```\n\nWhen you're done making changes you can use the `review` option to bring up the review tool after running your tests. Each differing snapshot will display a diff and let you inspect the new value and the old value in a python repl.\n\n```bash\n$ pytest --insta review\n...\n_____________________________ [1/1] _____________________________\n\nold: snapshots/example_hello_world__0.txt\nnew: .pytest_cache/d/insta/example_hello_world__0.txt\n\n> assert old == new\nE assert 'hello' == 'world'\nE - world\nE + hello\n\ntest_example.py:1: test_hello_world\n\na: accept, r: reject, s: skip\n>>>\n```\n\nFinally, the `update` option will let you update any differing snapshot according to the current test run, without going through the review tool.\n\n```bash\n$ pytest --insta update\n...\nUPDATE snapshots/<prefix>__hello_world__0.txt\n```\n\nIt's worth mentioning that the updating, recording and reviewing strategies take into account any filter you might specify with the `-k` or `-m` options.\n\n## Caveats\n\nThe `snapshot` fixture hijacks equality checks to record changes. This keeps assertions expressive and readable but introduces two caveats that you need to be aware of.\n\n- **Right-sided snapshots \u274c**\n\n If an object's `__eq__` method doesn't return `NotImplemented` when its type doesn't match the compared object, the snapshot won't be able to record the updated value if it's placed on the right side of the comparison.\n\n <details>\n <summary>\n Explanation\n </summary>\n\n ***\n\n Strings return `NotImplemented` when compared to non-string objects so the following test will behave as expected.\n\n ```python\n def test_bad(snapshot):\n assert \"hello\" == snapshot() # This works\n ```\n\n However, dataclasses return `False` when compared to objects of different types and won't let the snapshot record any changes when placed on the left-side of the comparison.\n\n ```python\n from dataclasses import dataclass\n from pathlib import Path\n\n from pytest_insta import Fmt\n\n @dataclass\n class Point:\n x: int\n y: int\n\n class FmtPoint(Fmt[Point]):\n extension = \".pt\"\n\n def load(self, path: Path) -> Point:\n return Point(*map(int, path.read_text().split()))\n\n def dump(self, path: Path, value: Point):\n path.write_text(f\"{value.x} {value.y}\")\n\n def test_bad(snapshot):\n assert Point(4, 2) == snapshot(\"pt\") # This doesn't work\n ```\n\n </details>\n\n **Recommendation \u2705**\n\n To avoid confusion and keep things consistent, always put snapshots on the left-side of the comparison.\n\n ```python\n def test_good(snapshot):\n assert snapshot() == \"hello\"\n ```\n\n ```python\n def test_good(snapshot):\n assert snapshot(\"pt\") == Point(4, 2)\n ```\n\n- **Not comparing snapshots \u274c**\n\n Snapshots should first be compared to their actual value before being used in other expressions and assertions.\n\n <details>\n <summary>\n Explanation\n </summary>\n\n ***\n\n The comparison records the current value if the snapshot doesn't exist yet. In the following example, the test will fail before the actual comparison and the snapshot will not be generated.\n\n ```python\n def test_bad(snapshot):\n expected = snapshot()\n assert expected.upper() == \"HELLO\" # This doesn't work\n assert expected == \"hello\"\n ```\n\n ```bash\n $ pytest\n ...\n > assert expected.upper() == \"HELLO\"\n E AttributeError: 'SnapshotNotfound' object has no attribute 'upper'\n ```\n\n </details>\n\n **Recommendation \u2705**\n\n Always compare the snapshot to its actual value first and only perform additional operations afterwards.\n\n ```python\n def test_good(snapshot):\n expected = snapshot()\n assert expected == \"hello\"\n assert expected.upper() == \"HELLO\"\n ```\n\n## Contributing\n\nContributions are welcome. Make sure to first open an issue discussing the problem or the new feature before creating a pull request. The project uses [`poetry`](https://python-poetry.org).\n\n```bash\n$ poetry install\n```\n\nYou can run the tests with `poetry run pytest`.\n\n```bash\n$ poetry run pytest\n```\n\nThe project must type-check with [`pyright`](https://github.com/microsoft/pyright). If you're using VSCode the [`pylance`](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) extension should report diagnostics automatically. You can also install the type-checker locally with `npm install` and run it from the command-line.\n\n```bash\n$ npm run watch\n$ npm run check\n```\n\nThe code follows the [`black`](https://github.com/psf/black) code style. Import statements are sorted with [`isort`](https://pycqa.github.io/isort/).\n\n```bash\n$ poetry run isort pytest_insta tests\n$ poetry run black pytest_insta tests\n$ poetry run black --check pytest_insta tests\n```\n\n---\n\nLicense - [MIT](https://github.com/vberlier/pytest-insta/blob/master/LICENSE)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A practical snapshot testing plugin for pytest",
"version": "0.3.0",
"project_urls": {
"Documentation": "https://github.com/vberlier/pytest-insta",
"Homepage": "https://github.com/vberlier/pytest-insta",
"Repository": "https://github.com/vberlier/pytest-insta"
},
"split_keywords": [
"pytest-plugin",
"pytest",
"testing",
"snapshot",
"snapshot-testing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cbd51459b2861cf703cf49d96b6f29731ee74f4ac7e34b0c60b0ff75bdd318bc",
"md5": "b938c632111a370a415024514412e18d",
"sha256": "93a105e3850f2887b120a581923b10bb313d722e00d369377a1d91aa535df704"
},
"downloads": -1,
"filename": "pytest_insta-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b938c632111a370a415024514412e18d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 13660,
"upload_time": "2024-02-19T23:00:20",
"upload_time_iso_8601": "2024-02-19T23:00:20.054275Z",
"url": "https://files.pythonhosted.org/packages/cb/d5/1459b2861cf703cf49d96b6f29731ee74f4ac7e34b0c60b0ff75bdd318bc/pytest_insta-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d05b6ca4baca60c3f8361415501668cde3abd94dbad44293325833fd89d1a7c1",
"md5": "89bf51c90364ea66ca6255675c434584",
"sha256": "9e6e1c70a021f68ccc4643360b2c2f8326cf3befba85f942c1da17b9caf713f7"
},
"downloads": -1,
"filename": "pytest_insta-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "89bf51c90364ea66ca6255675c434584",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 14960,
"upload_time": "2024-02-19T23:00:22",
"upload_time_iso_8601": "2024-02-19T23:00:22.014585Z",
"url": "https://files.pythonhosted.org/packages/d0/5b/6ca4baca60c3f8361415501668cde3abd94dbad44293325833fd89d1a7c1/pytest_insta-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-19 23:00:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vberlier",
"github_project": "pytest-insta",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pytest-insta"
}
JSON
