# pytest-image-snapshot
[](https://pypi.org/project/pytest-image-snapshot)
[](https://pypi.org/project/pytest-image-snapshot)
A pytest plugin for image snapshot management and comparison.
------------------------------------------------------------------------
## Features
- **Image Comparison**: Automatically compares a test-generated image with a pre-stored snapshot, identifying any visual discrepancies.
- **Snapshot Creation**: If a reference snapshot doesn't exist, the plugin will create it during the test run, making initial setup effortless.
- **Verbose Mode Display**: Capable of displaying the difference image for quick visual feedback in case of mismatches when running tests with `-v`.
- **Snapshot Update Option**: Includes a `--image-snapshot-update` flag to update existing snapshots or create new ones, accommodating visual changes in your project.
- **Threshold-Based Comparison**: Utilizes the `threshold` argument for enhanced image comparison with the `pixelmatch` library, enabling anti-aliasing pixel detection.
## Requirements
- Pillow
- pixelmatch (optional)
## Installation
You can install \"pytest-image-snapshot\" via pip from [PyPI](https://pypi.org/project/pytest-image-snapshot/):
$ pip install pytest-image-snapshot
### Optional Dependency
`pytest-image-snapshot` offers enhanced functionality with the optional [pixelmatch](https://github.com/whtsky/pixelmatch-py) package, suitable for advanced image comparison scenarios. To install `pytest-image-snapshot` along with this optional feature, use the following command:
```bash
$ pip install pytest-image-snapshot[pixelmatch]
```
## Pytest Image Snapshot Usage Example
The `image_snapshot` fixture is designed for visual regression testing in pytest. It compares a generated image in your tests with a stored reference image (snapshot). If the snapshot doesn't exist, it will be automatically created. This makes the fixture ideal for both creating initial snapshots and for ongoing comparison in visual tests.
### Usage
Here's a example of how to utilize the `image_snapshot` fixture:
```python
from PIL import Image
def test_image(image_snapshot):
# Create a new white image of 100x100 pixels
image = Image.new('RGB', (100, 100), 'white')
# Compare it to the snapshot stored in test_snapshots/test.png
# If test_snapshots/test.png does not exist, it will be created
image_snapshot(image, "test_snapshots/test.png")
```
### Optional `threshold` Argument in `image_snapshot`
The `image_snapshot` function includes an optional `threshold` argument. When set, and if the image does not match the snapshot, the `pixelmatch` library is used for a detailed comparison with anti-aliasing pixel detection.
- **Default Threshold:** If `threshold` is set to `True`, a default threshold value is utilized.
- **Custom Threshold:** If `threshold` is a numeric value, it is passed to the `pixelmatch` library to specify the tolerance level for image comparison.
```python
image_snapshot(image, "test_snapshots/test.png", True)
image_snapshot(image, "test_snapshots/test.png", 0.2)
```
> **⚠️ Warning:**
>
> The `image_snapshot` fixture does not automatically create directories for storing image snapshots. Ensure that the necessary directories (e.g., `test_snapshots/`) are created in your project structure before running tests.
### Verbose Mode (`-v` or `--verbose`)
The verbose mode enhances the output detail for `image_snapshot` tests:
- `-v`: Displays the 'diff' image when there's a mismatch.
- `-vv`: Shows all three images - 'diff', 'original', and 'current' for a comprehensive comparison.
This feature assists in quickly identifying and analyzing visual differences during test failures.
### Save actual image and diff image (`--image-snapshot-save-diff`)
Use the `--image-snapshot-save-diff` flag to save the actual image and the diff image when there's a mismatch. This is particularly useful for debugging in a CI environment.
```bash
pytest --image-snapshot-save-diff
```
### Updating Snapshots (`--image-snapshot-update`)
Use the `--image-snapshot-update` flag to update or create new reference snapshots. This is useful for incorporating intentional visual changes into your tests, ensuring that your snapshots always reflect the current expected state.
```bash
pytest --image-snapshot-update
```
### Failing when snapshots are missing (`--image-snapshot-fail-if-missing`)
Use the `--image-snapshot-fail-if-missing` flag to fail the test when the snapshot is missing. This is particularly useful in CI check to ensure that all snapshots are present and up-to-date.
```bash
pytest --image-snapshot-fail-if-missing
```
## Example
Visual regression test for [Django](https://www.djangoproject.com/) application home page with [playwright](https://playwright.dev/python/docs/intro):
```python
from PIL import Image
from io import BytesIO
def test_homepage(live_server, page: Page, image_snapshot):
page.goto(f"{live_server}")
# convert screenshot to image
screenshot = Image.open(BytesIO(page.screenshot()))
image_snapshot(screenshot, "test_snapshots/homepage.png", threshold=True)
```
## Contributing
Contributions are very welcome. Tests can be run with
[tox](https://tox.readthedocs.io/en/latest/), please ensure the coverage
at least stays the same before you submit a pull request.
## License
Distributed under the terms of the
[MIT](http://opensource.org/licenses/MIT) license,
\"pytest-image-snapshot\" is free and open source software
## Issues
If you encounter any problems, please [file an
issue](https://github.com/bmihelac/pytest-image-snapshot/issues) along
with a detailed description.
---
This [pytest](https://github.com/pytest-dev/pytest) plugin was generated
with [Cookiecutter](https://github.com/audreyr/cookiecutter) along with
[\@hackebrot](https://github.com/hackebrot)\'s
[cookiecutter-pytest-plugin](https://github.com/pytest-dev/cookiecutter-pytest-plugin)
template.
Raw data
{
"_id": null,
"home_page": "https://github.com/bmihelac/pytest-image-snapshot",
"name": "pytest-image-snapshot",
"maintainer": "Bojan Mihelac",
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": "bojan@informatikamihelac.com",
"keywords": null,
"author": "Bojan Mihelac",
"author_email": "bojan@informatikamihelac.com",
"download_url": "https://files.pythonhosted.org/packages/6b/af/168d4dc262dd34c61d75d68d4794b2a0e4c5df402e3f7c652b164f0efe51/pytest_image_snapshot-0.4.5.tar.gz",
"platform": null,
"description": "# pytest-image-snapshot\n\n[](https://pypi.org/project/pytest-image-snapshot)\n\n[](https://pypi.org/project/pytest-image-snapshot)\n\nA pytest plugin for image snapshot management and comparison.\n\n------------------------------------------------------------------------\n\n## Features\n\n- **Image Comparison**: Automatically compares a test-generated image with a pre-stored snapshot, identifying any visual discrepancies.\n- **Snapshot Creation**: If a reference snapshot doesn't exist, the plugin will create it during the test run, making initial setup effortless.\n- **Verbose Mode Display**: Capable of displaying the difference image for quick visual feedback in case of mismatches when running tests with `-v`.\n- **Snapshot Update Option**: Includes a `--image-snapshot-update` flag to update existing snapshots or create new ones, accommodating visual changes in your project.\n- **Threshold-Based Comparison**: Utilizes the `threshold` argument for enhanced image comparison with the `pixelmatch` library, enabling anti-aliasing pixel detection.\n\n\n## Requirements\n\n- Pillow\n- pixelmatch (optional)\n\n## Installation\n\nYou can install \\\"pytest-image-snapshot\\\" via pip from [PyPI](https://pypi.org/project/pytest-image-snapshot/):\n\n $ pip install pytest-image-snapshot\n\n### Optional Dependency\n\n`pytest-image-snapshot` offers enhanced functionality with the optional [pixelmatch](https://github.com/whtsky/pixelmatch-py) package, suitable for advanced image comparison scenarios. To install `pytest-image-snapshot` along with this optional feature, use the following command:\n\n```bash\n$ pip install pytest-image-snapshot[pixelmatch]\n```\n\n## Pytest Image Snapshot Usage Example\n\nThe `image_snapshot` fixture is designed for visual regression testing in pytest. It compares a generated image in your tests with a stored reference image (snapshot). If the snapshot doesn't exist, it will be automatically created. This makes the fixture ideal for both creating initial snapshots and for ongoing comparison in visual tests.\n\n### Usage\n\nHere's a example of how to utilize the `image_snapshot` fixture:\n\n```python\nfrom PIL import Image\n\ndef test_image(image_snapshot):\n # Create a new white image of 100x100 pixels\n image = Image.new('RGB', (100, 100), 'white')\n # Compare it to the snapshot stored in test_snapshots/test.png\n # If test_snapshots/test.png does not exist, it will be created\n image_snapshot(image, \"test_snapshots/test.png\")\n```\n\n### Optional `threshold` Argument in `image_snapshot`\n\nThe `image_snapshot` function includes an optional `threshold` argument. When set, and if the image does not match the snapshot, the `pixelmatch` library is used for a detailed comparison with anti-aliasing pixel detection.\n\n- **Default Threshold:** If `threshold` is set to `True`, a default threshold value is utilized.\n- **Custom Threshold:** If `threshold` is a numeric value, it is passed to the `pixelmatch` library to specify the tolerance level for image comparison.\n\n```python\nimage_snapshot(image, \"test_snapshots/test.png\", True)\nimage_snapshot(image, \"test_snapshots/test.png\", 0.2)\n```\n\n> **\u26a0\ufe0f Warning:**\n>\n> The `image_snapshot` fixture does not automatically create directories for storing image snapshots. Ensure that the necessary directories (e.g., `test_snapshots/`) are created in your project structure before running tests.\n\n### Verbose Mode (`-v` or `--verbose`)\n\nThe verbose mode enhances the output detail for `image_snapshot` tests:\n- `-v`: Displays the 'diff' image when there's a mismatch.\n- `-vv`: Shows all three images - 'diff', 'original', and 'current' for a comprehensive comparison.\n\nThis feature assists in quickly identifying and analyzing visual differences during test failures.\n\n### Save actual image and diff image (`--image-snapshot-save-diff`)\n\nUse the `--image-snapshot-save-diff` flag to save the actual image and the diff image when there's a mismatch. This is particularly useful for debugging in a CI environment.\n\n```bash\npytest --image-snapshot-save-diff\n```\n\n### Updating Snapshots (`--image-snapshot-update`)\n\nUse the `--image-snapshot-update` flag to update or create new reference snapshots. This is useful for incorporating intentional visual changes into your tests, ensuring that your snapshots always reflect the current expected state.\n\n```bash\npytest --image-snapshot-update\n```\n\n### Failing when snapshots are missing (`--image-snapshot-fail-if-missing`)\n\nUse the `--image-snapshot-fail-if-missing` flag to fail the test when the snapshot is missing. This is particularly useful in CI check to ensure that all snapshots are present and up-to-date.\n\n```bash\npytest --image-snapshot-fail-if-missing\n```\n\n## Example\n\nVisual regression test for [Django](https://www.djangoproject.com/) application home page with [playwright](https://playwright.dev/python/docs/intro):\n\n```python\nfrom PIL import Image\nfrom io import BytesIO\n\ndef test_homepage(live_server, page: Page, image_snapshot):\n page.goto(f\"{live_server}\")\n # convert screenshot to image\n screenshot = Image.open(BytesIO(page.screenshot()))\n image_snapshot(screenshot, \"test_snapshots/homepage.png\", threshold=True)\n```\n\n## Contributing\n\nContributions are very welcome. Tests can be run with\n[tox](https://tox.readthedocs.io/en/latest/), please ensure the coverage\nat least stays the same before you submit a pull request.\n\n## License\n\nDistributed under the terms of the\n[MIT](http://opensource.org/licenses/MIT) license,\n\\\"pytest-image-snapshot\\\" is free and open source software\n\n## Issues\n\nIf you encounter any problems, please [file an\nissue](https://github.com/bmihelac/pytest-image-snapshot/issues) along\nwith a detailed description.\n\n--- \n\nThis [pytest](https://github.com/pytest-dev/pytest) plugin was generated\nwith [Cookiecutter](https://github.com/audreyr/cookiecutter) along with\n[\\@hackebrot](https://github.com/hackebrot)\\'s\n[cookiecutter-pytest-plugin](https://github.com/pytest-dev/cookiecutter-pytest-plugin)\ntemplate.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A pytest plugin for image snapshot management and comparison.",
"version": "0.4.5",
"project_urls": {
"Homepage": "https://github.com/bmihelac/pytest-image-snapshot"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "afe7d3de93d95006f30f370a8b8fa41a85ab2a7e69b6cdaf5056d9715599b98d",
"md5": "0e8b3ebdd9196c137fd099b31b716e07",
"sha256": "cc544510d87ded7eba48de356601fa5b26ca97f5ee4b891c6c8fe4184cf1930d"
},
"downloads": -1,
"filename": "pytest_image_snapshot-0.4.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0e8b3ebdd9196c137fd099b31b716e07",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 6506,
"upload_time": "2025-07-16T09:59:54",
"upload_time_iso_8601": "2025-07-16T09:59:54.538837Z",
"url": "https://files.pythonhosted.org/packages/af/e7/d3de93d95006f30f370a8b8fa41a85ab2a7e69b6cdaf5056d9715599b98d/pytest_image_snapshot-0.4.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6baf168d4dc262dd34c61d75d68d4794b2a0e4c5df402e3f7c652b164f0efe51",
"md5": "a5f15b83c3eabae5986be2ad5df04232",
"sha256": "706f0ee3f8b7826beda93702a6c0a001ae783ee2cb273948f145f4e8560413d5"
},
"downloads": -1,
"filename": "pytest_image_snapshot-0.4.5.tar.gz",
"has_sig": false,
"md5_digest": "a5f15b83c3eabae5986be2ad5df04232",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 6744,
"upload_time": "2025-07-16T09:59:56",
"upload_time_iso_8601": "2025-07-16T09:59:56.105112Z",
"url": "https://files.pythonhosted.org/packages/6b/af/168d4dc262dd34c61d75d68d4794b2a0e4c5df402e3f7c652b164f0efe51/pytest_image_snapshot-0.4.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 09:59:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bmihelac",
"github_project": "pytest-image-snapshot",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pytest-image-snapshot"
}
JSON
