测试覆盖说明

本页介绍 UnifiedQuantum 的测试体系：测试框架、文件组织、各模块的测试方式与覆盖范围，以及如何运行测试和 CI 集成。

什么时候进入本页

  • 你想知道项目有哪些测试、覆盖了哪些模块

  • 你在开发新功能，需要了解如何编写或运行测试

  • 你在排查问题，想确认某个模块是否有对应的测试

测试框架

  • 框架：pytest

  • 测试目录：uniqc/test/

  • 配置文件：pytest.ini（项目根目录）

测试函数命名规则（由 pytest.ini 中的 python_functions 配置）：

  • test_*：被 pytest 自动收集的标准测试

  • run_test_*：被 pytest 自动收集的测试入口（兼容历史命名）

运行测试

# 运行全部测试
pytest uniqc/test/ -v

# 运行全部测试，并包含会向真实云平台提交量子线路的测试
pytest uniqc/test/ -v --real-cloud-test

# 运行指定模块测试
pytest uniqc/test/test_simulator.py -v

# 运行测试并生成覆盖率报告
pytest uniqc/test/ --cov=uniqc --cov-report=term-missing -v

注意：部分随机回归测试（test_random_*）依赖 qiskit、qiskit-aer、qutip 等外部包，需额外安装。

真实云平台测试

真实云平台测试分两层：

  • @pytest.mark.cloud：需要真实 token、真实网络或平台 API。只读取后端列表、查询平台状态、验证 API key / proxy / connectivity 的测试属于这一类，默认必须执行。

  • @pytest.mark.real_cloud_execution：会向真实云平台提交量子线路并可能产生排队、额度或费用消耗。只有这类测试在默认运行时跳过，传入 --real-cloud-test 后执行。

默认运行：

pytest uniqc/test/ -v

这会执行 backend discovery、status、token/connectivity 等真实 API 测试，但跳过真实量子线路执行测试。

需要周期性验证真实执行路径时运行：

pytest uniqc/test/ -v --real-cloud-test

不要因为测试需要 API key、需要读取 backend list 或需要访问平台 status API 就标记为 real_cloud_execution。只有实际提交线路、轮询真实任务或读取该真实任务结果的测试才使用该 marker。Core developer 环境应配置可用的 ~/.uniqc/config.yaml token，让非执行类云测试默认通过。

逐模块测试覆盖

模块

测试文件

测试方式

覆盖范围

simulator

test_simulator.py

单元测试

噪声模拟器（NoisySimulator）statevector/density_matrix 后端计算正确性；含自定义错误模型测试

originir

test_originir_parser.py, test_random_OriginIR.py

单元测试 + 随机回归

解析器：随机生成 OriginIR → 解析 → 重建 → 模拟结果一致性验证；密度矩阵后端与 QuTip 对比

qasm

test_qasm_parser.py, test_random_QASM.py, test_random_QASM_measure.py, test_QASMBench.py

单元测试 + 随机回归 + Benchmark

QASM 解析与重建一致性；statevector/density_matrix 后端与 Qiskit 对比；shots 采样与 Qiskit 对比；QASMBench 兼容性验证

transpiler

test_transpile.py

单元测试

plot_time_line 脉冲序列可视化正确性

analyzer

test_result_adapter.py

单元测试

结果适配器工具函数基本验证

circuit_builder

test_general.py

集成测试

电路构建基本功能（iswap 等特殊门操作）

demos

test_demos.py

集成测试

示例代码（backend='dummy:local:simulator' 模式）端到端运行验证

各测试文件详细说明

test_simulator.py

测试模拟器的计算正确性，主要覆盖：

  • 噪声模拟器测试：构建含噪声量子线路，验证 NoisySimulator 在 statevector 和 density_matrix 两种后端下的结果

  • 自定义错误模型：测试 BitFlip、PhaseFlip、Depolarizing、TwoQubitDepolarizing、AmplitudeDamping 等预设错误模型

test_originir_parser.py

验证 OriginIR 解析器的正确性：

  • 随机生成 OriginIR 代码 → 解析为 Circuit 对象 → 重新导出 OriginIR → 比较两次模拟结果

  • 确保解析-重建往返（round-trip）不丢失语义信息

test_random_OriginIR.py

随机回归测试，与 QuTip 交叉验证：

  • 随机生成多门组合线路，分别用 UnifiedQuantum 和 QuTip 模拟

  • 比较 density matrix 结果的一致性

  • 支持含噪声线路的对比测试

test_qasm_parser.py

验证 QASM 解析器的正确性：

  • 随机生成 QASM 代码 → 解析 → 重建 → 模拟结果一致性验证

  • 与 OriginIR 解析器类似的 round-trip 测试策略

test_random_QASM.py

随机回归测试，与 Qiskit 交叉验证：

  • statevector 对比：UnifiedQuantum 与 Qiskit statevector 模拟结果对比

  • density matrix 对比：UnifiedQuantum density matrix 后端与 Qiskit 对比

  • QuTip 对比：density matrix 与 QuTip 结果一致性验证

test_random_QASM_measure.py

Shots 采样测试：

  • UnifiedQuantum 与 Qiskit 的 shots 采样结果对比

  • 验证测量概率分布的统计一致性

test_QASMBench.py

QASMBench 基准测试兼容性：

  • 加载 QASMBench 数据集（.pkl）

  • 解析、转译 QASM 电路并验证模拟结果

test_transpile.py

转译工具测试：

  • plot_time_line：验证脉冲序列 JSON 的解析和可视化

test_result_adapter.py

结果适配器工具函数的基本验证。

test_general.py

电路构建集成测试：

  • 验证 sx、xy 等特殊门操作

  • 基本的模拟器初始化和状态验证

test_demos.py

示例端到端测试：

  • Dummy 模式（submit_task(..., backend='dummy:local:simulator')）的完整工作流：创建配置 → 构建线路 → 提交任务 → 获取结果

  • 验证示例代码可正确运行

test_fake_backend.py（task_pipeline/）

Fake-backend 端到端测试，无需 API key 或云访问：

  • submit_task + get_result / wait_for_result 完整流水线

  • poll_result 非阻塞查询

  • submit_batch 批量提交与结果排序

  • OriginIR / QASM 字符串自动检测输入

  • Circuit.from_qasm() / Circuit.to_qasm() 序列化往返

  • 全目标门集（H, X, Y, Z, S, T, RX, RY, RZ, P, U1, U2, U3, CNOT, CZ, SWAP, CRX, CRY, CRZ, CP, CU, TOFFOLI）

  • qiskit.QuantumCircuit 自动转换

# 运行 fake-backend 测试（无需任何 API key）
pytest uniqc/test/task_pipeline/test_fake_backend.py -v

test_ibm_fake.py（task_pipeline/）

IBM 适配器本地测试，使用 qiskit fake provider（无需 IBM Quantum 凭证）：

  • IBMCircuitAdapter.adapt() 转换验证

  • 全目标门集适配

  • qiskit_adapter._normalize_qiskit_status 状态映射验证

# 运行 IBM fake 测试（需要 qiskit，无需 IBM 凭证）
pytest uniqc/test/task_pipeline/test_ibm_fake.py -v

CI 集成

项目有两套 CI workflow 涉及测试：

1. Build-and-test（build_and_test.yml）

  • 触发：push/PR 到 main

  • 环境：Ubuntu（gcc/clang）+ Windows（MSVC）

  • 内容：C++ 后端编译 + 构建验证

2. Pytest Coverage（pytest_coverage.yml）

  • 触发：push/PR 到 main

  • 环境：Ubuntu + Python 3.11

  • 内容：pytest uniqc/test/ --cov=uniqc -v

  • 产出：coverage.xml artifact

已知限制

  1. 外部依赖：随机回归测试需要 qiskit、qiskit-aer、qutip、scipy，不在默认安装范围内

  2. test_result_adapter / test_general：当前测试内容较简单，主要验证导入和基本功能，未覆盖全部 API

  3. transpiler 测试：仅覆盖 plot_time_line，未覆盖 qiskit_transpile 等转译功能

  4. task 模块：test_task_adapters.py 在 uniqc/test/ 中，但需要 mock HTTP，CI 环境可能不完整覆盖

未来改进方向

  • 补充 analyzer 模块的测试覆盖（expectation 计算、结果适配器完整 API）

  • 补充 transpiler 模块测试（qiskit 转译、电路绘制）

  • 增加 circuit_builder 的边界用例测试

  • 密度矩阵 bug 修复后取消 CI deselect

  • 引入 property-based testing（如 hypothesis）增强随机测试覆盖率