Quantum circuits are probabilistic at measurement time, but that does not make them untestable. This guide presents a practical Python testing workflow for checking circuit structure, ideal state behavior, distributions, expectation values, and seeded simulator results, with pytest fixtures and CI patterns you can adapt across quantum SDKs.
Overview
A reliable quantum test suite separates deterministic defects from expected statistical variation. A misplaced gate, incorrect qubit order, or missing measurement should usually fail with an exact assertion. A shot-based result, by contrast, should be checked with a tolerance, confidence interval, or property rather than an exact count.
Start by testing the least expensive and most stable representation of the program. A useful order is:
- Circuit structure: qubit count, classical-bit count, gate presence, gate counts, barriers, measurements, and parameter names.
- Ideal state properties: amplitudes, probabilities, normalization, parity, symmetry, or expectation values from a statevector-capable simulator.
- Shot-based behavior: measured distributions and observables within an explicitly chosen tolerance.
- Seeded regression results: stable simulator outputs used for debugging, not as a substitute for statistical validation.
- Backend behavior: transpilation, noise, connectivity, measurement mapping, and hardware execution in separate integration tests.
Keep unit tests focused on the circuit-building function. For example, a function that returns a circuit should not also submit a cloud job, read credentials, or hide the shot count. Those concerns belong at the integration boundary. This separation makes a quantum CI pipeline faster, easier to diagnose, and less sensitive to SDK or backend changes.
For related guidance, see the guide to testing quantum programs in CI and the practices for reproducible quantum experiments.
Checklist by scenario
1. Test circuit structure first
Structural tests catch ordinary programming mistakes before simulation begins. They are usually exact, fast, and stable across simulator seeds.
def build_bell_circuit():
# Replace this with the circuit type used by your SDK.
circuit = QuantumCircuit(2, 2)
circuit.h(0)
circuit.cx(0, 1)
circuit.measure([0, 1], [0, 1])
return circuit
def test_bell_circuit_structure():
circuit = build_bell_circuit()
assert circuit.num_qubits == 2
assert circuit.num_clbits == 2
assert circuit.count_ops().get("h", 0) == 1
assert circuit.count_ops().get("cx", 0) == 1
assert circuit.count_ops().get("measure", 0) == 2
In a real project, isolate SDK-specific details behind small helper functions such as count_operations or measurement_count. That keeps the test intent readable and reduces the number of places you must update when a result or circuit API changes.
2. Check statevector properties with exact assertions
When testing an ideal circuit without measurement, compare mathematical properties rather than relying only on a full serialized statevector. Full-vector snapshots can be useful, but they are sensitive to global phase, qubit ordering, precision, and representation details.
For a Bell-state circuit, suitable properties include:
- The probabilities of
00and11are approximately one-half. - The probabilities of
01and10are approximately zero. - The probabilities sum to one.
- The two qubits have equal computational-basis outcomes.
import numpy as np
def assert_probability_close(actual, expected, atol=1e-8):
np.testing.assert_allclose(actual, expected, atol=atol, rtol=0)
def test_bell_state_probabilities(statevector_simulator):
circuit = build_bell_circuit_without_measurements()
state = statevector_simulator(circuit)
probabilities = state.probabilities()
assert_probability_close(probabilities.sum(), 1.0)
assert_probability_close(probabilities[0], 0.5)
assert_probability_close(probabilities[3], 0.5)
assert_probability_close(probabilities[1], 0.0)
assert_probability_close(probabilities[2], 0.0)
The exact statevector and probability accessors differ between Qiskit, Cirq, and PennyLane. Treat the simulator adapter as part of your test support code. The assertion strategy remains the same even when the SDK call changes.
3. Validate probability distributions statistically
Shot-based tests should not normally assert that a result contains exactly the ideal count. If a state has a 50% probability of producing 00, a 1,000-shot run might produce 487 occurrences rather than exactly 500. Use a tolerance that reflects the shot count and the purpose of the test.
def assert_distribution_close(actual_counts, expected_probabilities,
shots, tolerance=0.08):
for outcome, expected_probability in expected_probabilities.items():
observed_probability = actual_counts.get(outcome, 0) / shots
assert abs(observed_probability - expected_probability) <= tolerance
def test_bell_measurements(counts_simulator):
shots = 2_000
counts = counts_simulator(build_bell_circuit(), shots=shots, seed=7)
assert_distribution_close(
counts,
{"00": 0.5, "11": 0.5, "01": 0.0, "10": 0.0},
shots=shots,
tolerance=0.06,
)
For production-quality statistical tests, choose the tolerance deliberately. A fixed percentage is simple, but a binomial confidence interval or a test designed around the expected variance is more informative when shot counts vary. Document whether the tolerance covers sampling variation only or also includes a noise model.
4. Test expectation values separately
Variational algorithms and many hybrid workflows consume expectation values rather than raw bitstrings. Test the observable and its sign explicitly. A sign error can produce plausible-looking measurements while sending an optimizer in the wrong direction.
def test_z_expectation_for_zero_state(expectation_simulator):
circuit = make_zero_state_circuit()
value = expectation_simulator(circuit, observable="Z", qubit=0)
assert value == pytest.approx(1.0, abs=1e-8)
For noisy or shot-based expectation values, use a wider tolerance and test the expected direction when an exact value is not appropriate. The quantum measurement strategies guide covers shots, observables, basis rotations, and result post-processing that can affect these tests.
5. Use seeded outputs as diagnostic snapshots
A simulator seed can make a failing test reproducible. It is useful when debugging a changed transpilation path, measurement mapping, or random noise sample. However, a seeded output is an implementation snapshot, not a universal truth. Different SDK versions, simulator backends, optimization settings, or parallel execution modes may legitimately change it.
@pytest.fixture
def seeded_counts_simulator():
def run(circuit, shots=256, seed=1234):
return run_local_simulator(
circuit,
shots=shots,
seed_simulator=seed,
seed_transpiler=seed,
)
return run
def test_seeded_regression(seeded_counts_simulator):
counts = seeded_counts_simulator(build_bell_circuit(), shots=256)
assert counts == {"00": 129, "11": 127}
Use exact seeded snapshots only when the simulator configuration is pinned and the team accepts that the snapshot may require review after an upgrade. Pair the snapshot with a distribution-level test so the suite does not mistake a changed random sequence for a changed algorithm.
Testing strategy comparison
| Test type | Best for | Assertion style | Main risk |
|---|---|---|---|
| Exact assertions | Structure, gate counts, dimensions, deterministic invariants | Exact equality | Overfitting to SDK representation |
| Statistical assertions | Shots, noisy results, sampled observables | Tolerance or confidence interval | Flaky thresholds or too few shots |
| Snapshot tests | Serialized circuits, seeded simulator output, compiled artifacts | Compare with an approved baseline | Stale snapshots hiding meaningful changes |
| Property-based tests | Parameterized circuits and broad input ranges | Invariant holds across generated cases | Slow or poorly constrained test cases |
6. Add property-based tests for parameterized circuits
For circuits with rotation angles or encoded inputs, test invariants across representative values. Useful properties include normalized probabilities, Hermitian-observable bounds, periodicity where expected, and preservation of qubit or register dimensions.
@pytest.mark.parametrize("angle", [0.0, 0.25, 1.0, 3.141592653589793])
def test_parameterized_circuit_is_normalized(angle, statevector_simulator):
circuit = make_rotation_circuit(angle)
state = statevector_simulator(circuit)
assert state.probabilities().sum() == pytest.approx(1.0, abs=1e-8)
For broader generated input coverage, Hypothesis can supply bounded floating-point values, but avoid blindly generating values that make simulation impractically large. Test data encoding and parameterized-circuit behavior separately when possible.
What to double-check
- Qubit ordering: Confirm whether the SDK displays the least-significant qubit first, and write a small mapping test for bitstrings.
- Classical-bit mapping: A correct quantum state can appear wrong if measurement results are stored or displayed in a different order.
- Measurement placement: Statevector tests generally need an unmeasured circuit, while count tests require measurements or an SDK-specific sampling path.
- Global phase: Physically equivalent states can have different complex amplitudes. Prefer probabilities, observables, or phase-insensitive comparisons unless phase is the behavior under test.
- Noise configuration: Record the model, seed, shot count, and backend options. See the quantum noise models guide when validating noisy simulations.
- Transpilation: Test the logical circuit separately from the compiled circuit. Gate counts and layout can change when the target backend or optimization level changes.
- SDK result formats: Normalize counts, probabilities, and expectation values at the boundary of your test helpers rather than spreading version-specific parsing through every test.
- External jobs: Keep hardware or cloud-provider tests marked as integration tests. They may need credentials, queues, backend availability, and a different failure policy from unit tests.
When moving between Qiskit, Cirq, PennyLane, or another framework, compare semantics before comparing syntax. The quantum SDK migration guide and circuit portability guide can help identify differences in registers, measurement conventions, observables, and parameter handling.
Common mistakes
- Asserting exact shot counts. Replace
counts["00"] == 500with a probability or tolerance assertion unless the circuit is deterministic. - Using one test for everything. A failing structure test, statevector test, and hardware test should point to different likely causes. Keep them separate.
- Testing only the final answer. A circuit can produce the expected output for the wrong reason on a narrow fixture. Check intermediate invariants and representative inputs.
- Hard-coding an unrecorded seed. Store seeds with the test configuration and label seeded snapshots as diagnostic artifacts.
- Ignoring bit order. Add a basis-state mapping test before interpreting multi-qubit count strings.
- Comparing raw floating-point arrays too strictly. Use an absolute tolerance appropriate to the simulator precision and operation count.
- Allowing CI to call hardware for every pull request. Run fast local simulator tests on ordinary changes and reserve hardware tests for scheduled, labeled, or release workflows.
- Accepting snapshots automatically. Review circuit and result diffs. Updating a snapshot should be a deliberate change accompanied by an explanation.
When to revisit
Review this testing checklist whenever a circuit feature, SDK, simulator, backend, noise model, or result parser changes. A practical maintenance schedule is to inspect the suite before major planning or release cycles and at least every six months, even if the circuit code has not changed.
At each review, verify:
- The SDK imports and result accessors still match the supported version.
- Seed and simulator options still produce reproducible local diagnostics.
- Statistical tolerances are justified by the current shot counts and noise assumptions.
- Snapshots represent intentional behavior rather than accidental implementation details.
- CI separates fast unit tests from integration and hardware tests.
- Test fixtures cover new parameters, observables, encodings, and backend targets.
Before merging a quantum circuit change, run this short sequence: inspect the structure, validate an ideal invariant, sample the distribution, record the seed and configuration for any failure, then run the relevant integration test. This workflow turns probabilistic behavior into evidence that can be reviewed, reproduced, and maintained as the surrounding quantum software tools evolve.