Fixtures

The qtest.fixtures subpackage provides ready-to-use pytest fixtures for common quantum circuits, plus plain factory functions that can be called outside of pytest.

To make the fixtures discoverable in your suite, list the relevant plugin modules under pytest_plugins in your top-level conftest.py:

pytest_plugins = [
    "qtest.fixtures.common_states",
    "qtest.fixtures.common_gates",
]

State-preparation fixtures

bell_state	Yield a fresh Bell-state preparation circuit per test.
plus_state	Yield a fresh \(|+\rangle\) preparation circuit per test.
minus_state	Yield a fresh \(|-\rangle\) preparation circuit per test.
ghz_state	Factory fixture yielding n -> QuantumCircuit for GHZ-n states.
ghz_3	Shortcut for a 3-qubit GHZ preparation circuit.
ghz_4	Shortcut for a 4-qubit GHZ preparation circuit.
ghz_5	Shortcut for a 5-qubit GHZ preparation circuit.
w_state	Factory fixture yielding n -> QuantumCircuit for W-n states.

Pytest fixtures (and plain factory functions) for common quantum states.

Each fixture / factory returns a qiskit.QuantumCircuit that prepares the named state starting from \(|0\rangle^{\otimes n}\). Circuits are unitary-only (no measurement / reset); add qc.measure_all() in your test when sampling.

The same builders are exposed twice:

• As pytest fixtures (bell_state, ghz_state, plus_state, ghz_3 …) — request them in test signatures.

• As plain functions (bell_circuit, ghz_circuit(n), plus_circuit …) — call them directly outside of pytest tests.

For pytest discovery, list this module in the consumer’s pytest_plugins or import individual fixtures into your conftest.py:

# tests/conftest.py
pytest_plugins = ["qtest.fixtures.common_states"]

Examples

>>> # In a pytest test:
>>> def test_bell(bell_state, qiskit_backend):
...     assert_state_close(bell_state, "bell")

>>> # As a plain function:
>>> from qtest.fixtures.common_states import bell_circuit
>>> qc = bell_circuit()

qtest.fixtures.common_states.bell_circuit()

Return a circuit preparing the Bell state \((|00\rangle + |11\rangle)/\sqrt{2}\).

Return type:

Any

qtest.fixtures.common_states.plus_circuit()

Return a 1-qubit circuit preparing \(|+\rangle = (|0\rangle + |1\rangle)/\sqrt{2}\).

Return type:

Any

qtest.fixtures.common_states.minus_circuit()

Return a 1-qubit circuit preparing \(|-\rangle = (|0\rangle - |1\rangle)/\sqrt{2}\).

Return type:

Any

qtest.fixtures.common_states.ghz_circuit(n)

Return an n-qubit GHZ-state preparation circuit.

Builds \((|0\rangle^{\otimes n} + |1\rangle^{\otimes n}) / \sqrt{2}\) via the standard H + (n-1) × CX recipe.

Parameters:

n (int) – Qubit count (n >= 1).

Return type:

Any

qtest.fixtures.common_states.w_circuit(n)

Return an n-qubit W-state preparation circuit.

For n == 1 returns X|0> = |1>; for n == 2 uses the closed-form H + CX + X recipe; for n >= 3 it appends a unitary qiskit.circuit.library.StatePreparation block with the target amplitudes \((|10\dots0\rangle + |01\dots0\rangle + \dots) / \sqrt{n}\).

Parameters:

n (int) – Qubit count (n >= 1).

Return type:

Any

qtest.fixtures.common_states.bell_state()

Yield a fresh Bell-state preparation circuit per test.

Example:

def test_bell(bell_state):
    assert_state_close(bell_state, "bell")

Return type:

Any

qtest.fixtures.common_states.plus_state()

Yield a fresh \(|+\rangle\) preparation circuit per test.

Return type:

Any

qtest.fixtures.common_states.minus_state()

Yield a fresh \(|-\rangle\) preparation circuit per test.

Return type:

Any

qtest.fixtures.common_states.ghz_state()

Factory fixture yielding n -> QuantumCircuit for GHZ-n states.

Example:

def test_ghz_5(ghz_state):
    assert_state_close(ghz_state(5), "ghz_5")

Return type:

Callable[[int], Any]

qtest.fixtures.common_states.w_state()

Factory fixture yielding n -> QuantumCircuit for W-n states.

Example:

def test_w_4(w_state):
    assert_state_close(w_state(4), "w_4")

Return type:

Callable[[int], Any]

qtest.fixtures.common_states.ghz_3()

Shortcut for a 3-qubit GHZ preparation circuit.

Return type:

Any

qtest.fixtures.common_states.ghz_4()

Shortcut for a 4-qubit GHZ preparation circuit.

Return type:

Any

qtest.fixtures.common_states.ghz_5()

Shortcut for a 5-qubit GHZ preparation circuit.

Return type:

Any

Gate-layer fixtures

hadamard_circuit	Factory fixture for n-qubit Hadamard-layer circuits.
random_clifford	Factory fixture for random Clifford circuits.

Pytest fixtures (and plain factory functions) for common gate-sequence circuits.

Provides:

• hadamard_circuit(n) — n-qubit Hadamard layer (one H per qubit).

• random_clifford_circuit(n, depth, seed) — depth-controlled random Clifford built from the gate set {H, S, S†, X, Y, Z} plus occasional CX for n >= 2.

Examples

>>> # In a pytest test:
>>> def test_uniform(hadamard_circuit):
...     assert_distribution_close(
...         hadamard_circuit(3), expected={"000": 1/8, ..., "111": 1/8}
...     )

>>> # As plain functions:
>>> from qtest.fixtures.common_gates import random_clifford_circuit
>>> qc = random_clifford_circuit(n=2, depth=20, seed=42)

qtest.fixtures.common_gates.hadamards(n=1)

Return an n-qubit circuit that applies \(H\) to every qubit.

The resulting state from \(|0\rangle^{\otimes n}\) is the uniform superposition \(H^{\otimes n}|0\rangle^{\otimes n}\).

Parameters:

n (int)

Return type:

Any

qtest.fixtures.common_gates.random_clifford_circuit(n=1, depth=10, seed=None)

Return a random Clifford circuit on n qubits with depth gates.

Each “layer” is a single gate: with probability ~0.3 (when n >= 2) a random CX, otherwise a random gate drawn from {H, S, S†, X, Y, Z} on a random qubit. Reproducible when seed is set.

Parameters:

• n (int) – Qubit count (n >= 1).

• depth (int) – Number of gates (depth >= 0). depth == 0 returns the identity circuit.

• seed (int | None) – Seed for the RNG; None means non-deterministic.

Return type:

Any

qtest.fixtures.common_gates.hadamard_circuit()

Factory fixture for n-qubit Hadamard-layer circuits.

Example:

def test_uniform(hadamard_circuit):
    qc = hadamard_circuit(3)         # 3 qubits, all in |+>
    qc.measure_all()
    assert_distribution_close(
        qc, expected={f"{i:03b}": 1/8 for i in range(8)}
    )

Return type:

Callable[[…], Any]

qtest.fixtures.common_gates.random_clifford()

Factory fixture for random Clifford circuits.

Example:

def test_clifford_unitarity(random_clifford):
    for seed in range(5):
        assert_unitary(random_clifford(n=3, depth=20, seed=seed))

Return type:

Callable[[…], Any]

Plain factories (no pytest required)

The state and gate builders are also exposed as plain factory functions via the qtest.fixtures package — usable in scripts, notebooks, or any non-pytest context:

from qtest.fixtures import bell_circuit, ghz_circuit

qc = bell_circuit()
ghz5 = ghz_circuit(5)

Built-in pytest fixtures (and plain factories) for common quantum circuits.

To use the fixtures in your tests, add the relevant module(s) to pytest_plugins in your top-level conftest.py:

# tests/conftest.py
pytest_plugins = [
    "qtest.fixtures.common_states",
    "qtest.fixtures.common_gates",
]

The same builders are also exposed as plain functions here, usable outside of pytest:

from qtest.fixtures import bell_circuit, ghz_circuit
qc = bell_circuit()
ghz5 = ghz_circuit(5)

Imports are lazy (PEP 562 __getattr__): nothing is loaded until the attribute is actually requested. This lets the pytest plugin loader register common_states and common_gates as plugins independently, without one being imported as a side effect of the other (which would suppress assert rewriting in the second).