Metadata-Version: 2.1
Name: pytest-image-snapshot
Version: 0.2.2
Summary: A pytest plugin for image snapshot management and comparison.
Home-page: https://github.com/bmihelac/pytest-image-snapshot
Author: Bojan Mihelac
Author-email: bojan@informatikamihelac.com
Maintainer: Bojan Mihelac
Maintainer-email: bojan@informatikamihelac.com
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Testing
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.5
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pytest>=3.5.0
Requires-Dist: Pillow
Provides-Extra: pixelmatch
Requires-Dist: pixelmatch>=0.3.0; extra == "pixelmatch"

# pytest-image-snapshot

[![PyPI version](https://img.shields.io/pypi/v/pytest-image-snapshot.svg)](https://pypi.org/project/pytest-image-snapshot)

[![Python versions](https://img.shields.io/pypi/pyversions/pytest-image-snapshot.svg)](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.

### 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
```

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

