Tendermint 测试体系全解析:单元测试、集成测试、E2E 混沌测试与模糊测试实战指南

原创2026-10-11 23:08:521,975 阅读
文章标签:区块链共识算法

Tendermint 测试体系全解析:单元测试、集成测试、E2E 混沌测试与模糊测试实战指南

本文系统梳理 Tendermint Core(BFT 共识引擎,Go 语言实现)的完整测试体系:从一条命令跑完的单元测试,到在 Docker 容器中验证 ABCI 应用与节点持久化恢复能力的集成测试,再到以 TOML 清单驱动、覆盖多种故障注入与拜占庭行为的端到端(E2E)测试网,以及针对 mempool、p2p、RPC 等模块的模糊测试(Fuzzing)。读完本文,你将掌握 Tendermint 各层测试的入口命令、测试清单的完整字段含义、故障注入与手动调试技巧,并能直接在本地仓库中复现整套测试流程。

测试体系总览:两条命令背后的分层结构

Tendermint 的测试体系以 test/README.md 为总入口,整体划分为两个层次:

  • 单元测试:即常规的 go test,通过 make test 一键执行;
  • 集成测试:通过 make test_integrations 执行,它会构建一个包含本地 Tendermint 版本的 Docker 镜像,并在容器中依次运行 Go 竞态测试、应用测试与持久化(崩溃恢复)测试。

这两条命令的底层编排位于仓库根目录的 tests.mk 中。以 make test 为例,其执行的是:

test:
	@echo "--> Running go test"
	@go test -p 1 $(PACKAGES) -tags deadlock

其中 -p 1 强制串行执行各包测试,-tags deadlock 会启用 libs/sync 中的死锁检测包装(deadlock.go),用于在测试阶段暴露潜在的锁竞争与死锁问题。make test_integrations 则是多条目标的串联:

test_integrations:
	make build_docker_test_image
	make tools
	make install
	make install_abci
	make test_cover
	make test_apps
	make test_abci_apps
	make test_abci_cli
	make test_libs

可以看到,一次集成测试会依次完成:构建测试 Docker 镜像(test/docker/Dockerfile)、安装工具链与 tendermint/abci-cli 二进制、运行带覆盖率的单测、运行应用测试、ABCI 应用/CLI 测试以及 libs 测试。test_cover 对应的 test/test_cover.sh 会遍历 github.com/tendermint/tendermint/... 下所有包,以 -race -covermode=atomic 方式执行并合并覆盖率为 coverage.txt。

集成测试:Docker 容器内的三类验证

集成测试的载体是 test/docker/Dockerfile 构建的 tester 镜像:它基于 golang:1.18,安装 jq、hexdump、killall、netcat、curl 等测试依赖,复制仓库代码后依次执行 make tools、make install_abci、make install,并用 tendermint testnet 预生成 4 个验证节点的测试网络数据(--v=4,节点目录前缀 mach)。

根据 test/README.md,集成测试在容器内覆盖以下内容:

  1. Go 测试(带 --race):竞态检测 + 测试覆盖率统计;
  2. 应用测试(app tests):验证 ABCI 应用与节点的协同工作,具体组合为:
    • kvstore 应用 over socket;
    • counter 应用 over socket;
    • counter 应用 over grpc;
  3. 持久化测试(persistence tests):在众多预定义的时间点逐个崩溃 Tendermint,重启后验证其能否与应用状态正确同步。

应用测试的完整执行脚本

应用测试的入口是 test/app/test.sh,它以 case 分支支持 5 种场景,并可全部执行:

case "$1" in
    "kvstore_over_socket") kvstore_over_socket ;;
    "kvstore_over_socket_reorder") kvstore_over_socket_reorder ;;
    "counter_over_socket") counter_over_socket ;;
    "counter_over_grpc") counter_over_grpc ;;
    "counter_over_grpc_grpc") counter_over_grpc_grpc ;;
    *) # 默认全部执行
esac

每个场景的套路一致:先用 tendermint init 初始化 TMHOME($HOME/.tendermint_app),随后以 abci-cli 启动应用进程、以 tendermint node 启动节点,睡眠数秒等待就绪后调用对应的断言脚本,最后 kill -9 清理进程。其中值得注意的两个变体:

  • kvstore_over_socket_reorder:先启动 Tendermint 再启动应用,验证节点在应用尚未就绪时也能稳定启动并随后连接成功;
  • counter_over_grpc_grpc:以 --abci grpc 启动应用与节点,并通过 --rpc.grpc_laddr tcp://localhost:36656 暴露 gRPC 广播接口,再以 GRPC_BROADCAST_TX=true 环境变量让断言脚本改用 grpc_client.go 发送交易。

断言脚本:kvstore 与 counter 的验证逻辑

kvstore_test.sh 验证 kvstore 应用的读写语义:通过 curl 调用 127.0.0.1:26657/broadcast_tx_commit 提交十六进制编码的 KEY=VALUE(如 abcd=dcba),随后用 abci-cli query 和 RPC 的 /abci_query 双重确认——既能查到 key 对应的 value,又不能把 value 当 key 查到,从而验证查询路径的正确性。

counter_test.sh 验证 counter 应用的 nonce 语义,其核心用例:

  • TX=00:第一次提交应进入区块且 deliver_tx 返回 code 0;
  • TX=00 再次提交:应被 mempool 拒绝(返回错误与非零 code);
  • TX=01:正常通过;
  • TX=03:能通过 check_tx 进入区块,但因 nonce 错误导致 deliver_tx 返回非零 code——区分了"mempool 检查"与"执行验证"两个阶段。

持久化测试:崩溃恢复验证

test/README.md 提到的持久化测试,在源码层面对应 consensus/replay.go 及其测试 consensus/replay_test.go。该机制在共识状态机的众多预设推进点注入崩溃,重启后通过 WAL(写前日志,见 consensus/wal.go)与应用状态比对,确保节点"从哪里跌倒就从哪里爬起来",与链上状态保持一致。这是对 Tendermint 崩溃一致性承诺(Crash Fault Tolerance)最直接的验证。

模糊测试(Fuzzing):针对系统输入的持续攻击

test/README.md 指出对"各种系统输入"进行模糊测试,细节记录在 test/fuzz/README.md。该目录基于 go-fuzz 库,覆盖以下输入面:

  • mempool 的 CheckTx(使用进程内 kvstore ABCI 应用);
  • p2p Addrbook#AddAddress;
  • p2p pex.Reactor#Receive;
  • p2p SecretConnection#Read / Write;
  • RPC JSON-RPC 服务器。

目录结构约定为:

| test
|  |- corpus/        # 语义合法的种子输入,引导 fuzzer 理解合法字节序列
|  |- crashers/      # 导致 panic 的输入(fuzzer 运行后生成)
|  |- suppressions/  # 被抑制的输入(fuzzer 运行后生成)
|  |- init-corpus/   # 生成 corpus 数据的脚本
|  |- testdata/      # 附加数据,如 addrbook.json
|  |- <testname>.go  # 单个 fuzz 目标

运行入口在 test/fuzz/Makefile:

make fuzz-mempool
make fuzz-p2p-addrbook
make fuzz-p2p-pex
make fuzz-p2p-sc
make fuzz-rpc-server

每个目标都会先生成/复用 corpus、编译出 *-fuzz.zip 归档并调用 go-fuzz。运行期间,一旦发现崩溃,crashers/ 目录会生成以输入哈希命名的三件套:原始崩溃字节文件(如 61bde465...)、崩溃报告(.output)与便于复现的 .quoted 文件。将该字节喂回对应的 Fuzz 函数即可复现并修复 bug。init-corpus 示例可参考 test/fuzz/p2p/addrbook/init-corpus/main.go。

端到端(E2E)测试:Docker Compose 驱动的多节点测试网

E2E 测试是 test/e2e/README.md 描述的"重武器":它根据一个 TOML 测试网清单(testnet manifest),在 Docker Compose 中拉起一整条 Tendermint 网络并对其施加交易负载、故障扰动与拜占庭行为。快速运行 CI 测试网:

make
./build/runner -f networks/ci.toml

其中 make 会通过 test/e2e/Makefile 依次构建 docker(e2e 节点镜像)、generator 与 runner 三个产物到 ./build/。-f networks/ci.toml 指定清单文件,测试网名称 ci 由清单文件名决定,工作目录落在 networks/ci/ 下。

测试网清单(Manifest)字段全解

清单的 Go 结构定义在 test/e2e/pkg/manifest.go,顶层字段包括:

字段 含义 默认值
ipv6 是否使用 IPv6 网络 IPv4
initial_height 创世区块初始高度 1
initial_state 应用初始 key/value 集合(写入创世) 无
validators 初始验证者集(节点名 → 投票权),显式置空则应用需在 InitChain 通过 validator_update.0 返回验证者集 所有 mode=validator 的节点,权 100
validator_update.<height> 指定高度返回给 ABCI 应用的验证者变更;高度 0 表示 InitChain 时返回;删除验证者需返回权 0 无
nodes 网络节点定义(至少一个) 必填
key_type 验证者密钥曲线:ed25519 / secp256k1 —
abci_protocol ABCI 通信协议:unix / tcp / grpc / builtin(builtin 将完整 Tendermint 节点编译进应用进程) builtin

每个节点(ManifestNode)的字段:

字段 含义 默认值
mode 节点类型:validator / full / light / seed;full 节点使用虚拟签名密钥,seed 节点启用 PEX 反应器 validator
seeds P2P 种子节点(节点名列表) 无
persistent_peers 持久连接节点列表;两者都未指定时默认为网络中其他所有节点(light 客户端则对应 provider) 其他所有节点
database 存储后端:goleveldb / cleveldb / rocksdb / boltdb / badgerdb goleveldb
privval_protocol 共识消息签名协议:file / unix / tcp;后两者由应用进程另起协程启动远程签名客户端,仅 validator 节点生效 file
start_at 节点启动的区块高度,runner 会等待网络到达该高度 0
fast_sync 快速同步模式:""(关闭)/ v0 / v1 / v2 关闭
mempool_version mempool 版本:v0 / v1 v0
state_sync 是否启用状态同步;要求网络中有节点设置了非零 snapshot_interval,且同步节点 start_at 落在快照可用高度 关闭
persist_interval 应用状态持久化的高度间隔;0 表示禁用持久化 1(每个高度)
snapshot_interval 状态同步快照的高度间隔 0(禁用)
retain_blocks 保留最近区块数,0 表示全保留;必须大于 persist_interval 与 snapshot_interval 0
perturb 故障扰动:disconnect(临时断连)/ kill(SIGKILL 后重启)/ pause(冻结)/ restart(SIGTERM 重启) 无
misbehaviors 指定高度下的拜占庭行为,如 { 10 = "double-prevote", 20 = "double-prevote" },行为清单见 test/maverick/consensus/misbehavior.go 无

上述参数的实际组合可见 CI 使用的 test/e2e/networks/ci.toml:它通过 initial_height = 1000、validator_update 动态变更验证者集,并让 validator02/03/04/05 分别使用 boltdb、badgerdb、rocksdb、cleveldb 后端,同时组合 abci_protocol = "builtin"/"tcp"、privval_protocol = "unix"/"tcp"、fast_sync、state_sync、mempool_version 以及 disconnect/restart/kill/pause 各类扰动和 double-prevote 拜占庭行为——用单张网络覆盖最广的功能面。最简单的清单见 test/e2e/networks/simple.toml(4 个 validator 节点)与 test/e2e/networks/single.toml(单节点)。

随机测试网生成与批量运行

generator 可生成"随机但确定性"的测试网组合:

./build/generator -d networks/generated/

# 按文件名分成 8 组
./build/generator -g 8 -d networks/generated/

其随机逻辑见 test/e2e/generator/random.go,通过 uniformChoice(均匀随机)与 weightedChoice(加权随机)在合法参数空间中采样。生成的多个测试网可用 test/e2e/run-multiple.sh 串行执行:

./run-multiple.sh networks/generated/gen-group3-*.toml

该脚本会对每个清单运行 runner;若某个测试网失败,会打印其清单并 dump 容器日志,但继续运行其余测试网,最终汇总失败列表并返回非零退出码。

runner 的 8 个阶段与辅助命令

test/e2e/README.md 列出 runner 的完整阶段,均可显式执行:./build/runner -f <manifest> <stage>:

  • setup:生成配置文件与测试网目录;
  • start:启动 Docker 容器;
  • load:向测试网节点施加交易负载;
  • perturb:执行清单中声明的扰动(节点重启、断连等);
  • wait:等待若干区块产出,并等待所有节点追上该高度;
  • test:在运行中的测试网上对每个节点执行 test/e2e/tests 下的测试用例;
  • stop:停止 Docker 容器;
  • cleanup:删除配置文件与 Docker 容器/网络。

辅助命令:logs(输出全部节点日志)、tail(跟踪节点日志直至取消)。不指定阶段直接运行 runner 时,会按 test/e2e/runner/main.go 中 RunE 的顺序完整编排:Cleanup → Setup → Load(后台)→ Start → Wait → Perturb → Wait → Test → Cleanup,--preserve 标志可保留运行中的测试网便于事后排查。

测试用例:testNode 并行机制与手动运行

测试用例以普通 Go 测试写在 test/e2e/tests(如 app_test.go、block_test.go、evidence_test.go、net_test.go、validator_test.go)。核心辅助函数 testNode(定义于 test/e2e/tests/e2e_test.go)将回调作为并行子测试对网络中每个节点执行:若设置了 E2E_NODE 环境变量则只测试该节点,否则测试全部节点(Stateless() 节点跳过)。

手动运行测试网中的测试用例:

./build/runner -f networks/ci.toml start
E2E_MANIFEST=networks/ci.toml go test -v ./tests/...

E2E_MANIFEST 指定清单路径;未设置时测试会被跳过(t.Skip("E2E_MANIFEST not set, ...")),从而不影响常规单测运行。E2E_NODE 可进一步限定单个节点。这些环境变量也可写死在 test/e2e/tests/e2e_test.go 的 init() 中,便于从 IDE 直接运行:

func init() {
	os.Setenv("E2E_MANIFEST", "networks/ci.toml")
	os.Setenv("E2E_NODE", "validator01")
}

失败排查:日志、日志级别与 pprof

若某个命令或测试失败,runner 只会以错误信息和非零状态码退出,测试网保持运行,数据留在测试网目录中。排查手段:

  • docker ps / docker logs <NODENAME> 直接查看容器;
  • ./build/runner -f <manifest> logs 或 tail 输出节点日志;
  • 排查完毕用 ./build/runner -f <manifest> cleanup 关停并清理;
  • 若默认 log_level 不够详细(例如需要对某些模块开启 debug),可在清单中调整。

每个节点还暴露一个 pprof 服务器(端口 6060),先用 docker port <NODENAME> 6060 找到映射到宿主机的端口,再执行各类 profile 抓取:

export PORT=$(docker port full01 6060 | awk -F: '{print $2}')

go tool pprof http://localhost:$PORT/debug/pprof/goroutine
go tool pprof http://localhost:$PORT/debug/pprof/heap
go tool pprof http://localhost:$PORT/debug/pprof/threadcreate
go tool pprof http://localhost:$PORT/debug/pprof/block
go tool pprof http://localhost:$PORT/debug/pprof/mutex

启用 IPv6

Docker 默认不启用 IPv6。需要在 daemon.json 中配置(Docker for Mac 用户可在 Preferences → Docker Engine 中编辑):

{
  "ipv6": true,
  "fixed-cidr-v6": "2001:db8:1::/64"
}

测试网基准测试

benchmark 命令用于对测试网做简单性能基准,它管理全流程:搭建环境、启动测试网、等待 100 个区块产出,然后基于采样区块计算并输出:

  • 平均出块时间(Mean Block Interval);
  • 出块时间标准差(Standard Deviation);
  • 最小/最大出块时间(Min/Max Block Interval)。

其实现见 test/e2e/runner/benchmark.go:从第一个归档节点(ArchiveNodes()[0])拉取连续 benchmarkLength(默认 100)个区块头,计算相邻区块时间戳间隔后统计均值、标准差、最值,并打印如下的结果块:

Benchmarked from height 101 to 200
	Mean Block Interval: 1.02s
	Standard Deviation: 0.030000
	Max Block Interval: 1.1s
	Min Block Interval: 0.98s

基准期间不执行任何扰动(参见 test/e2e/runner/main.go 中 benchmark 命令的说明)。

运行单个节点:builtin 与 socket 两种模式

E2E 框架面向多节点 Docker 测试网,但在部署大型地理分散测试网时也支持单节点运行。

Builtin 模式(应用内嵌节点):

make node
tendermint init validator
TMHOME=$HOME/.tendermint ./build/node ./node/built-in.toml

其中 make node 用 -tags badgerdb,boltdb,cleveldb,rocksdb 构建内嵌多种数据库后端的 node 二进制。更简化的方式是直接让 e2e 应用跑在 tendermint 二进制内:

tendermint start --proxy-app e2e

不过这种方式的灵活度不如前者。

Socket 模式(独立应用进程 + 独立节点):

make node
tendermint init validator
tendermint start
./build/node ./node.socket.toml

节点应用配置(built-in.toml 与 socket.toml)包含 snapshot_interval、persist_interval、chain_id、protocol、listen 等字段,完整字段定义与校验逻辑见 test/e2e/node/config.go——其中 chain_id 必填、protocol != "builtin" 时 listen 必填。

拜占庭测试节点 Maverick:注入共识恶意行为

test/e2e/pkg/manifest.go 中 misbehaviors 字段引用的行为定义在 test/maverick(说明见 test/maverick/README.md)。Maverick 是一个拜占庭节点,用于在共识层注入多种故障行为,检验 Tendermint 网络对恶意节点的反应,也可配合不同网络拓扑做模糊测试。

核心抽象是 Misbehavior 结构,它允许在以下 6 个阶段分别覆盖节点行为(见 test/maverick/consensus/misbehavior.go):

type Misbehavior struct {
	Name string

	EnterPropose    func(cs *State, height int64, round int32)
	EnterPrevote    func(cs *State, height int64, round int32)
	EnterPrecommit  func(cs *State, height int64, round int32)
	ReceivePrevote  func(cs *State, prevote *types.Vote)
	ReceivePrecommit func(cs *State, precommit *types.Vote)
	ReceiveProposal func(cs *State, proposal *types.Proposal) error
}

创建新行为的方式是:基于 DefaultMisbehavior() 派生一个函数,覆盖其中一个或多个回调,然后注册进行为列表:

var MisbehaviorList = map[string]Misbehavior{
	"double-prevote": DoublePrevoteMisbehavior(),
}

仓库内置的 DoublePrevoteMisbehavior 会在同一高度和轮次内既对区块投 prevote 又对 nil 投 prevote,并向对等节点分别发送两种冲突投票(见 misbehavior.go 中的实现)。构建与使用 Maverick:

go build          # 在 test/maverick 目录下
maverick init     # 初始化单节点
maverick node --proxy_app persistent_kvstore --misbehaviors double-vote,10

上例使节点在高度 10 的每一轮都投两次票;要追加更多行为,以逗号分隔继续追加 行为,高度 对即可。Maverick 的完整节点实现位于 test/maverick/node/node.go,其共识部分复用并修改自 consensus 包。

负载生成与延迟分析工具 loadtime

test/loadtime/README.md 介绍的 loadtime 工具集用于向 Tendermint 生成交易负载并测量交易延迟:load 生成的交易内嵌了生成时的时间戳与负载参数元数据,report 则基于区块内执行时间戳之差计算延迟指标。

构建与使用:

make build        # 产出 ./build/load 与 ./build/report

# 对 localhost:26657 的 websocket 施加负载:1 连接、10 秒、1000 TPS、1024 字节交易、sync 广播
./build/load \
    -c 1 -T 10 -r 1000 -s 1024 \
    --broadcast-tx-method sync \
    --endpoints ws://localhost:26657/websocket

# 从 goleveldb 数据目录计算延迟指标(最小/最大/平均/标准差)
./build/report --database-type goleveldb --data-dir ~/.tendermint/data

# 输出原始数据到 CSV,便于用更强的工具做聚合分析
./build/report --database-type goleveldb --data-dir ~/.tendermint/data --csv out.csv

report 按 load 启动时生成的 UUID 区分每次实验,并同时输出该次实验使用的参数值。其负载格式定义在 test/loadtime/payload/payload.proto,指标计算逻辑见 test/loadtime/report/report.go。

小结:从单测到混沌测试的完整链路

Tendermint 的测试体系呈现清晰的金字塔结构:make test 提供带死锁检测的单元测试;make test_integrations 在 Docker 容器中叠加竞态检测、覆盖率、ABCI 应用语义与崩溃恢复验证;E2E 框架用一份 TOML 清单即可组合验证者动态更新、多数据库后端、多种 ABCI/签名协议、故障扰动与拜占庭行为;Maverick 与 loadtime 分别补足恶意行为注入和性能基准能力;模糊测试则持续守护 mempool、p2p 与 RPC 的输入解析边界。这套体系既适合开发者提交前自测,也为研究 BFT 共识鲁棒性的读者提供了可直接复现的实验环境。

登录后查看全文
tendermint