QUTest: A Native Testing Framework for Quantum Programs

TL;DR

QUTest is a native testing framework for quantum programs using OpenQASM 3, enabling standardized, compatible, and comprehensive testing directly on circuit files with various assertion types.

Contribution

It introduces a native testing framework that operates directly on .qasm files, integrating tests, assertions, and environment management in a compatible manner.

Findings

Supports 12 assertion types for diverse checks

Provides environment-aware and CI-compatible features

Available at https://github.com/QBugs/qutest

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.