Dogecoin 回归测试套件实战指南:基于 qa/pull-tester 与 qa/rpc-tests 的测试运行、依赖安装与用例编写

原创2026-09-21 09:40:511,761 阅读
文章标签:区块链

Dogecoin 回归测试套件实战指南:基于 qa/pull-tester 与 qa/rpc-tests 的测试运行、依赖安装与用例编写

导读

本文围绕 Dogecoin 仓库中的 qa/README.md 展开,系统讲解如何使用 qa/pull-tester/rpc-tests.py 驱动 qa/rpc-tests/ 下的 RPC 回归测试:包括环境依赖安装、单测/组合测试/全量套件/扩展套件的运行方式、每个测试可用的命令行选项、缓存机制的底层原理,以及如何基于测试框架编写新的回归用例。读完本文,你将能够在本地完整跑通 Dogecoin 的回归测试流水线,并具备独立编写 RPC 与 P2P 测试的能力。

一、回归测试体系的整体结构

Dogecoin 的测试体系由两层目录构成:

  • qa/pull-tester/:入口脚本层。rpc-tests.py 以子进程方式逐一调用 qa/rpc-tests/ 中的测试脚本,负责并行调度、超时统计、覆盖率汇总与结果输出;install-deps.sh 负责安装 Python 测试依赖。
  • qa/rpc-tests/:用例层。每个 *.py 文件是一个独立的回归测试用例,共享 test_framework/ 下的公共测试框架。

在 Dogecoin 的持续集成流程中,每一个提交到仓库的 Pull Request 都会被构建并完整跑一遍回归测试套件;开发者在本地也可以运行全部或任意单个测试,这与 CI 使用的入口完全一致。

二、测试依赖安装

运行测试前需要安装 python3-zmq 与 ltc_scrypt 两个依赖。其中 python3-zmq 用于 ZeroMQ 相关测试(如 zmq_test.py),ltc_scrypt 是 Dogecoin 验证脚本与部分测试所需的 Scrypt 算法 Python 实现。

Unix(Ubuntu / Debian)

sudo apt-get update
sudo apt-get install -y curl gcc python3-pip python3-setuptools python3-zmq
./qa/pull-tester/install-deps.sh

install-deps.sh 实际执行的动作是:从 ltc-scrypt 仓库下载 v1.0.1.tar.gz,用 sha256sum 校验其哈希(e866ade3...48ff0de),再通过 pip install --user 安装到当前用户目录,最后清理压缩包。如果你想离线安装或升级版本,可对照该脚本修改下载地址与哈希。

OS X

brew install curl
pip3 install pyzmq
./qa/pull-tester/install-deps.sh

关于 ZMQ 依赖的构建期开关

是否运行 ZMQ 测试还取决于编译期配置。rpc-tests.py 启动时会读取构建生成的 tests_config.py(configure 时由模板替换生成),其中 ENABLE_ZMQ、ENABLE_WALLET、ENABLE_UTILS、ENABLE_DOGECOIND 四个变量分别对应编译期是否启用了 ZMQ、钱包、工具链与 dogecoind 守护进程。从 rpc-tests.py 可以看到,只有当 Wallet、Utils、Dogecoind 三者全部启用时才会执行测试;若 ENABLE_ZMQ 开启但 import zmq 失败,脚本会直接报错并提示参阅 qa/README.md。

三、运行回归测试

3.1 运行单个测试

qa/pull-tester/rpc-tests.py <testname>

例如:

qa/pull-tester/rpc-tests.py wallet

注意:<testname> 可以省略 .py 后缀——rpc-tests.py 在匹配用例时会同时尝试 t in opts 与去掉 .py 后的名字,因此 wallet.py 与 wallet 等价。

3.2 运行多个测试的组合

qa/pull-tester/rpc-tests.py <testname1> <testname2> <testname3> ...

传入的每个名字会与基础套件(testScripts)和扩展套件(testScriptsExt)两个列表逐项比对,命中的用例才会被加入执行队列;如果没有命中任何用例,脚本会提示 No tests selected; do you have a typo in ...? 并退出。

3.3 运行完整回归套件

不带任何参数即运行默认基础套件(约 70 个用例,覆盖钱包、P2P 协议、区块、交易、REST、代理、多节点等场景):

qa/pull-tester/rpc-tests.py

3.4 运行扩展套件

qa/pull-tester/rpc-tests.py -extended

-extended 会把 testScriptsExt 中的长耗时用例(如 pruning.py、smartfees.py、maxuploadtarget.py、bip65-cltv.py、invalidateblock.py、forknotify.py 等)追加到基础套件之后一并执行。基础套件内部还按预估时长做了排序注释("longest test should go first"、"Tests less than 5m/2m/60s/30s"),以便并行调度时获得更好的负载均衡。

3.5 并行度与覆盖率

  • 默认情况下测试并行执行,可通过 -parallel=n 指定同时运行的作业数,默认 n=4:
    qa/pull-tester/rpc-tests.py -parallel=8
    
    并行调度由 RPCTestHandler 类实现:它维护一个运行中作业队列,用 subprocess.Popen 拉起 python3 <test>.py,每 0.5 秒轮询一次,先结束的作业先返回结果,并汇总每个用例的 PASSED/DURATION 及总耗时(见 rpc-tests.py)。若并发数大于 1 且用例多于一个,脚本会先调用 create_cache.py 预生成缓存,避免各并行作业重复同步区块数据。
  • 如需生成 RPC 接口的基础覆盖率报告,追加 --coverage:
    qa/pull-tester/rpc-tests.py --coverage
    

3.6 适用于每个单独测试的选项

以下选项会被 rpc-tests.py 原样透传给每个测试脚本(参数以 -- 开头的都会被收集进 passon_args,见 rpc-tests.py):

  -h, --help            show this help message and exit
  --nocleanup           Leave dogecoinds and test.* datadir on exit or error
  --noshutdown          Don't stop dogecoinds after the test execution
  --srcdir=SRCDIR       Source directory containing dogecoind/dogecoin-cli
                        (default: ../../src)
  --tmpdir=TMPDIR       Root directory for datadirs
  --tracerpc            Print out all RPC calls as they are made
  --coveragedir=COVERAGEDIR
                        Write tested RPC commands into this directory

各选项的实际行为在 test_framework.py 的 BitcoinTestFramework.main() 中有完整对应实现:

  • --srcdir:指向包含 dogecoind/dogecoin-cli 可执行文件的目录,默认相对测试框架所在位置解析为仓库 src/ 目录;该目录会被注入 PATH 环境变量,供测试启动节点时使用。
  • --tmpdir:测试数据目录的根目录,默认由 tempfile.mkdtemp(prefix="test") 创建;每个测试进程还会用 --portseed(默认取进程 PID)在根目录下再派生一个唯一子目录。
  • --tracerpc:开启后会把日志级别设为 DEBUG 并输出到 stdout,逐条打印测试发出的 RPC 调用。
  • --nocleanup:测试退出或报错后保留各节点的 dogecoind 数据目录,方便事后排查。
  • --noshutdown:测试结束后不停止 dogecoind 进程,用于调试时保留节点现场。
  • --coveragedir:把测试执行过的 RPC 命令写入该目录(详见下文覆盖率机制)。

3.7 调试输出

设置环境变量 PYTHON_DEBUG=1 可获得额外调试输出,典型用法:

PYTHON_DEBUG=1 qa/pull-tester/rpc-tests.py wallet

从 test_framework.py 可以看到,当启用了 PYTHON_DEBUG 且测试失败(或未清理)时,框架会遍历 node*/regtest/debug.log,把每个节点调试日志的最后 1000 行打印出来,用于定位 CI 上的偶发失败。

四、缓存机制:200 区块的 regtest 预生成链

首次运行回归测试时,框架会创建一条 200 个区块的 -regtest 区块链,并为四个节点各生成一个钱包,保存在 cache/ 目录下(即 qa/cache/,可通过 --cachedir 修改)。每个节点钱包中拥有 25 个成熟区块的产出(25*50=1250 DOGE,注释按 BTC 单位书写,实际币种以各用例断言为准)。

从 util.py 可以看到一个细节:缓存链默认不使用 mocktime,仅在需要同步 mempool 的用例中通过 enable_mocktime() 把时间锚定到 2014 年 1 月 1 日之后约 33.5 小时处,以规避 IBD 导致的 mempool 不同步问题。

首次运行之后,cache/ 中的区块链与钱包会被复制到临时目录,作为后续每次测试的初始状态,从而大幅缩短测试准备时间。这一复制逻辑由 initialize_chain() 在 util.py 中实现,缓存目录的预生成则通过 rpc-tests.py 在并行模式下调用 create_cache.py 完成(该脚本以 num_nodes = 0 运行,仅生成缓存而不实际启动节点)。

缓存损坏后的恢复

如果缓存或节点进程进入异常状态,按文档给出的方式恢复:

rm -rf cache
killall dogecoind

删除 cache/ 后,下次运行会重新生成完整缓存。

五、RPC 覆盖率报告的工作原理

--coverage 的底层机制在 coverage.py 中实现:

  1. AuthServiceProxyWrapper 包装 AuthServiceProxy,每次 RPC 调用完成后把方法名追加写入 coverage.pid<pid>.node<n>.txt 文件;
  2. 测试开始时,通过 dogecoin-cli help 输出解析出全部可用 RPC 命令清单,写入 rpc_interface.txt(每个目录只写一次);
  3. 全部用例结束后,RPCCoverage.report_rpc_coverage()(见 rpc-tests.py)把各测试累计调用过的命令与全量清单做差集,输出未被任何用例覆盖的 RPC 命令列表,若差集为空则打印 All RPC commands covered.。

这套机制让开发者可以直观地看到哪些 RPC 接口缺少测试覆盖,从而针对性补齐用例。

六、编写新的回归测试

仓库鼓励为新增或既有功能编写测试,测试框架与各用例的详细说明位于 qa/rpc-tests/README.md。所有用例共享 test_framework.py 中的基类 BitcoinTestFramework,其标准生命周期为:

  1. setup_chain():初始化临时目录;默认从缓存复制链与钱包(setup_clean_chain = False),也可置为 True 从零开始。
  2. setup_network():启动 num_nodes(默认 4)个节点,默认把节点连成 "chain" 拓扑(0-1、1-2、2-3),并支持 split=True 分裂成 0/1 与 2/3 两组以测试分叉与重组。
  3. run_test():实现具体断言逻辑,通过 self.nodes[i].<rpc方法>(...) 直接发起 RPC 调用。
  4. main():解析上述全部命令行选项,捕获 JSONRPCException、AssertionError 等异常,测试成功后清理临时目录并以退出码 0/1 表示通过/失败。

一个典型的 RPC 用例可参考 wallet.py:它继承 BitcoinTestFramework,用 self.nodes[0].generate(1) 挖块、getwalletinfo()/getbalance() 断言余额、lockunspent()/listlockunspent() 验证 UTXO 锁定,并用 assert_equal 校验每个中间状态。

P2P 测试的两种范式

qa/rpc-tests/README.md 还记录了 P2P 测试的两种框架:

  • Mininode(mininode.py):定义所有网络层对象(CBlock、CTransaction、msg_block、msg_tx 等)与 NodeConn 连接类。P2P 测试采用双线程模型——一个线程用 asyncore 处理与 dogecoind 的全部网络通信,另一个线程执行测试逻辑;实现一个继承 NodeConnCB 的回调类并传给 NodeConn 即可接收感兴趣的事件。测试中同样可以发起 RPC 调用。代表用例:p2p-acceptblock.py、maxblocksinflight.py。
  • Comptool(comptool.py):用于把被测 dogecoind 的区块/交易接收行为与 1 个或多个参考节点(或已知预期结果)进行对比。通过实现生成器函数 get_tests() 产出 TestInstance,每个实例由 [object, outcome, hash] 条目列表与 sync_every_block、sync_every_transaction 两个同步标志组成:object 可为 CBlock/CTransaction/CBlockHeader;outcome 为 True/False/None(None 表示比较所有被测节点对最佳链头的共识);hash 指定期望的链头哈希。使用单节点时可用 --testbinary 指定被测二进制,多节点时可用 --refbinary 指定 2 号及之后节点的参考二进制。代表用例:invalidblockrequest.py、p2p-fullblocktest.py。

端口分配与并发安全

多测试并行时,util.py 定义了 MAX_NODES = 8、PORT_MIN = 11000、PORT_RANGE = 5000,并通过 PortSeed(由 rpc-tests.py 以"时间戳取模 625"的伪随机偏移 + 用例序号生成)为每个测试进程计算互不冲突的 P2P 与 RPC 端口,避免并行作业互相干扰。

七、小结

Dogecoin 的回归测试体系以 qa/pull-tester/rpc-tests.py 为统一入口,串联起 qa/rpc-tests/ 下数十个覆盖钱包、区块、交易、P2P 协议、REST、ZMQ 等场景的用例。借助缓存机制与并行调度,开发者可以快速在本地复现 CI 的完整验证流程;借助 BitcoinTestFramework 基类与 Mininode/Comptool 两套 P2P 框架,也能以较低成本为新功能补充高质量回归用例。相关文档与源码索引:

登录后查看全文
dogecoin