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,
    *,
    transform: Optional[Callable[[Any], Any]] = None,
    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`
`transform`	An optional function applied to `obj` before it is recorded and compared, e.g. to strip volatile fields (timestamps, uuids) from a dict. Runs after any transforms registered globally with `register_snapshot_transform`. TYPE: `Optional[Callable[[Any], Any]]` DEFAULT: `None`
`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.

pytest_regtest.register_snapshot_transform

register_snapshot_transform(
    check_function: Callable[[Any], bool],
    transform_function: Callable[[Any], Any],
) -> None

Registers a transform applied to every snapshotted object that matches check_function, before it is recorded and compared. Useful for cleaning up data which can change between test runs without affecting the correctness of the test, e.g. stripping timestamps or uuids from dicts, without having to write a full custom snapshot handler.

Multiple registered transforms are applied in registration order to every object for which check_function returns True.

PARAMETER	DESCRIPTION
`check_function`	A function which takes the snapshotted object and returns `True` if `transform_function` should be applied to it. TYPE: `Callable[[Any], bool]`
`transform_function`	A function which takes the snapshotted object and returns the cleaned-up object to record and compare instead. TYPE: `Callable[[Any], Any]`

pytest_regtest.clear_snapshot_transforms

clear_snapshot_transforms() -> None

Unregisters all globally registered snapshot transforms.

Snapshot cleaning helpers

pytest_regtest.cleaning.drop_keys

drop_keys(*keys: str) -> Callable[[Any], Any]

Returns a transform that recursively removes the given dict keys from obj, wherever they occur at any nesting depth.

pytest_regtest.cleaning.round_floats

round_floats(ndigits: int) -> Callable[[Any], Any]

Returns a transform that recursively rounds every float in obj to ndigits decimal places, so insignificant numerical noise (e.g. from floating point summation order) doesn't cause spurious snapshot failures.

pytest_regtest.cleaning.redact_regex

redact_regex(
    pattern: str, repl: str = "<redacted>"
) -> Callable[[Any], Any]

Returns a transform that recursively replaces every regex match of pattern in string values of obj with repl.

pytest_regtest.cleaning.walk

walk(obj: Any, leaf_fn: Callable[[Any], Any]) -> Any

Recursively walks obj, rebuilding it so the original is left untouched. Only the builtin containers dict, list, tuple and set are recursed into; everything else is considered a leaf and passed through leaf_fn.

PARAMETER	DESCRIPTION
`obj`	The (possibly nested) object to walk. TYPE: `Any`
`leaf_fn`	Function applied to each leaf value encountered. TYPE: `Callable[[Any], Any]`

RETURNS	DESCRIPTION
`Any`	A new object with `leaf_fn` applied to every leaf.

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],
    insert_front: bool = False,
)

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