We present the architectural design and prototype implementation of QUT (Quantum Unit Testing), a framework for unit testing of quantum subroutines. The framework is developed with a focus on usability and simplicity, making the complex theoretical concepts behind quantum unit testing accessible to a wide range of users with diverse backgrounds. This is achieved through the implementation of polymorphic probabilistic assertions, whose evaluation methods adapt to the data types of the arguments used in assertion statements, which may vary according to the context-dependent semantics of quantum subroutines. These arguments can be represented as qubit measurement outcomes, density matrices, or Choi matrices. For each type, the architecture integrates a specific testing protocol - such as quantum process tomography, quantum state tomography, or Pearson's chi-squared test - while remaining flexible enough to incorporate additional protocols in the future. The framework is built on the Qiskit software stack, providing compatibility with a broad range of quantum hardware backends and simulation platforms. Drawing on the reasoning provided by the denotational semantics of quantum subroutines, this work also highlights the key distinctions between quantum unit testing and its classical counterpart.
We present the architectural design and prototype implementation of QUT (Quantum Unit Testing), a framework for unit testing of quantum subroutines. The framework is developed with a focus on usability and simplicity, making the complex theoretical concepts behind quantum unit testing accessible to a wide range of users with diverse backgrounds. This is achieved through the implementation of polymorphic probabilistic assertions, whose evaluation methods adapt to the data types of the arguments used in assertion statements, which may vary according to the context-dependent semantics of quantum subroutines. These arguments can be represented as qubit measurement outcomes, density matrices, or Choi matrices. For each type, the architecture integrates a specific testing protocol - such as quantum process tomography, quantum state tomography, or Pearson's chi-squared test - while remaining flexible enough to incorporate additional protocols in the future. The framework is built on the Qiskit software stack, providing compatibility with a broad range of quantum hardware backends and simulation platforms. Drawing on the reasoning provided by the denotational semantics of quantum subroutines, this work also highlights the key distinctions between quantum unit testing and its classical counterpart.
Abstract Software testing is a critical component of the classical software development lifecycle, and this principle is expected to hold true for quantum software as it evolves toward large-scale production and adherence to industry standards. Developing and testing quantum software presents unique challenges due to the non-deterministic nature of quantum information, the high dimensionality of the underlying Hilbert space, complex hardware noise, and the inherent non-local properties of quantum systems. In this work, we propose a unifying theoretical framework based on probabilistic assertions, which encompasses several testing approaches—such as quantum tomography and statistical tests—for developing practical unit tests for quantum subroutines. The framework is built upon the semantic equivalence between quantum subroutines and parameterized quantum channels, as established in this work. To address the computational complexity associated with unit testing in quantum systems, we propose incorporating context-awareness into the testing process. The trade-offs between accuracy, state space coverage, and efficiency associated with the proposed theoretical framework for quantum unit testing have been demonstrated through its application to a simple three-qubit quantum subroutine that prepares a Greenberger–Horne–Zeilinger state, as well as to subroutines within a program implementing Shor’s algorithm.
Quantum computing has emerged as a promising field with the potential to revolutionize various domains by harnessing the principles of quantum mechanics. As quantum hardware and algorithms continue to advance, developing high-quality quantum software has become crucial. However, testing quantum programs poses unique challenges due to the distinctive characteristics of quantum systems and the complexity of multi-subroutine programs. This article addresses the specific testing requirements of multi-subroutine quantum programs. We begin by investigating critical properties by surveying existing quantum libraries and providing insights into the challenges of testing these programs. Building upon this understanding, we focus on testing criteria and techniques based on the whole testing process perspective, spanning from unit testing to integration testing. We delve into various aspects, including IO analysis, quantum relation checking, structural testing, behavior testing, integration of subroutine pairs, and test case generation. We also introduce novel testing principles and criteria to guide the testing process. We conduct comprehensive testing on typical quantum subroutines, including diverse mutants and randomized inputs, to evaluate our proposed approach. The analysis of failures provides valuable insights into the effectiveness of our testing methodology. Additionally, we present case studies on representative multi-subroutine quantum programs, demonstrating the practical application and effectiveness of our proposed testing principles and criteria.
Large language models (LLMs) have shown strong results in classical code generation and are increasingly used to write the unit tests that safeguard that code. Whether they can do the same for quantum software is less clear, because quantum programs are probabilistic, depend on numerical tolerances, and are judged by domain-specific checkers, so a well-formed test can still disagree with the benchmark's verdict. Existing quantum benchmarks measure whether a model produces a correct solution, but not whether its tests can distinguish correct implementations from faulty ones. We introduce QTestBench, a framework that evaluates LLM-generated quantum test suites against independent benchmark checkers, never treating the tests themselves as ground truth. For each task, QTestBench prompts models to produce syntactic, semantic, and behavioral tests, injects candidate solutions at runtime, and compares each test verdict with the checker's label under three validation cohorts, each answering a distinct diagnostic question. We benchmark five LLMs on eight PennyLane QHack challenges and ten Qiskit HumanEval tasks. Generated suites almost always execute, but discrimination lags behind: the best generator reaches a test quality of 0.71 on QHack and 0.34 on Qiskit HumanEval, so executability alone overstates test quality. Oracle-verified synthetic mutants stabilize bug-detection estimates when natural faulty solutions are scarce, as on three of ten Qiskit tasks that yield none. QTestBench offers a reproducible, cross-framework benchmark for the trustworthiness of LLM-generated quantum tests.
Errors in quantum programs are challenging to track down due to the uncertainty of quantum programs. Testing is, therefore, an indispensable method for assuring the quality of quantum software. Existing testing methods focus only on testing quantum programs with quantum circuits or single subroutines and, therefore, cannot effectively test quantum programs with multi-subroutines. In this paper, we first discuss several critical issues that must be considered when testing multi-subroutine quantum programs and point out the limitations and problems with existing testing methods. We then present a novel framework for testing multi-subroutine quantum programs that allow for both unit and integration testing. Our framework includes two novel test coverage criteria for the equivalent class partition of quantum variables to guide our testing tasks and techniques to test quantum programs with several common patterns. We also discuss how to generate test cases based on our framework. To evaluate the effectiveness of our testing framework, we implemented a tool called QSharpTester for testing Q\# programs with multiple subroutines. We used it to conduct experiments on hundreds of mutation programs deriving from seven original Q\# programs. The experimental results show that our testing methods can deal with broader types of quantum programs than existing ones and perform well on almost all faulty mutation programs.
Over the past few years, several quantum software stacks (QSS) have been developed in response to rapid hardware advances in quantum computing. A QSS includes a quantum programming language, an optimizing compiler that translates a quantum algorithm written in a high-level language into quantum gate instructions, a quantum simulator that emulates these instructions on a classical device, and a software controller that sends analog signals to a very expensive quantum hardware based on quantum circuits. In comparison to traditional compilers and architecture simulators, QSSes are difficult to tests due to the probabilistic nature of results, the lack of clear hardware specifications, and quantum programming complexity.This work devises a novel differential testing approach for QSSes, named QDiff with three major innovations: (1) We generate input programs to be tested via semantics-preserving, source to source transformation to explore program variants. (2) We speed up differential testing by filtering out quantum circuits that are not worthwhile to execute on quantum hardware by analyzing static characteristics such as a circuit depth, 2-gate operations, gate error rates, and T1 relaxation time. (3) We design an extensible equivalence checking mechanism via distribution comparison functions such as Kolmogorov–Smirnov test and cross entropy.We evaluate QDiff with three widely-used open source QSSes: Qiskit from IBM, Cirq from Google, and Pyquil from Rigetti. By running QDiff on both real hardware and quantum simulators, we found several critical bugs revealing potential instabilities in these platforms. QDiff’s source transformation is effective in producing semantically equivalent yet not-identical circuits (i.e., 34% of trials), and its filtering mechanism can speed up differential testing by 66%.
Quantum programs are often shared as OpenQASM 3 circuits, but tests are still written in host languages such as Python with Qiskit. We present QUTest, a native framework in which both programs and tests are standard .qasm files. Tests follow the Arrange / Act / Assert pattern, while configuration, runtime requirements, and assertions are encoded as pragma comments (//%), preserving compatibility with existing OpenQASM tools. QUTest provides 12 assertion types spanning deterministic, statistical, quantum-state, and structural checks, plus a linter and an environment-aware mode for running the same test across selected runtime versions in isolated environments. Its CLI supports automatic test discovery, runtime compatibility checks, and XML reports for continuous integration. We describe the pragma language, implementation, and a planned evaluation using coverage and mutation testing.
QUTest is available at https://github.com/QBugs/qutest.
Video demo: https://youtu.be/FvgvsiAXuW0.