Tendermint 测试体系全解析:单元测试、集成测试、E2E 混沌测试与模糊测试实战指南
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,集成测试在容器内覆盖以下内容:
- Go 测试(带
--race):竞态检测 + 测试覆盖率统计; - 应用测试(app tests):验证 ABCI 应用与节点的协同工作,具体组合为:
- kvstore 应用 over socket;
- counter 应用 over socket;
- counter 应用 over grpc;
- 持久化测试(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 共识鲁棒性的读者提供了可直接复现的实验环境。