Shardeum 网络级冒烟测试完全指南从环境准备到压测断言【免费下载链接】shardeumShardeum is an EVM based autoscaling blockchain项目地址: https://gitcode.com/GitHub_Trending/sh/shardeum本文是 ShardeumEVM 兼容、可自动扩容的区块链开源仓库中网络级集成测试Smoke Test的实战指南核心依据是仓库内的 test/README.md 运行说明并结合 test/main.test.ts.disabled 测试源码、test/testUtils.ts 工具库、jest.config.js 与 package.json 脚本逐一展开。读完本文你将掌握如何在本地拉起一条多节点 Shardeum 测试网、通过 Hardhat 压测工具向网络灌入 ETH 转账与 ERC20 代币转账交易、校验节点数据同步与归档节点数据一致性以及如何解读测试断言阈值并排查失败。一、先读懂这份 README四条核心步骤test/README.md用四条步骤浓缩了整个冒烟测试的运行流程原文如下SetSTART_NETWORK_SIZEto 5 (as an example) in shardeum/test/main.test.tsSetspam-clientlocated dir toSPAM_CLIENT_DIR. The load test command will be from that dir.Keep thejson-rpc-serverrunning in the backgroud before starting the unit test.Open terminal in shardeum directory and runnpm t.这四条步骤对应四个关键要素网络规模参数、压测客户端路径、后台常驻服务与测试入口命令。下面的章节将逐条展开并结合源码说明为什么这样配置以及配置值实际被谁读取。需要先说明一个重要事实当前仓库中shardeum/test/main.test.ts已被重命名为test/main.test.ts.disabledJest 不会加载.disabled后缀文件README 中提到的在 main.test.ts 中修改参数在操作时需要先将该文件恢复为.ts扩展名或参照 package.json 中的test:smoke脚本按参数方式运行。这一点在后续章节会给出两种可行的操作路径。二、冒烟测试定位它测的是整条链而不是单个函数仓库内的测试分为两套体系单元测试Unit Test位于 test/unit由jest.config.js中的roots: [rootDir/test/unit,rootDir/test/testCases]指定覆盖src/下各模块EVM、序列化、状态管理、存储、质押/惩罚交易等的独立逻辑网络级冒烟测试Smoke Test以 test/main.test.ts.disabled 为代表通过execa以 Shell 方式调用shardusCLI 真实拉起多条节点形成完整 P2P 网络再通过压测工具向网络注入真实交易最终通过 monitor-server 与 archiver 的 HTTP API 校验网络行为。test/main.test.ts.disabled的describe(Smoke Testing to the Shardeum Network, ...)块中依次包含 7 个测试覆盖启动网络 → ETH 转账压测 → ERC20 代币转账压测 → 全节点数据同步校验 → 启动新归档节点 → 归档数据一致性校验 → 清理网络。这是一条从造网到验网再到拆网的完整闭环是评估 Shardeum 分片网络在真实运行条件下基本健康度的关键手段。三、环境准备四类前置组件在修改任何测试参数之前请确保以下组件就绪1. shardus CLI网络生命周期管理测试通过execa.commandSync(shardus create ...)、shardus stop、shardus clean等命令创建/销毁本地节点实例对应test/main.test.ts.disabled第 28、34、162–166 行。相关能力来自shardeum-foundation/tools-shardus-cli见 package.json devDependencies。shardus create会在当前目录生成instances/目录存放各节点实例。2. monitor-server报告与活动节点查询测试通过http://localhost:3000见test/testUtils.ts中的MONITOR_HOST的/api/report、/api/flush接口查询活跃节点列表、注入/处理交易统计等。monitor-server 由shardeum-foundation/monitor-server提供测试前需随网络一同启动。3. json-rpc-serverJSON-RPC 网关README 第 3 步明确要求在启动测试前保持 json-rpc-server 在后台运行。原因在于压测工具spam-client / load-tester注入交易依赖 JSON-RPC 接口同时部分验证逻辑也需要通过 RPC 层观察交易执行结果。如果该服务未就绪压测命令将无法完成交易注入测试会因数据不足而失败。请以守护进程方式如 pm2 / nohup在后台常驻。4. spam-client / load-tester压测注入工具README 第 2 步要求设置spam-client所在目录。需要指出的是当前源码 test/main.test.ts.disabled 第 17 行实际使用的是变量名LOAD_TESTERconst LOAD_TESTER join(__dirname, ../../load-tester) // spam-client repo path即 README 中提到的SPAM_CLIENT_DIR对应代码中的LOAD_TESTER默认解析为shardeum仓库上一级目录下的load-tester目录join(__dirname, ../../load-tester)。该目录存放 Hardhat 工程package.json中存在hardhat load_test任务。若你的 spam-client 不在该默认位置需将LOAD_TESTER或按 README 命名为SPAM_CLIENT_DIR改为实际路径。test/testCases/transactions.ts中同样定义了LOAD_TESTER改动时需要保持两处一致。四、关键参数配置逐项说明1.START_NETWORK_SIZE网络节点规模在test/main.test.ts.disabled第 12 行const START_NETWORK_SIZE 5取值含义shardus create创建的目标节点总数。README 以 5 为例可依据机器资源调整下游影响waitForNetworkToBeActive(START_NETWORK_SIZE)test/testUtils.ts第 63 行会轮询 monitor-server 的/api/report直至活跃节点数 ≥ 该值才判定网络就绪后续压测 TPS 也以nodeCount * 2动态计算见下文超时约束jest.config.js中testTimeout: 5000000毫秒约 83 分钟注释明确指出节点越多需要的超时越长大网络规模下请勿随意调低此值。2.USE_EXISTING_NETWORK复用已有网络test/main.test.ts.disabled第 11 行const USE_EXISTING_NETWORK false。设为true时跳过shardus create直接查询当前已运行的活跃节点并校验数量是否等于START_NETWORK_SIZE设为false时先shardus stop、删除instances/再全新创建网络。调试阶段若不想反复重建网络可临时置为true。3. 压测参数在测试源码内动态生成test/main.test.ts.disabled第 57–58 行ETH 转账压测命令为npx hardhat load_test --type eth_transfer --tps ${nodeCount * 2} --duration ${durationSecond} --eoa ${nodeCount * 50} --validate true--tps目标吞吐按每节点每秒 2 笔计算nodeCount * 2--duration压测时长秒测试用例固定为 1 分钟60 * durationMinute--eoa参与转账的 EOA外部账户数量按nodeCount * 50计算--validate true开启交易校验。第 89–90 行ERC20 代币转账压测命令为npx hardhat load_test --type token_transfer --tps ${nodeCount * 2} --duration ${durationSecond} --contracts 5 --eoa ${nodeCount * 50} --validate true --deploytps 1与 ETH 转账相比新增两个参数--contracts部署并转账的 ERC20 合约数量此处为 5--deploytps合约部署的注入速率此处为 1 笔/秒避免大量部署交易挤占转账带宽。压测执行前会先调用utils.resetReport()请求 monitor-server/api/flush清空统计再await utils._sleep(10000)等待 monitor-server 重新收集活跃节点信息见test/testUtils.ts第 52–53 行。五、运行测试npm t与两条可行路径路径 A严格按 README 执行需恢复 main.test.ts将 test/main.test.ts.disabled 恢复为test/main.test.ts修改START_NETWORK_SIZE如 5与LOAD_TESTERspam-client 路径确保 json-rpc-server 后台运行在shardeum/目录执行npm t注意npm t即jest见 package.json 的test: jest会依据jest.config.js的roots扫描test/unit与test/testCases下的用例。若 main.test.ts 未被显式匹配到npm t实际跑的是单元测试而非冒烟测试——README 的写法隐含主测试文件已被 Jest 直接加载的前提因此建议优先采用路径 B。路径 B使用 package.json 内置的 smoke 脚本推荐package.json 已封装好带参数的冒烟测试命令npm run test:smoke对应脚本test:smoke: cross-env minNodes20 nodesPerConsensusGroup5 NODE_ENVDEBUG jest --detectOpenHandles --useStderr --coverage main.test.ts该脚本显式指定main.test.ts作为测试目标并预设minNodes20、nodesPerConsensusGroup5环境变量节点规模更大对机器资源要求更高可按需改成与START_NETWORK_SIZE匹配的值同时开启--detectOpenHandles检测未关闭的句柄避免进程挂起与--coverage覆盖率统计。若main.test.ts仍为.disabled状态需先恢复文件名。运行中的关键节奏源码内的时间等待test/main.test.ts.disabled中的等待逻辑是理解测试耗时来源的重点网络启动后waitForNetworkToBeActive先固定等待 60 秒_sleep(60000)之后按10 秒 × max(attempt/2, 1)递增轮询最多轮询START_NETWORK_SIZE * 3次test/testUtils.ts第 63–84 行每次压测结束后额外_sleep(durationMiliSecond 10000)其中额外 10 秒用于等待队列中的待处理交易被消费完第 63 行注释 extra 10s for processing pending txs in the queue归档节点同步测试前等待 60 秒第 130 行 needs to wait while new archiver is syncing data。六、测试断言解读如何判定通过test/main.test.ts.disabled中两个压测用例使用完全相同的断言逻辑第 66–71 行、第 97–103 行let processedRatio report.totalProcessed / report.totalInjected expect(processedRatio).toBeGreaterThanOrEqual(0.8) // 处理/注入比例 ≥ 80% expect(report.totalRejected).toBeLessThanOrEqual(report.totalInjected * 0.03) // 拒绝量 ≤ 注入量 × 3%其中report来自 monitor-server 的/api/reporttest/testUtils.ts第 17–21 行queryLatestReport。三条硬性校验标准为处理比例 ≥ 80%totalProcessed / totalInjected不得低于 0.8即网络必须消化绝大多数注入交易拒绝比例 ≤ 3%totalRejected不得超过注入总量的 3%全节点同步getInsyncAll()test/testUtils.ts第 105–131 行请求任意活跃节点的/get-tree-last-insync-all解析输出中inSync标记要求in_sync START_NETWORK_SIZE且out_sync 0。源码注释标注了 TBC: ... should be 80% or more 与 TBC: rejected should be less than 3%表明这两个阈值目前仍是待确认的工程约定值。运行时可结合节点规模与机器性能审慎解读。七、归档节点Archiver专项测试数据一致性校验冒烟测试的后半段聚焦归档节点的加入与数据同步第 115–159 行启动新归档节点执行shardus-network start --archivers 1随后waitForArchiverToJoin(localhost, 4001)通过查询原归档节点4000 端口的 cycle 记录确认新节点4001出现在joinedArchivers列表中总量一致性等待 60 秒同步后分别请求 4000 与 4001 的/totalData接口test/testUtils.ts第 58–61 行queryArchiverTotalData逐一比对totalCycles、totalAccounts、totalTransactions、totalReceipts四项计数深度数据比对在模块化用例test/testCases/archiver.ts中通过dataSyncTest开关启用逐 cycle 比对归档数据/cycleinfo/100、/receipt?startCycleendCycletypetally并使用Utils.safeStringify做深度序列化比较同时借助 scripts/accountsSyncCheck.ts 从共识节点与归档节点双向拉取账户列表检查任一方向是否存在对方有、本方缺的账户确保没有数据丢失。归档节点默认端口为 4000ARCHIVER_HOSTtest/testUtils.ts第 4 行新归档节点为 4001。八、模块化测试骨架testCases 目录除main.test.ts的整体式写法外仓库将冒烟测试拆分为可复用模块位于 test/testCases入口 test/testCases/index.ts 统一导出模块函数覆盖能力start.tsstartTest(START_NETWORK_SIZE, EXPECTED_ACTIVE_NODES)创建/复用网络并等待就绪transactions.tstransactionsTest(START_NETWORK_SIZE)ETH 转账与 ERC20 转账压测固定 TPSarchiver.tsarchiverTest(startNewAchiver, checkTotalDataCheck, dataSyncTest)归档节点加入、总量一致、深度数据比对nodeReward.tsnodeRewardTest()通过/nodeRewardValidate校验节点奖励正确发放到支付地址stop.tsstopTest()shardus stopshardus clean清理网络这套模块化设计便于组合出不同粒度的测试序列例如只验证启动 清理或启动 压测 归档。九、常见问题与排查要点npm t没有执行冒烟用例检查 jest.config.js 的roots与testMatch确认main.test.ts是否被匹配优先使用npm run test:smoke显式指定目标文件压测注入 0 笔交易确认 json-rpc-server 已在后台运行README 第 3 步并核对LOAD_TESTER指向的 spam-client 目录下npx hardhat load_test可正常执行网络永远无法 ActivewaitForNetworkToBeActive轮询的是 monitor-server/api/report请确认 monitor-server 已随网络启动且START_NETWORK_SIZE与shardus create实际创建的节点数一致测试超时jest.config.js的testTimeout为 5,000,000 ms若在低配机器上运行较大网络规模超时仍可能触发需降低START_NETWORK_SIZE或调高超时残留实例干扰测试启动阶段会执行shardus stop并rm -rf instancestest/main.test.ts.disabled第 28–33 行若历史进程残留可能导致清理失败可手动执行shardus stop后重试。十、相关文件速查运行说明test/README.md主测试用例test/main.test.ts.disabledREADME 所述 main.test.ts 的当前形态测试工具库test/testUtils.tsmonitor/archiver HTTP 交互、轮询等待、同步校验模块化用例test/testCases/start / transactions / archiver / nodeReward / stopJest 配置jest.config.jsroots、testTimeout、ts-jest 预设脚本定义package.jsontest、test:smoke等命令账户同步校验工具scripts/accountsSyncCheck.ts归档数据完整性比对单测入口test/unit与冒烟测试互补的单元测试体系按 README 四步流程完成配置后一条 Shardeum 测试网即可在本地完成建网 → 灌压 → 验同步 → 验归档 → 清理的完整生命周期验证为开发者评估分片网络的基本运行健康度提供可重复、可量化的基准。【免费下载链接】shardeumShardeum is an EVM based autoscaling blockchain项目地址: https://gitcode.com/GitHub_Trending/sh/shardeum创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考