QUTest: A Native Testing Framework for Quantum Programs

2026-05-19

AI Summary

Although quantum programs are commonly shared in OpenQASM 3 format, testing still relies on host languages and lacks a native, unified solution. This work proposes QUTest—the first purely OpenQASM 3-native testing framework—that unifies program code and test logic within a single .qasm file using the Arrange/Act/Assert pattern. Test configurations, runtime requirements, and assertions are embedded via pragma annotations. QUTest supports twelve assertion types, covering deterministic, statistical, quantum state, and structural checks, and enables environment-aware multi-version testing. It provides a command-line interface for automatic test discovery, continuous integration support, XML reporting, and a linter tool, all while maintaining compatibility with existing quantum toolchains. Together, these features establish a comprehensive native testing infrastructure for quantum software development.

Abstract

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.

Problem

• quantum programs
• OpenQASM
• testing framework
• native testing
• quantum software

Innovation

• native testing framework
• OpenQASM 3
• quantum program testing
• pragma-based assertions
• environment-aware testing