Quantum programs need ordinary software discipline as well as quantum-specific checks. This guide presents a practical CI workflow for testing quantum programs before they reach a simulator or cloud backend, including deterministic unit tests, statevector and measurement assertions, circuit snapshots, seeded experiments, tolerance thresholds, and a project structure that can grow with your codebase.
Overview
A quantum circuit can be syntactically valid and still be wrong. A gate may target the wrong qubit, a measurement may use an unexpected bit order, or a small refactor may change a circuit's depth and noise sensitivity without raising an exception. Testing should catch these problems close to the code change, not after a remote job has been submitted.
The most reliable approach is to separate quantum software testing into layers:
- Classical unit tests verify input validation, parameter preparation, result parsing, and orchestration logic.
- Circuit structure tests verify qubit count, classical-bit count, gate choices, connectivity, depth, and measurement placement.
- Ideal simulator tests compare exact or near-exact statevector results for small circuits.
- Sampling tests compare measurement distributions using a fixed seed where supported and a suitable tolerance.
- Backend integration tests confirm that a circuit can be translated, submitted, and interpreted by a selected simulator or hardware service.
Keep the first three layers fast enough to run on every pull request. Sampling and backend tests may belong in a separate job when they require more time, credentials, or external services. The goal is not to prove that every possible quantum execution is correct. It is to make expected behavior explicit and detect meaningful regressions early.
A maintainable project layout
project/
src/
quantum_app/
circuits.py
execute.py
results.py
tests/
unit/
test_inputs.py
test_results.py
circuits/
test_bell_pair.py
test_measurements.py
test_snapshots.py
integration/
test_local_backend.py
snapshots/
bell_pair.json
pyproject.toml
.github/workflows/test.ymlKeep circuit construction separate from execution. A function that returns a circuit is easier to inspect and test than a function that builds, submits, waits, and formats results in one step.
Checklist by scenario
Scenario 1: Testing a deterministic, small circuit
Begin with circuits whose ideal behavior is unambiguous. An identity circuit should preserve a basis state. An X gate should flip a computational-basis state. A pair of entangling operations can be checked against the expected Bell-state amplitudes. These tests establish that the SDK wiring, qubit indexing, and execution adapter are behaving as intended.
- Construct the circuit with explicit numbers of qubits and classical bits.
- Assert the number of qubits and required registers.
- Inspect the gate sequence or normalized circuit representation.
- Run an ideal statevector or equivalent exact simulator when available.
- Compare amplitudes with an absolute tolerance rather than requiring fragile string equality.
- Verify that measurement operations are present only where expected.
A conceptual pytest-style test might look like this:
def test_x_gate_flips_zero(simulator):
circuit = make_circuit(operations=[("x", 0)])
state = simulator.statevector(circuit)
assert_probability(state, basis_state="1", expected=1.0, atol=1e-10)The exact simulator API differs between Qiskit, Cirq, PennyLane, and other quantum SDKs, so place framework-specific calls inside a small adapter. Your test should express behavior, not depend on the details of one execution provider.
Scenario 2: Testing measurements and sampled results
Measurement tests are probabilistic. Even a correct circuit can produce slightly different counts from one run to another. Test the expected distribution instead of demanding one exact count for every outcome.
- Use a small, known circuit such as a basis-state preparation or a balanced superposition.
- Set a seed when the selected simulator supports reproducible pseudorandom sampling.
- Use enough shots to make the assertion meaningful, while keeping CI fast.
- Assert that impossible outcomes remain absent or below a very small threshold.
- Assert that expected outcomes fall within a documented tolerance range.
- Normalize counts into probabilities before comparing results.
For example, a test for a circuit expected to produce only 00 and 11 should check that other bitstrings have negligible probability and that the two expected outcomes are reasonably close to their target probabilities. Do not use a tolerance copied from another project without considering shot count and the purpose of the test.
Scenario 3: Protecting circuit structure with snapshots
Behavioral tests can miss an accidental change that still produces an acceptable result on a simple simulator. Circuit snapshots provide a second line of defense. Store a normalized representation containing operations, targets, parameters, measurements, and—where useful—depth or layout information.
A snapshot should be stable across irrelevant formatting changes. Avoid snapshotting raw object representations that include memory addresses, provider metadata, or version-specific text. A compact JSON representation is usually easier to review:
{
"qubits": 2,
"operations": [
{"name": "h", "targets": [0]},
{"name": "cx", "targets": [0, 1]}
],
"measurements": [[0, 0], [1, 1]]
}When a snapshot changes, require a reviewer to decide whether the change is intentional. Updating a snapshot should never be an automatic response to a failing test.
Scenario 4: Testing a hybrid quantum-classical workflow
For variational algorithms and other hybrid workflows, test the classical boundaries independently. Check that parameters are mapped to the intended gates, the objective function receives results in the expected format, and the optimizer stops under the correct conditions. Use a small deterministic mock executor for most unit tests, then reserve real simulator runs for a smaller integration suite.
What to double-check
Reproducibility
Record the Python version, SDK versions, simulator configuration, shot count, seed, and circuit parameters for failed runs. A seed improves repeatability but does not make every backend or numerical operation identical across environments. Treat it as a debugging aid, not a universal guarantee.
Numerical tolerances
Statevector comparisons often need tight tolerances, while sampled probabilities need wider ones. Define tolerances by test purpose and document them. If a test fails only at the boundary, investigate whether the assertion is too strict, the simulator is nondeterministic, or the circuit has changed.
Bit and qubit ordering
Different SDKs and result formats may display bits in different orders. Add a dedicated test for your conversion layer. A test that checks counts without verifying ordering can pass while the application assigns a measured value to the wrong variable.
Compilation and translation
If production execution includes transpilation, decomposition, or routing, test both the logical circuit and the compiled form. Check that required operations remain supported, measurements survive translation, and resource limits such as depth or two-qubit-gate count do not change unexpectedly.
Failure diagnostics
When a test fails, print or attach the circuit diagram, normalized operation list, seed, parameters, and observed distribution. Quantum failures are much easier to investigate when the failing artifact is available in the CI log.
Common mistakes
- Testing only successful submission: A job that runs without an exception may still implement the wrong algorithm.
- Using only full end-to-end tests: Remote tests are slower and harder to diagnose. Keep most checks local and focused.
- Asserting exact shot counts: Sampling varies. Compare probabilities with an appropriate tolerance.
- Ignoring classical code: Parameter binding, result parsing, and post-processing often contain ordinary software bugs.
- Snapshotting unstable output: Raw SDK strings can change after harmless dependency updates. Normalize first.
- Hiding seed and environment details: Without execution metadata, a failure may be impossible to reproduce.
- Updating snapshots blindly: A changed snapshot may indicate a real regression. Review it as carefully as source code.
- Confusing ideal and noisy behavior: An ideal simulator test should not be used to assert hardware-level results. Keep noise, mitigation, and device behavior in separate integration tests.
When to revisit
Revisit this testing checklist before a seasonal planning cycle, after a major SDK or Python dependency update, and whenever the execution workflow changes. It also deserves review when a circuit gains new measurements, parameters, controlled operations, error-mitigation steps, or a new target backend.
Use this action list for the next change:
- Add or update a deterministic unit test for the smallest affected circuit.
- Add a structural assertion for qubits, measurements, gates, or resource limits.
- Run an ideal simulator test and record a clear tolerance.
- Add a seeded sampling test if the change affects measurement behavior.
- Review the circuit snapshot rather than accepting it automatically.
- Run the local test suite, then the integration job if credentials and backend access are required.
- Record the SDK, simulator, seed, and configuration in any failure report.
As your quantum codebase grows, treat tests as executable documentation. A compact suite of deterministic circuits, carefully chosen probabilistic assertions, and reviewed snapshots can provide a dependable foundation for quantum CI/CD without requiring every commit to use real hardware.
For related workflows, see Quantum Circuit Debugging, Quantum Error Mitigation for Developers, and How to Run a Quantum Circuit on Real Hardware.