从零开始写TUN调试单元测试

凌晨三点十七分，我的手机在床头柜上震得像个得了疟疾的闹钟。屏幕上是一连串来自交易所的推送，红绿交错，像一场无声的烟花。我眯着眼划开锁屏，看到那条让我瞬间清醒的消息——某个新上线的铭文代币，价格在十分钟内跌去了百分之七十三，链上数据显示，大量交易都经过了一个我从未见过的合约地址。

我翻身坐起来，打开笔记本，把那串地址扔进了一个调试器。屏幕上立刻弹出一行字：“TUN协议异常：非预期状态转换”。

这就是我写这篇博客的起点。不是因为我发现了什么惊天大秘密，而是因为我意识到，在这个人人都喊着“去中心化”、却连自己写的合约状态机都懒得测的时代，TUN（Token Utility Network，一个虚构的、用于处理跨链资产兑换的底层协议）的调试单元测试，已经成了加密世界里最后一道“手动挡”防线。今天，我就带你从零开始，用一场真实的“事故”作为引子，把TUN调试单元测试的骨架、血肉和神经，一层层拆开给你看。

事故现场：那个不存在的“退款”

让我们把时间拨回事故发生的四小时前。当时我正在写一个TUN协议的测试用例，场景很简单：用户A通过TUN网关，用10个ETH兑换了1000个USDT，然后因为汇率滑点超限，交易被回滚。按照协议设计，回滚后，用户的10个ETH应该原路退回，而且必须退回用户发起交易时的那个原始地址。

我写了一个单元测试，模拟了这个流程。测试代码里，我调用了TUNRouter.swapExactTokensForTokens，然后故意把链上预言机的价格拉高，触发滑点保护。一切看起来都很正常，直到我运行测试，控制台输出了一行让我瞳孔放大的日志：

[WARN] Refund address mismatch: expected 0xabc...123, got 0xdef...456

退款地址不匹配。也就是说，当交易回滚时，TUN协议把ETH退给了合约内部的一个临时地址，而不是用户A的原地址。如果这个bug被部署到主网，那么所有遭遇滑点的用户，他们的资产都会永久锁死在那个临时地址里——而那个地址的私钥，没有任何人拥有。

那一刻我后背有点发凉。这不是一个“功能未实现”的问题，而是一个状态管理的问题。TUN协议的核心逻辑是：在交易执行前，先将用户资产锁定在一个托管合约中；交易成功后，托管合约释放资产给接收方；交易失败后，托管合约将资产退回原地址。问题出在“退回原地址”这一步——我的测试环境里，托管合约在初始化时，把“原地址”记录为msg.sender，但实际在跨链调用场景下，msg.sender是TUN网关的合约地址，而不是用户的钱包地址。

这个bug之所以能逃过我的眼睛，是因为我之前的测试用例都太“干净”了——每个测试都是独立运行，没有模拟跨链调用时的msg.sender上下文。这就是我要讲的第一个知识点：单元测试不是“跑通就行”，而是要模拟真实世界的脏环境。

从零搭建：TUN调试单元测试的“三层肉”

第一层：最小可复现的“事故现场”

写TUN的单元测试，第一步不是写测试代码，而是搭一个“事故现场”。你需要一个本地的EVM模拟环境（比如Hardhat Network或者Anvil），然后部署三样东西：

1. 一个TUN路由器合约（TUNRouter.sol）——负责处理用户的兑换请求。
2. 一个TUN托管合约（TUNEscrow.sol）——负责锁定和释放资产。
3. 一个模拟的跨链预言机（MockPriceOracle.sol）——用于控制汇率，制造滑点。

我当时犯的错误是，直接用了Hardhat自带的ethers.getContractFactory来部署合约，然后没有设置from字段。这导致所有交易都默认从测试账户0发起，msg.sender永远是同一个地址。这就像你只在一个房间里测试消防警报，却从没想过走廊里着火是什么场景。

正确的做法是，在测试的beforeEach钩子里，显式地创建多个模拟账户，并且在每次调用TUN路由器的交易中，指定from为不同的用户。比如：

async function deployTUNFixture() { const [deployer, userA, userB, attacker] = await ethers.getSigners(); const priceOracle = await MockPriceOracle.deploy(); const escrow = await TUNEscrow.deploy(priceOracle.address); const router = await TUNRouter.deploy(escrow.address); // 关键：给userA和userB预置一些ETH和USDT await router.depositLiquidity({ value: ethers.utils.parseEther("100") }); await escrow.connect(userA).approve(router.address, ethers.constants.MaxUint256); return { router, escrow, priceOracle, userA, userB, attacker }; }

这个deployTUNFixture函数，就是你的“事故现场”。每次测试都从它开始，确保环境是全新的、可预测的。注意那个connect(userA)——如果你不写这个，你就是在用部署者的身份在测试，那测出来的结果毫无意义。

第二层：把“状态转换”钉死在测试矩阵里

TUN协议最复杂的地方在于它的状态机：闲置（IDLE） -> 锁定（LOCKED） -> 兑换中（SWAPPING） -> 成功（SUCCESS） / 失败（FAILED）。每一个状态转换，都必须有对应的单元测试。

但这里有个坑：很多人在写测试时，只测“正常路径”——从IDLE到SUCCESS。一旦遇到FAILED状态，就随便写个expect(...).to.be.reverted了事。这远远不够。你要测试的是状态转换的原子性。

我举一个具体的例子。在TUN协议中，当用户发起兑换时，托管合约会先调用一个内部函数_lockAssets()，把用户的ETH从用户地址转移到托管合约地址。然后，路由器会调用预言机获取价格，如果价格滑点超过阈值，则调用_refund()，把ETH退回用户。

我的测试用例应该覆盖以下矩阵：

| 测试场景 | 初始状态 | 触发动作 | 预期最终状态 | 关键断言 | | :--- | :--- | :--- | :--- | :--- | | 正常兑换 | IDLE | 调用swap | SUCCESS | 用户收到USDT，托管合约余额为0 | | 滑点回滚 | IDLE | 调用swap（价格被改动） | FAILED | 用户收到ETH，托管合约余额为0，退款地址正确 | | 重复兑换 | LOCKED | 再次调用swap | 必须revert | 防止重入攻击 | | 恶意价格 | IDLE | 预言机返回0或负数 | FAILED | 托管合约拒绝执行，且不锁定资产 |

这个矩阵里，最容易被忽略的是“恶意价格”那一行。你需要写一个测试，让预言机返回一个荒谬的价格（比如0），然后断言TUN协议不能进入LOCKED状态，因为一旦锁定了资产，而价格无效，协议就不知道该如何结算了。这个测试能帮你发现一个常见的逻辑漏洞：先锁资产后验证价格。正确顺序应该是先验证价格，再锁资产。

我当时写的那个bug，就是因为在_lockAssets之前没有检查msg.sender是否等于用户授权地址，导致退款时把资产退给了msg.sender（即路由器合约）。这个bug的根因，就是状态转换的顺序错了。

第三层：用“模糊测试”和“事件日志”来逼疯自己

单元测试写多了，你会发现一个规律：所有bug都藏在边界条件里。比如，当用户发送的ETH数量是0.0000001个（我们叫它“尘埃”），或者用户传入一个不存在的代币地址，或者用户试图在同一个区块内发起两次兑换。

对于这些边界情况，我强烈建议你引入模糊测试（Fuzz Testing）。Hardhat自带的loadFixture和ethers的parseEther可以帮你快速生成随机数据。但更重要的是，你要学会读取事件日志。

TUN协议在每次状态转换时，都会emit一个事件，比如AssetsLocked(address indexed user, uint256 amount)和RefundIssued(address indexed user, uint256 amount, bytes32 reason)。你的测试用例里，必须包含对事件参数的断言。

举个例子，我在写“滑点回滚”测试时，一开始只检查了用户余额是否恢复。但后来我加了一行代码：

await expect(tx) .to.emit(escrow, "RefundIssued") .withArgs(userA.address, ethers.utils.parseEther("10"), "SLIPPAGE_EXCEEDED");

这一行代码立刻暴露了问题：事件里记录的user是router.address，而不是userA.address。因为托管合约内部使用的是msg.sender来记录退款地址。这个发现让我把测试矩阵里“退款地址正确”那一行的断言从“余额相等”改成了“事件参数匹配”。记住：余额相等只是结果，事件参数才是过程。 如果你不检查事件，你永远不知道资产是从哪个门溜走的。

实战演练：复现那个凌晨三点的bug

现在，让我们回到文章开头的那个场景。我怀疑那个铭文代币的暴跌，是因为TUN协议的某个版本存在类似的退款地址漏洞。为了验证，我写了一个针对性的单元测试，模拟了“跨链调用”的上下文。

测试步骤是这样的：

1. 部署一个假的“跨链网关”合约，这个合约暴露一个executeRemoteSwap函数，函数内部调用TUN路由器的swap函数。注意，这个网关合约本身不是用户，它只是一个中间人。
2. 用户A调用网关合约，网关合约再调用TUN路由器。此时，TUN路由器看到的msg.sender是网关合约的地址，而不是用户A。
3. 触发滑点回滚，然后检查退款地址。

测试代码片段如下：

it("should refund to original user even when called via gateway", async function () { const { router, escrow, priceOracle, userA } = await loadFixture(deployTUNFixture); // 部署一个恶意网关，模拟跨链调用 const maliciousGateway = await MaliciousGateway.deploy(router.address);

// 用户A授权给网关，网关再调用路由器 await escrow.connect(userA).approve(maliciousGateway.address, ethers.constants.MaxUint256);

// 改变预言机价格，制造滑点 await priceOracle.setPrice(0); // 价格变为0，必然触发回滚

// 用户A通过网关发起兑换 const tx = await maliciousGateway.connect(userA).executeSwap( ethers.utils.parseEther("1"), { value: ethers.utils.parseEther("1") } );

// 断言事件中的退款地址是userA，而不是网关 await expect(tx) .to.emit(escrow, "RefundIssued") .withArgs(userA.address, ethers.utils.parseEther("1"), "INVALID_PRICE"); });

这个测试跑起来后，控制台立刻报错——事件中的user参数是maliciousGateway.address。原因和我之前发现的一样：TUN托管合约在记录“原地址”时，使用了msg.sender，而msg.sender是网关。这个bug在单用户直接调用时不会显现，但一旦通过任何中间合约调用，就会导致资产错位。

修复方案很简单：在TUN路由器的swap函数中，增加一个originalUser参数，并在调用托管合约时显式传入。托管合约内部，只信任路由器传过来的originalUser，而不是自己用msg.sender去猜。修复后，我的测试矩阵里新增了一行：“通过代理合约调用时，退款地址必须等于原始用户”。

调试的艺术：让测试替你说“不”

写完这些测试后，我关掉笔记本，窗外天已经蒙蒙亮。那个铭文代币的暴跌，最终被证实是另一个项目方跑路，跟TUN协议无关。但我的测试用例里，却多了一条宝贵的经验：永远不要信任msg.sender，永远要显式传递上下文。

TUN调试单元测试，本质上是一场“防御性编程”的演练。你写的每一个expect，都是在向未来的自己说：“不，这个值不能变。”你构造的每一个恶意场景，都是在向黑客说：“不，这条路不通。”

最后给你一个实用的检查清单，当你写完一组TUN测试后，问自己这几个问题：

• 我是否测试了通过中间合约调用的场景？
• 我是否检查了事件日志中的每一个参数，而不仅仅是余额？
• 我是否在状态转换的每一对组合上都写了断言（IDLE->LOCKED, LOCKED->FAILED, LOCKED->SUCCESS）？
• 我是否用了模糊测试来随机生成金额和地址？
• 我是否在测试中显式设置了from字段，而不是依赖默认账户？

如果你对这四个问题的答案都是“是”，那么恭喜你，你的TUN调试单元测试，已经比市面上百分之九十的DeFi项目要扎实了。剩下的百分之十，需要你在凌晨三点的手机震动声中，慢慢去补全。