README

A simple approval test library utilizing external diff programs such as PyCharm and Visual Studio Code to compare approved and received output.

About

Approval tests capture the output (a snapshot) of a piece of code and compare it with a previously approved version of the output.

It's most useful in environments where frequent changes are expected or where the output is of a complex nature but can be easily verified by humans, aided for example by a diff-tool or a visual representation of the output.

Once the output has been approved then as long as the output stays the same the test will pass. A test fails if the received output is not identical to the approved version. In that case, the difference between the received and the approved output is reported to the tester.

For outputs that can be represented by text, a report can be as simple as printing the difference to the terminal. Using diff programs with a graphical user interface such as PyCharm or Visual Studio Coder as reporter not only helps to visualize the difference, but they can also be used as approver by applying the changes of the received output to the approved output.

Not all data can or should be represented by text. In many cases an image is the best and most easily verifiable representation. PyCharm and Visual Studio Code can work with images as well.

A picture’s worth a 1000 tests (approvaltests.com).

Requirements

OS

• Linux/Unix
• MacOS

One of following programs installed:

• PyCharm
• Visual Studio Code
• Meld
• GNU Diffutils (diff)

Installation

uv add git+https://github.com/GIScience/asyncpg-recorder.git

Usage

Verify text:

from pytest_approval import verify, verify_json


def test_verify_string()
    assert verify("Hello World!")


def test_verify_dict()
    # automatic conversion to JSON
    assert verify_json({"msg": "Hello World!"})

Verify binary files such as an image:

from pytest_approval import  verify_binary


def test_verify_binary(image):
    with open("my_image.jpg", "rb") as file:
        buffer = file.read()
    assert verify_binary(buffer, extension=".jpg")

Auto approval

It is possible to run auto approve every approval tests:

uv run pytest --auto-approve

This is useful for elimination of approval files which are not in use anymore.

1. Make sure tests are green.
2. Then remove all approval files.
3. Run pytest in auto approval mode.

Configuration

Approved and received files are stored next to the test file per default. If you want to save those files in a specific directory instead, please set the approvals-dir key in your pyproject.toml:

[tool.pytest-approval]
"approved-dir"="tests/approvals"  

This path is relative to your pytest root (usually your pyproject.toml).

Development

uv sync --all-extras
uv run pytest

Release

This project uses CalVer.

Format is: YYYY.MM.DD (E.g 2025.9.2).

In case of releasing twice on one day add a micro number starting with 1: YYYY.MM.DD.micro (E.g. 2025.9.2.1).

To make a new release run ./scripts/release.sh YYYY.MM.DD

Alternatives

Syrupy is a zero-dependency pytest snapshot plugin. It enables developers to write tests which assert immutability of computed results.

Approvaltests is an open source assertion/verification library to aid testing.