Snapshot testing

Snapshot (golden-file) testing locks in a circuit’s measured distribution: the first run records it to a JSON file, later runs re-sample and compare against that baseline with the usual statistical metric. Use it through the qtest_snapshot pytest fixture:

def test_my_circuit(qtest_snapshot):
    qc = build_circuit()
    qc.measure_all()
    qtest_snapshot.assert_distribution_close(qc, shots=4096, tolerance=0.1)

Golden files are written to a __qtest_snapshots__/ directory beside the test file and should be committed. Refresh them deliberately:

pytest --qtest-snapshot-update

Reference

Snapshot (golden-file) testing for measurement distributions.

The first time a snapshot test runs (or whenever --qtest-snapshot-update is passed) qtest samples the circuit and writes the resulting distribution to a JSON golden file next to your test. On later runs it re-samples and compares against the stored baseline with the usual statistical metric — so you can lock in a circuit’s behaviour and get alerted when a refactor changes it, without hand-writing the expected distribution.

Use it through the qtest_snapshot() pytest fixture:

def test_my_circuit(qtest_snapshot):
    qc = build_circuit()
    qc.measure_all()
    qtest_snapshot.assert_distribution_close(qc, shots=4096, tolerance=0.1)

Golden files live in a __qtest_snapshots__/ directory beside the test file and should be committed to version control. Refresh them deliberately with:

pytest --qtest-snapshot-update
class qtest.snapshot.Snapshot(directory, default_name, update=False)[source]

Bases: object

A handle to the golden files for one test.

Usually obtained from the qtest_snapshot() fixture rather than constructed directly.

Parameters:

  • directory (Path) – Directory holding this test’s golden files (created on demand).

  • default_name (str) – Snapshot name used when a call does not pass an explicit name (typically derived from the test’s node id).

  • update (bool) – When True (--qtest-snapshot-update), golden files are (re)written instead of compared.

path_for(name=None)[source]

Return the golden-file path for name (or the default name).

Parameters:

name (str | None)

Return type:

Path

assert_distribution_close(circuit, name=None, shots=None, tolerance=None, metric=None, backend=None, seed=None, noise_model=None, msg=None)[source]

Compare circuit’s distribution against a stored snapshot.

On the first run (no golden file yet) or under --qtest-snapshot-update the measured distribution is written to disk and the check passes. Otherwise the circuit is re-sampled and compared to the stored distribution via qtest.assert_distribution_close().

Parameters:

  • circuit (Any) – A backend-native circuit with measurements.

  • name (str | None) – Snapshot name (allows multiple snapshots per test). Defaults to the test’s node-id-derived name.

  • shots (int | None) – Forwarded to sampling / comparison; None means “use config”.

  • tolerance (float | None) – Forwarded to sampling / comparison; None means “use config”.

  • metric (str | None) – Forwarded to sampling / comparison; None means “use config”.

  • backend (Any | None) – Forwarded to sampling / comparison; None means “use config”.

  • seed (int | None) – Forwarded to sampling / comparison; None means “use config”.

  • noise_model (Any | None) – Forwarded to sampling / comparison; None means “use config”.

  • msg (str | None) – Forwarded to sampling / comparison; None means “use config”.

Return type:

None