API

pytest-regtest public API

pytest_regtest.RegtestStream

Fixture for recording textual output in regression tests.

The regtest fixture provides an instance of this class. It behaves like a file handle that can be used to record output for comparison.

ATTRIBUTE	DESCRIPTION
`version`	An optional identifier to distinguish multiple recorded outputs within the same test function.
`identifier`	Alias for `version`.

pytest_regtest.Snapshot.check

check(
    obj: Any,
    *,
    failure_handler: Optional[
        Callable[[Any, Any], None]
    ] = None,
    version: Optional[Union[str, int]] = None,
    **options: Any,
) -> None

Record and check a snapshot of the given object.

PARAMETER	DESCRIPTION
`obj`	The object to record. TYPE: `Any`
`failure_handler`	A callback function that is called when the check fails. The function receives the current and the recorded object as arguments. TYPE: `Optional[Callable[[Any, Any], None]]` DEFAULT: `None`
`version`	An optional identifier to distinguish multiple snapshots within the same test function. TYPE: `Optional[Union[str, int]]` DEFAULT: `None`
`**options`	Additional options passed to the snapshot handler. Supported options depend on the handler (e.g., `atol`, `rtol`, `compact`). For Python objects, pass `format="json"` to store the snapshot as a human-readable JSON file instead of binary pickle — JSON files are easy to inspect and produce meaningful diffs in code review. TYPE: `Any` DEFAULT: `{}`

pytest_regtest.register_converter_post

register_converter_post(
    function: Callable[
        [str, Optional[FixtureRequest]], None
    ],
) -> None

Registers a new conversion function at the head of the list of existing converters

PARAMETER	DESCRIPTION
`function`	Function to cleanup given string and remove data which can change between test runs without affecting the correctness of the test. The second argument is optional and is a `pytest` object which holds information about the current `config` or the current test function. This argument can be ignored in many situations. TYPE: `Callable[[str, Optional[FixtureRequest]], None]`

pytest_regtest.register_converter_pre

register_converter_pre(
    function: Callable[
        [str, Optional[FixtureRequest]], None
    ],
) -> None

Registers a new conversion function at the head of the list of existing converters.

PARAMETER	DESCRIPTION
`function`	Function to cleanup given string and remove data which can change between test runs without affecting the correctness of the test. The second argument is optional and is a `pytest` object which holds information about the current `config` or the current test function. This argument can be ignored in many situations. TYPE: `Callable[[str, Optional[FixtureRequest]], None]`

pytest_regtest.clear_converters

clear_converters() -> None

Unregisters all converters, including the builtin converters.

Snapshot handler API

pytest_regtest.snapshot_handler.SnapshotHandlerRegistry

This class serves as a registry for the builtin snapshot handlers and can be used to add more handlers for particular data types.

add_handler `classmethod`

add_handler(
    clz,
    check_function: Callable[[Any], bool],
    handler_class: type[BaseSnapshotHandler],
)

Add a handler.

PARAMETER	DESCRIPTION
`check_function`	A function which takes an object and returns `True` if the `handler_class` argument should be used for the given object. TYPE: `Callable[[Any], bool]`

get_handler `classmethod`

get_handler(clz, obj: Any) -> BaseSnapshotHandler

Find and initialize handler for the given object.

PARAMETER	DESCRIPTION
`obj`	The object for which we try to find a handler. TYPE: `Any`

RETURNS	DESCRIPTION
`BaseSnapshotHandler`	An instance of the handler or `None` if no appropriate handler was found.

pytest_regtest.snapshot_handler.BaseSnapshotHandler

Bases: ABC

Abstract base class to implement snapshot handlers.

init `abstractmethod`

__init__(
    handler_options: dict[str, Any],
    pytest_config: type[Config],
    tw: int,
) -> None

This method is called within snapshot.check to configure the handler.

PARAMETER	DESCRIPTION
`handler_options`	Keyword arguments from `shapshot.check` call TYPE: `dict[str, Any]`
`pytest_config`	`pytest` config object. TYPE: `type[Config]`
`tw`	Terminal width. TYPE: `int`

compare `abstractmethod`

compare(current_obj: Any, recorded_obj: Any) -> bool

The method compares if the current object from the snapshot.check call and the object loaded with the load method are considered to be the same. If this returns True the snapshot.check call will pass.

PARAMETER	DESCRIPTION
`current_obj`	The object the snapshot handler receiving from `snapshot.check`. TYPE: `Any`
`recorded_obj`	The object the snapshot handler is loading with the `load` method. TYPE: `Any`

RETURNS	DESCRIPTION
`bool`	Boolean value which decides is the `snapshot.check` call will pass.

load `abstractmethod`

load(folder: Union[str, PathLike[Any]]) -> Any

This method loads an existing snapshot from the given folder and must be consistent with the save method.

PARAMETER	DESCRIPTION
`folder`	Path to the folder. The folder exists already when this method is called. TYPE: `Union[str, PathLike[Any]]`

RETURNS	DESCRIPTION
`Any`	The loaded object.

save `abstractmethod`

save(folder: Union[str, PathLike[Any]], obj: Any) -> None

This method is called when a snapshot is reset, and a subclass must store the given object in the given folder. How this folder is managed internally is entirely up to the snapshot handler. It can be a single file, or a complex structure of multiple files and sub-folders.

PARAMETER	DESCRIPTION
`folder`	Path to the folder. The folder exists already when this method is called. TYPE: `Union[str, PathLike[Any]]`
`obj`	The object from the `snapshot.check` call. TYPE: `Any`

show `abstractmethod`

show(obj: Any) -> list[str]

This method returns a line wise textual representation of the given object.

PARAMETER	DESCRIPTION
`obj`	The object the snapshot handler is managing. TYPE: `Any`

RETURNS	DESCRIPTION
`list[str]`	List of strings.

show_differences `abstractmethod`

show_differences(
    current_obj: Any,
    recorded_obj: Any,
    has_markup: bool,
    use_ddiff: bool,
) -> list[str]

The method shows differences between the object from the snapshot.check call and the object loaded with the load method.

PARAMETER	DESCRIPTION
`current_obj`	The object the snapshot handler receiving from `snapshot.check`. TYPE: `Any`
`recorded_obj`	The object the snapshot handler is loading with the `load` method. TYPE: `Any`
`has_markup`	Indicates if the tests run within a terminal and the method can use color output in case `has_markup` is `True`. TYPE: `bool`
`use_ddiff`	Use the ddiff library to print diffs, may not be supported by all handlers. TYPE: `bool`

RETURNS	DESCRIPTION
`list[str]`	List of strings to describe the differences.

API

pytest-regtest public API

pytest_regtest.RegtestStream

pytest_regtest.Snapshot.check

pytest_regtest.register_converter_post

pytest_regtest.register_converter_pre

pytest_regtest.clear_converters

Snapshot handler API

pytest_regtest.snapshot_handler.SnapshotHandlerRegistry

add_handler classmethod

get_handler classmethod

pytest_regtest.snapshot_handler.BaseSnapshotHandler

__init__ abstractmethod

compare abstractmethod

load abstractmethod

save abstractmethod

show abstractmethod

show_differences abstractmethod