qtest — statistical, pytest-native testing for quantum circuits¶
qtest is an open-source Python library that brings the discipline of
modern software testing to quantum programs. It plugs straight into
pytest, gives you statistical assertions designed for noisy and
probabilistic outputs, and integrates with Hypothesis so you can do property-based testing
on quantum circuits — without writing a single line of plumbing.
Why qtest?¶
Testing quantum software is hard for reasons classical testing tools were never designed to handle:
Outputs are distributions, not values. A measurement gives you counts that are statistically close to the truth, never exact.
assertEqualis the wrong tool.State and unitary comparisons are global-phase-insensitive. Two correct implementations of the same gate can differ by a phase that doesn’t matter physically — but does matter to
numpy.allclose.Shot noise and seed drift make tests flaky. Without a principled tolerance and a controlled seed, your CI lights up red at random.
Property-based testing fits quantum perfectly — laws like unitarity, reversibility, and Bell-state symmetry are universal — but the standard Hypothesis strategies don’t know about
QuantumCircuit.
qtest solves these directly: tolerance-aware statistical assertions,
a Hypothesis strategy set tuned for circuits, gates, and states, and a
pytest plugin that exposes --qtest-shots, --qtest-tolerance,
and --qtest-seed as first-class CLI flags.
Quickstart¶
Install:
pip install qtest-quantum
Write your first quantum test — a Bell state should produce a 50/50
distribution over 00 and 11:
from qiskit import QuantumCircuit
from qtest import assert_distribution_close
def test_bell_state_is_balanced():
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()
assert_distribution_close(
qc,
expected={"00": 0.5, "11": 0.5},
shots=4096,
tolerance=0.03,
)
Run it:
pytest test_bell.py -v
That’s it — no mocking, no manual shot-count math, no hand-rolled tolerance checks.
Getting started
User guide
API reference
Project