Skip to main content

A plugin for snapshot testing with pytest.

Project description

PyPI version Python versions CI Status Coverage

A plugin for snapshot testing with pytest.

This library was inspired by jest’s snapshot testing. Snapshot testing can be used to test that the value of an expression does not change unexpectedly. The added benefits of snapshot testing are that

  • They are easy to create.

  • They are easy to update when the expected value of a test changes.

Instead of manually updating tests when the expected value of an expression changes, the developer simply needs to

  1. run pytest --snapshot-update to update the snapshot tests

  2. verify that the snapshot files contain the new expected results

  3. commit the snapshot changes to version control

Features

  • snapshot testing of strings and bytes

  • snapshot testing of (optionally nested) collections of strings and bytes

  • complete control of the snapshot file path and content

Requirements

Installation

You can install “pytest-snapshot” via pip from PyPI:

$ pip install pytest-snapshot

Usage

assert_match

A classic equality test looks like:

def test_function_output():
    assert foo('function input') == 'expected result'

It could be re-written using snapshot testing as:

def test_function_output_with_snapshot(snapshot):
    snapshot.snapshot_dir = 'snapshots'  # This line is optional.
    snapshot.assert_match(foo('function input'), 'foo_output.txt')

The author of the test should then

  1. run pytest --snapshot-update to generate the snapshot file snapshots/foo_output.txt containing the output of foo().

  2. verify that the content of the snapshot file is valid.

  3. commit it to version control.

Now, whenever the test is run, it will assert that the output of foo() is equal to the snapshot.

What if the behaviour of foo() changes and the test starts to fail?

In the first example, the developer would need to manually update the expected result in test_function_output. This could be tedious if the expected result is large or there are many tests.

In the second example, the developer would simply

  1. run pytest --snapshot-update

  2. verify that the snapshot file contains the new expected result

  3. commit it to version control.

Snapshot testing can be used for expressions whose values are strings or bytes. For other types, you should first create a human readable representation of the value. For example, to snapshot test a json-serializable value, you could either convert it into json or preferably convert it into the more readable yaml format using PyYAML:

snapshot.assert_match(yaml.dump(foo()), 'foo_output.yml')

assert_match_dir

When snapshot testing a collection of values, assert_match_dir comes in handy. It will save a snapshot of a collection of values as a directory of snapshot files. assert_match_dir takes a dictionary from file name to value. Dictionaries can also be nested to create nested directories containing snapshot files.

For example, the following code creates the directory snapshots/people containing files john.json and jane.json.

def test_something(snapshot):
    snapshot.snapshot_dir = 'snapshots'
    snapshot.assert_match_dir({
        'john.json': '{"first name": "John", "last name": "Doe"}',
        'jane.json': '{"first name": "Jane", "last name": "Doe"}',
    }, 'people')

When running pytest --snapshot-update, snapshot files will be added, updated, or deleted as necessary. As a safety measure, snapshots will only be deleted when using the --allow-snapshot-deletion flag.

Common use case

A quick way to create snapshot tests is to create a directory containing many test case directories. In each test case, add files containing the inputs to the function you wish to test. For example:

test_cases
    case1
        input.json
    case2
        input.json
    ...

Next, add a test that is parametrized on all test case directories. The test should

  • read input from the test case directory

  • call the function to be tested

  • snapshot the result to the test case directory

import json
import os

import pytest
import yaml
from pathlib import Path


def json_to_yaml(json_string):
    obj = json.loads(json_string)
    return yaml.dump(obj, indent=2)


@pytest.mark.parametrize('case_dir', list(Path('test_cases').iterdir()))
def test_json(case_dir, snapshot):
    # Read input files from the case directory.
    input_json = case_dir.joinpath('input.json').read_text()

    # Call the tested function.
    output_yaml = json_to_yaml(input_json)

    # Snapshot the return value.
    snapshot.snapshot_dir = case_dir
    snapshot.assert_match(output_yaml, 'output.yml')

Now, we can run pytest --snapshot-update to create an output.yml snapshot for each test case. If we later decide to modify the tested function’s behaviour, we can fix the test cases with another pytest --snapshot-update.

Similar Packages

Another python package that can be used for snapshot testing is snapshottest. While this package and snapshottest fulfill the same role, there are some differences.

With pytest-snapshot:

  • Every snapshot is saved to a separate file.

  • The paths to snapshot files are fully customizable.

  • The serialization of objects to snapshots is fully customizable (the library does not serialize).

This allows the user to organize snapshots in the most human-readable and logical place in their code repository. This is highly beneficial since snapshots will be viewed by users many times during development and code reviews.

Contributing

Contributions are very welcome. Before contributing, please discuss the change with me. I wish to keep this plugin flexible and not enforce any project layout on the user.

Tests can be run with tox or python -m pytest. Note that the test suite does not pass when run with --assert=plain.

License

Distributed under the terms of the MIT license, “pytest-snapshot” is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pytest-snapshot-with-message-generator-0.0.1.tar.gz (17.5 kB view details)

Uploaded Source

Built Distribution

File details

Details for the file pytest-snapshot-with-message-generator-0.0.1.tar.gz.

File metadata

File hashes

Hashes for pytest-snapshot-with-message-generator-0.0.1.tar.gz
Algorithm Hash digest
SHA256 063837cdadffa8709e8155da32437de130d46f6919112170d837551876d1aaf3
MD5 f462d2486433f3b756e9c3f2d072767a
BLAKE2b-256 bfe9345402d9155629daa4591e6f7031022f7399933870dbf50a8a1795f6f5d6

See more details on using hashes here.

File details

Details for the file pytest_snapshot_with_message_generator-0.0.1-py3-none-any.whl.

File metadata

File hashes

Hashes for pytest_snapshot_with_message_generator-0.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 2ad7a8b7b3d53a9f3cb82d560d8b443b51e2d35058dd63439e8b2055e890aa64
MD5 c3ee531d54d3574be912643ef39c969a
BLAKE2b-256 ce322b79341b067ae04454c8736ab04137eadd74cdd00429d73b732ac72aca49

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page