Quantum Workloads in CI/CD: Test Circuits Locally Before Submitting Cloud Jobs

Overview

A quantum circuit CI pipeline should answer three different questions:

1. Does the application behave correctly? Unit and integration tests can check circuit construction, classical post-processing, input validation, and expected results on small cases.
2. Can the circuit be submitted correctly? Provider adapters, authentication, backend selection, serialization, and job polling can be tested with mocks or controlled integration environments.
3. Does the workload behave on a target device? Hardware tests can reveal noise, queue behavior, backend restrictions, and transpilation effects, but they should usually run on a schedule or behind an explicit promotion step.

Keeping these questions separate prevents a common failure mode: making every pull request depend on a cloud backend. A local simulator is fast and inexpensive, but it does not reproduce all hardware behavior. A mocked provider verifies application logic, but it cannot prove that a real job will execute successfully. A scheduled hardware test adds valuable evidence, but it may be slower, nondeterministic, or subject to provider availability.

Design the pipeline in layers. Start with tests that run on every change, then add provider-level checks only when they provide information that a local test cannot. For background on selecting a suitable execution target, see How to Choose a Quantum Computing Backend for a Workload. For a broader comparison of platforms and migration concerns, use How to Choose a Quantum SDK and Cloud Platform.

Checklist by scenario

Scenario 1: Every pull request

Keep the default CI path deterministic, small, and independent of cloud credentials.

• Install the pinned Python and SDK versions declared by the project.
• Run formatting, linting, type checks, and ordinary Python unit tests.
• Build representative circuits with the smallest useful number of qubits.
• Use a local state-vector, shot-based, or stabilizer simulator appropriate to the circuit.
• Use fixed seeds where the selected simulator supports reproducible sampling.
• Assert stable properties rather than fragile full output dumps. Examples include valid bit-string keys, normalized probabilities, expected symmetry, or a known result for a tiny input.
• Fail fast when a circuit exceeds agreed limits for qubits, gates, depth, or shots.
• Store test results and logs when a job fails.

Do not treat a simulator result as proof of hardware performance. The purpose of this stage is to catch regressions in circuit generation and classical orchestration before a cloud submission is considered.

Scenario 2: Testing a provider adapter without credentials

When application code submits jobs to IBM Quantum, Amazon Braket, Azure Quantum, or another service, isolate the provider-specific layer behind a small interface. The rest of the application should not need to know how credentials are loaded, how a backend is selected, or how job status is polled.

• Mock the provider client's submission, status, result, and error responses.
• Test successful submission and result parsing.
• Test rejected circuits, unavailable backends, timeout responses, malformed results, and retry boundaries.
• Verify that the application does not submit a second job when a retry is unsafe or the first job may still be running.
• Use fixture responses that resemble the provider's documented response shape, while keeping the fixtures small and readable.
• Confirm that secrets are never written to logs, snapshots, exception messages, or uploaded artifacts.

Mocking is especially useful for testing the control plane. It does not validate provider availability or current backend restrictions. Keep provider-specific assumptions in one module so an SDK or authentication change does not require rewriting the entire test suite.

Scenario 3: Circuit and transpilation regression testing

A circuit can remain logically equivalent while its compiled form changes. If depth, two-qubit gate count, or measurement placement matters, add a resource test after transpilation for the target execution model.

• Compile a small, representative circuit using a pinned or explicitly selected compilation configuration.
• Record relevant metrics such as qubit count, circuit depth, total gate count, and two-qubit gate count.
• Set thresholds that describe acceptable behavior rather than arbitrary perfection.
• Use snapshots for stable intermediate representations only when the SDK exposes a representation suitable for review.
• Review snapshot changes as code changes; do not automatically update them in CI.
• Allow expected SDK-driven changes to be updated deliberately with a clear pull request explanation.

Resource estimation can help define meaningful thresholds. See Quantum Circuit Resource Estimation for the metrics that commonly affect execution planning.

Scenario 4: Scheduled hardware validation

Run real-backend tests separately from ordinary pull requests. A nightly, weekly, or manually approved workflow can check the path from circuit generation to cloud execution without making every code change depend on a QPU.

• Select one or two deliberately small circuits with clear expected properties.
• Use a backend allowlist rather than accepting arbitrary user input.
• Define a maximum shot count, runtime expectation, and retry policy.
• Record the SDK version, circuit identifier, backend identifier, compilation settings, submission time, and result metadata.
• Separate infrastructure failures from algorithmic failures in the report.
• Mark noise-sensitive tests as toleranced checks instead of exact equality assertions.
• Require human review before expanding the hardware test set or increasing resource limits.

A hardware test should be treated as an observation of a changing execution environment, not as a permanent binary truth. Compare results against a defined tolerance and retain enough context to explain a change.

What to double-check

Simulator choice and determinism

Confirm that the local simulator supports the circuit features your application uses, including measurements, noise models, custom gates, parameter binding, and multiple classical registers where relevant. A test that silently ignores an unsupported feature can create false confidence. Fix seeds for sampling-based tests, but also retain a small number of statistical tests when sampling behavior itself is important.

Limits before execution

Apply limits before invoking a costly simulation or provider call. Check qubit count, depth, total gates, two-qubit gates, shots, parameter combinations, and expected matrix or state-vector size. The right limit depends on the runner and simulator, so document the assumption in the repository. If a limit is exceeded, report the measured value and the allowed threshold in the CI output.

Secrets and permissions

Keep cloud credentials in the CI platform's secret store and expose them only to workflows that need them. Never place tokens in circuit fixtures, notebooks committed to the repository, command-line output, or failure artifacts. Use separate credentials or environments for scheduled tests where possible, and restrict the permitted provider, project, workspace, or backend according to the provider's current controls.

Failure artifacts

A failed quantum test is difficult to diagnose if CI preserves only a red status. Upload the test name, input parameters, SDK versions, transpiled circuit summary, resource metrics, simulator configuration, random seed where applicable, provider request identifier, and sanitized error message. Avoid uploading raw credentials or sensitive input data. If the circuit is generated dynamically, preserve a reproducible representation or a safe hash that lets the team identify the failing case.

Cost and quota boundaries

Make cloud submission an explicit pipeline stage. A useful guard is a dry-run mode that builds and validates the request without submitting it. Another is a job-count or shot-count assertion that fails before provider invocation. The Quantum Cloud Computing Cost Guide provides useful context for separating simulator, access, and hardware-run considerations.

Common mistakes

• Running hardware jobs on every commit: This increases latency and can make unrelated code changes depend on queue or service conditions. Keep hardware checks scheduled or approval-based.
• Asserting exact noisy results: Hardware counts can vary. Test distributions, tolerances, or invariant properties where appropriate.
• Using only one giant integration test: A failure that combines circuit construction, authentication, submission, polling, and parsing is hard to localize. Test each boundary separately.
• Snapshotting unstable output: Full serialized circuits may change across SDK versions or compiler settings. Snapshot only the representation your team intends to review.
• Leaving resource limits implicit: A test suite can become slow or expensive after a small change in qubit count or parameter grid. Make thresholds visible and enforce them early.
• Assuming simulator equivalence: Different simulators can model shots, noise, measurements, and unsupported operations differently. Record the simulator configuration and test the features that matter.
• Mixing credentials with test data: Keep authentication code, fixtures, and artifacts separate. Review CI logs as carefully as application logs.
• Ignoring the classical layer: In hybrid workflows, test optimizers, parameter binding, data encoding, retries, and result aggregation as ordinary software. The guide to building a hybrid quantum-classical workflow in Python can help structure these boundaries.

When to revisit

Review the pipeline whenever the underlying inputs change. At minimum, schedule a quarterly maintenance pass and revisit it before major planning or release cycles. Also review it immediately after:

• upgrading a quantum SDK, simulator, compiler, or Python runtime;
• changing CI runners, operating systems, caching, or dependency installation;
• switching cloud providers, projects, regions, authentication flows, or backends;
• adding a new gate, noise model, measurement pattern, encoding method, or parameterized circuit;
• changing shot counts, circuit-size limits, retry rules, or scheduled test frequency;
• seeing a hardware result that differs from simulator expectations;
• receiving a provider error that is not represented by a mock fixture.

Use this short review sequence: pin and record tool versions; run the local suite; inspect resource thresholds; verify mock responses against current provider documentation; confirm that secrets and backend allowlists still work; run the smallest approved hardware test; and archive the resulting artifacts. If the workflow has grown complex, document which checks are required for pull requests, which are scheduled, and which require human approval.

The practical goal is not to eliminate every difference between simulation and hardware. It is to catch ordinary regressions early, make cloud behavior observable, and reserve scarce or variable execution resources for tests that genuinely need them.