Dogecoin 回归测试套件实战指南:基于 qa/pull-tester 与 qa/rpc-tests 的测试运行、依赖安装与用例编写
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=8RPCTestHandler类实现:它维护一个运行中作业队列,用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 中实现:
AuthServiceProxyWrapper包装AuthServiceProxy,每次 RPC 调用完成后把方法名追加写入coverage.pid<pid>.node<n>.txt文件;- 测试开始时,通过
dogecoin-cli help输出解析出全部可用 RPC 命令清单,写入rpc_interface.txt(每个目录只写一次); - 全部用例结束后,
RPCCoverage.report_rpc_coverage()(见 rpc-tests.py)把各测试累计调用过的命令与全量清单做差集,输出未被任何用例覆盖的 RPC 命令列表,若差集为空则打印All RPC commands covered.。
这套机制让开发者可以直观地看到哪些 RPC 接口缺少测试覆盖,从而针对性补齐用例。
六、编写新的回归测试
仓库鼓励为新增或既有功能编写测试,测试框架与各用例的详细说明位于 qa/rpc-tests/README.md。所有用例共享 test_framework.py 中的基类 BitcoinTestFramework,其标准生命周期为:
setup_chain():初始化临时目录;默认从缓存复制链与钱包(setup_clean_chain = False),也可置为True从零开始。setup_network():启动num_nodes(默认 4)个节点,默认把节点连成 "chain" 拓扑(0-1、1-2、2-3),并支持split=True分裂成 0/1 与 2/3 两组以测试分叉与重组。run_test():实现具体断言逻辑,通过self.nodes[i].<rpc方法>(...)直接发起 RPC 调用。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 框架,也能以较低成本为新功能补充高质量回归用例。相关文档与源码索引:
- 测试总入口文档:qa/README.md
- 用例与框架说明:qa/rpc-tests/README.md
- 测试调度脚本:qa/pull-tester/rpc-tests.py
- 依赖安装脚本:qa/pull-tester/install-deps.sh
- 测试框架基类:qa/rpc-tests/test_framework/test_framework.py
- 通用工具与端口分配:qa/rpc-tests/test_framework/util.py
- RPC 覆盖率工具:qa/rpc-tests/test_framework/coverage.py