ditto¶

The names most code imports: import ditto.

`record = pytest.mark.record` `module-attribute` ¶

Mark a test's snapshots with a recorder, and optionally a target.

Use as @ditto.record("yaml"), @ditto.record("json", target=uri) or @ditto.record("json", target_profile=name). The recorder name is required. A test may have one record mark, set on its function, class or module.

`yaml = record('yaml')` `module-attribute` ¶

Store a test's snapshots as YAML: @ditto.record("yaml").

`json = record('json')` `module-attribute` ¶

Store a test's snapshots as strict JSON, the default: @ditto.record("json").

`version = version` `module-attribute` ¶

The installed pytest-ditto version, such as "2.0.0".

`Snapshot(group_name, module, target, _backend, recorder=_UNSET, recorder_name=_UNSET, mode=SnapshotMode.RECORD, nodeid='', target_id='', _tracker=_SessionTracker())` `dataclass` ¶

Where a test's snapshots are stored and how they are recorded.

The snapshot fixture builds one for each test, and calling it, snapshot(data, key), stores or loads one snapshot. Construct a Snapshot directly only when fixture injection isn't available; it is immutable and holds no open resources.

Parameters:

Name	Type	Description	Default
`group_name`	`str`	Prefix used in snapshot keys. Derived from the pytest nodeid minus the file path (e.g. "test_something" or "TestClass.test_something").	required
`module`	`str`	Rootdir-relative test file stem (e.g. "tests/bar/test_api"). Required for all backends. Provides namespace isolation across test files.	required
`target`	`str`	URI of the storage location. Its scheme sets the storage key format: `file://` uses flat dotted keys (`module.group@key~hash.ext`), and every other scheme slash-separated keys (`module/group@key~hash.ext`). The data itself goes to `_backend`.	required
`_backend`	`MutableMapping[str, bytes]`	The mapping snapshots are stored in, such as a `dict` or an `FsspecMapping`. The fixture builds it from the test's target.	required
`recorder`	`Recorder`	Serialisation strategy. Defaults to strict JSON.	`_UNSET`
`recorder_name`	`str`	The recorder's registered name, which is its persisted identifier: it ends snapshot filenames and is recorded in `ditto.lock`. The fixture passes the name the recorder was selected by. A directly constructed `Snapshot` passes `recorder` and `recorder_name` together, or neither for strict JSON (`"json"`). The name may be omitted with the strict JSON recorder itself, whose name is `"json"`.	`_UNSET`
`mode`	`SnapshotMode`	Whether a snapshot is recorded, updated, or only verified. Defaults to `SnapshotMode.RECORD`.	`RECORD`
`nodeid`	`str`	Full pytest node id for the owning test, e.g. `tests/test_api.py::test_foo`. Used to build lock-file entries. Empty when constructed outside the fixture.	`''`
`target_id`	`str`	Portable lock-file target id (rootdir-relative for `file://`, URI otherwise).	`''`
`_tracker`	`_SessionTracker`	Where snapshot activity is recorded. The fixture passes its pytest session's tracker; a directly constructed `Snapshot` gets a private one.	`_SessionTracker()`

`call(data, key)` ¶

Store or load the snapshot for key, and return its value.

What happens depends on mode and on whether the snapshot is stored; see SnapshotMode. The value returned is always what the recorder reads back, never data itself.

Raises:

Type	Description
`TypeError`	When `key` isn't a `str`.
`DuplicateSnapshotKeyError`	When this test has already used `key`.
`DittoSnapshotNameCollisionError`	When another snapshot this session has the same storage name.

Source code in ditto/snapshot.py

def __call__(self, data: Any, key: str) -> Any:
    """Store or load the snapshot for `key`, and return its value.

    What happens depends on `mode` and on whether the snapshot is stored;
    see `SnapshotMode`. The value returned is always what the recorder
    reads back, never `data` itself.

    Raises
    ------
    TypeError
        When `key` isn't a `str`.
    DuplicateSnapshotKeyError
        When this test has already used `key`.
    DittoSnapshotNameCollisionError
        When another snapshot this session has the same storage name.
    """
    return resolve_snapshot(self, data, key)

`SnapshotMode` ¶

Bases: Enum

How a Snapshot treats the stored value for a key.

Attributes:

Name	Type	Description
`RECORD`		Save the value when the key is absent; otherwise return the stored value.
`UPDATE`		Always save the value, overwriting a stored one. Set by `--ditto-update`.
`VERIFY`		Never write: return the stored value, or the given value when the key is absent. Set by `--ditto-verify`, so a verify run cannot recreate a deleted snapshot.
`A value that is saved, or returned under VERIFY for an absent key, is`
`serialised and deserialised first, and the deserialised value is returned.`

`DuplicateSnapshotKeyError(key)` ¶

Bases: DittoException

Raised when a test calls snapshot() twice with the same key.

Source code in ditto/exceptions.py

def __init__(self, key: str) -> None:
    super().__init__(
        f"Snapshot key '{key}' has already been used in this test. "
        "Each snapshot call within a test must use a unique key."
    )

ditto¶

record = pytest.mark.record module-attribute ¶

yaml = record('yaml') module-attribute ¶

json = record('json') module-attribute ¶

version = __version__ module-attribute ¶

Snapshot(group_name, module, target, _backend, recorder=_UNSET, recorder_name=_UNSET, mode=SnapshotMode.RECORD, nodeid='', target_id='', _tracker=_SessionTracker()) dataclass ¶

__call__(data, key) ¶

SnapshotMode ¶

DuplicateSnapshotKeyError(key) ¶