pytest-quantum

The only pytest plugin built specifically for quantum software. 80+ assertions. 10 frameworks. Zero boilerplate. Ship quantum code you trust.

PyPI Python CI License: MIT

Who is this for?

  • Quantum software engineers writing gate-model circuits in Qiskit, Cirq, PennyLane, Pytket, or Braket who want rigorous, reproducible unit tests.

  • Researchers running VQE or QAOA who need statistically sound assertions on variational algorithm convergence, expressibility, and barren plateaus.

  • Teams CI-testing quantum algorithms across multiple frameworks and backends, including noisy simulation and real hardware targets.

  • Hardware validation engineers characterising real devices with quantum volume, randomised benchmarking, T1/T2/T2* coherence, and XEB fidelity.

The problem with quantum testing

# ❌ The old way: brittle, flaky, wrong
def test_bell_state():
    counts = run_bell_circuit(shots=1024)
    assert counts["00"] == 512   # fails 50% of the time due to shot noise
    assert counts["11"] == 512   # still wrong — global phase?

# ✅ The pytest-quantum way
from pytest_quantum import assert_measurement_distribution, assert_unitary

def test_bell_distribution(aer_simulator):
    counts = run_bell_circuit(aer_simulator, shots=2000)
    assert_measurement_distribution(counts, {"00": 0.5, "11": 0.5})
    # Chi-square tested. Won't flake. ✓

def test_hadamard():
    import numpy as np
    assert_unitary(h_circuit, np.array([[1,1],[1,-1]])/np.sqrt(2))
    # Global-phase safe. Works on Qiskit, Cirq, Braket, Pytket. ✓

One line install. Fixtures auto-injected. Tests just work.

Install in 10 seconds

pip install pytest-quantum                   # core
pip install "pytest-quantum[qiskit]"         # + Qiskit + Aer  ← most common
pip install "pytest-quantum[all]"            # everything

Then just write tests. No conftest.py. No imports. Fixtures appear by magic.

What’s in the box

Category

Count

Examples

Unitary & equivalence

6

assert_unitary, assert_circuits_equivalent, assert_cross_platform_equivalent

States & fidelity

3

assert_state_fidelity_above, assert_states_close, assert_normalized

Measurement distributions

2

assert_measurement_distribution, assert_counts_close

Density matrices

4

assert_density_matrix_close, assert_purity_above, assert_trace_distance_below

Quantum channels

6

assert_channel_is_cptp, assert_process_fidelity_above, assert_hermitian

Noise models

6

assert_depolarizing_channel, assert_amplitude_damping_channel, assert_channel_diamond_norm_below

Entanglement

3

assert_entanglement_entropy_below, assert_bloch_sphere_close, assert_schmidt_rank_at_most

Observables & VQE

4

assert_expectation_value_close, assert_vqe_converges, assert_ground_state_energy_close

Circuit structure

7

assert_circuit_depth, assert_gate_count, assert_circuit_is_clifford, assert_no_mid_circuit_measurement

Benchmarking

7

assert_quantum_volume, assert_randomized_benchmarking, assert_t1_above, assert_t2_above, assert_interleaved_rb

Quantum ML

4

assert_xeb_fidelity_above, assert_expressibility_above, assert_no_barren_plateau

Error mitigation

7

assert_zne_reduces_error, assert_pec_expectation_close, assert_cdr_reduces_error

Hardware

5

assert_backend_calibration, assert_circuit_fits_backend, assert_mirror_fidelity

QEC / Stim

3

assert_stim_logical_error_rate_below, assert_stabilizer_state

Sweeps

3

assert_circuit_sweep, assert_parametrized_unitary_continuous

QASM round-trips

2

assert_qasm_roundtrip, assert_qasm2_roundtrip

Snapshots

2

assert_unitary_snapshot, assert_distribution_snapshot

Information theory

3

assert_hellinger_close, assert_kl_divergence_below

Total

80+

Framework support

Works everywhere quantum code runs:

Framework

Install

Fixtures

Qiskit + Aer

pytest-quantum[qiskit]

aer_simulator, qiskit_sampler, qiskit_estimator

Cirq

pytest-quantum[cirq]

cirq_simulator, cirq_sampler

Amazon Braket

pytest-quantum[braket]

braket_simulator, braket_cloud_device

PennyLane

pytest-quantum[pennylane]

pennylane_device

Pytket

pip install pytket

pytket_circuit_factory

Stim (QEC)

pip install stim

stim_sampler

Mitiq

pytest-quantum[mitiq]

works with any backend

IBM Quantum (real HW)

pytest-quantum[ibm]

ibm_backend

IonQ (real HW)

pip install qiskit-ionq

ionq_backend

Quantinuum (real HW)

pip install pytket-quantinuum

quantinuum_backend

Documentation

Start here

Reference

Tutorials

Project