Testing Quantum Programs

Quantum programs are unusually hard to test. You cannot print an intermediate state — measurement destroys it — and the output is a probability distribution, not a deterministic value. Yet testing is non-negotiable: a subtle phase error or a swapped qubit index produces a circuit that looks plausible and is silently wrong. This lesson covers the discipline of writing assertions that pin down quantum behaviour, using a simulator as the oracle of truth.

Three things you can assert

Because the simulator gives us the full state — something hardware never will — we can test against three increasingly strict notions of correctness:

State equality. The prepared statevector equals a known reference, up to global phase. This is the strongest check and the right one for a state-preparation routine.
Distribution equality. The measurement probabilities match an expected histogram. Use this when only the outcome statistics matter and the relative phases do not.
Unitary equality. The whole gate (its $2^n\times2^n$ matrix) equals a target operator. Use this for a building block that will be embedded in larger circuits, where its action on all inputs matters, not just $|0\dots0\rangle$ .

A good test suite uses the weakest assertion that still catches the bugs you care about — a state assertion would reject a valid circuit that merely differs by an irrelevant global phase, so the grader compares up to global phase by default.

The Bell state as a test fixture

A fixture is a known-good value tests compare against. The canonical entanglement fixture is the Bell state

|\Phi^+\rangle = \frac{|00\rangle + |11\rangle}{\sqrt{2}},

prepared by a Hadamard on qubit 0 followed by a CNOT from qubit 0 to qubit 1:

const c = circuit(2);
c.h(0);      // (|00> + |10>) / sqrt(2)
c.cx(0, 1);  // (|00> + |11>) / sqrt(2) = |Phi+>

Its statevector has amplitudes $\tfrac{1}{\sqrt{2}}$ at indices $0$ ( $|00\rangle$ ) and $3$ ( $|11\rangle$ ), and $0$ elsewhere. Any entangling routine claiming to produce $|\Phi^+\rangle$ can be tested by asserting its statevector equals this fixture.

Why up-to-global-phase matters

Two states that differ only by an overall factor $e^{i\varphi}$ are physically identical — no measurement can distinguish them. A naive equality check that compared raw amplitude arrays would flag the perfectly-correct state $-|\Phi^+\rangle$ as wrong. Robust quantum tests therefore compare up to global phase: they fix the phase of one reference amplitude and check the rest relative to it. The relative phases between basis states are physical and are checked; only the unobservable overall phase is ignored.

Testing strategy in practice

For a real routine you would layer assertions:

A statevector test on the empty-input case ( $|0\dots0\rangle$ ) to catch gross errors.
A unitary test on a small instance to catch input-dependent bugs the zero-input case misses.
A distribution test with seeded sampling (next lessons) to check the measured behaviour the user actually observes.

Each test isolates a different failure mode, and all of them lean on the simulator as a trusted, fully-observable oracle — the one place in the stack where the entire quantum state is visible.

Try it

Build the Bell-state fixture $|\Phi^+\rangle$ on 2 qubits. The grader derives the target statevector from the reference solution and checks yours matches, up to global phase.

Run your code to see the quantum state.