OnchainTestKit：链上应用端到端测试框架

使链上应用测试可靠且直接

介绍

测试去中心化应用一直与测试传统的 web 应用有根本的不同。传统的应用处理的是直接的 HTTP 请求和可预测的数据库状态，而链上应用必须驾驭区块链交互的复杂世界：钱包连接、交易批准、网络切换和链状态。每一个交互都带来了现有测试框架未被设计用于处理的独特挑战。

在为 Verified Pools 项目 编写端到端测试时，我们遇到了许多这样的挑战。这个复杂的 DeFi 应用将机构级的流动性基础设施带到了链上市场，需要对前端、后端和智能合约集成之间的复杂用户流程进行测试。例如，用户连接他们的钱包，批准 token 支出，签署 Permit2 消息，向池提供流动性，并在多个合约中管理他们的头寸。原本应该是一个简单的测试工作，却迅速变成了一个长达数周的技术挑战和生产力瓶颈的历程。

E2E 链上测试的核心挑战

测试去中心化应用引入了 web 自动化和区块链交互交叉处的复杂性。标准的端到端测试框架并非天生为此环境而构建，这迫使开发者在编写有效的测试之前解决几个根本问题。

根据我们的经验，有 4 个主要的测试障碍：

1. 钱包扩展设置 每一个测试都需要从头开始安装、配置和提供资金的浏览器钱包。这个过程对每个钱包（如 MetaMask 或 Coinbase Wallet）都是唯一的，并可能导致脆弱的自定义脚本。

2. 不可预测的钱包弹窗 在测试过程中，用户操作会触发钱包弹窗，用于交易批准、消息签名和网络切换。这些弹窗以不一致的时间和 UI 模式异步出现，导致不可预测性和不稳定性。

3. 共享链上状态 在共享区块链上，真正的测试并行是不可能的。当多个测试同时运行时，它们使用相同的钱包地址，并与同一区块链上的相同智能合约进行交互。这导致测试相互干扰，导致难以调试的不可预测的故障。

4. 合约部署和状态管理 在 Solidity 中的智能合约开发（使用 Foundry）和 TypeScript 中的端到端测试之间存在着一个根本的工具缺口。测试需要以特定的初始状态部署合约，但合约地址是不确定的，这破坏了与前端的连接。

OnchainTestKit 如何解决每个问题

OnchainTestKit 直接针对这四个关键问题，提供了专门构建的解决方案：

解决方案 1：自动钱包管理

OnchainTestKit 不是手动设置每种钱包类型，而是自动处理一切，提供了一个适用于所有钱包类型的统一接口。以下是如何使用 Coinbase Wallet 配置测试的示例：

// 使用本地节点和 coinbase 钱包配置测试
const coinbaseWalletConfig = configure()
  .withLocalNode({
    chainId: baseSepolia.id,
    forkUrl: process.env.E2E_TEST_FORK_URL,
    forkBlockNumber: BigInt(process.env.E2E_TEST_FORK_BLOCK_NUMBER ?? "0"),
    hardfork: "cancun",
  })
  .withCoinbase()
  .withSeedPhrase({
    seedPhrase: DEFAULT_SEED_PHRASE ?? "",
    password: DEFAULT_PASSWORD,
  })
  .withNetwork({
    name: "Base Sepolia",
    chainId: baseSepolia.id,
    symbol: "ETH",
    rpcUrl: "http://localhost:8545",
  })
  .build();

结果：对开发者友好，与钱包无关，且易于使用。我们将钱包设置和管理的所有复杂性都隐藏在开发者之外。

解决方案 2：可靠的钱包弹窗处理

OnchainTestKit 提供了一个统一的接口，抽象了所有弹窗的复杂性：

// 无需处理时间和弹窗检测：
await coinbaseWallet.handleAction(BaseActionType.CONNECT_TO_DAPP);
await coinbaseWallet.handleAction(BaseActionType.HANDLE_TRANSACTION, {
  approvalType: ActionApprovalType.APPROVE
});

await coinbaseWallet.handleAction(BaseActionType.CHANGE_SPENDING_CAP, {
  approvalType: ActionApprovalType.APPROVE
});

智能等待策略和重试：OnchainTestKit 使用智能等待策略，理解区块链的时间模式和钱包行为。内置的重试机制自动处理瞬时故障，而自适应超时则根据网络状况和弹窗复杂性进行调整。

结果：测试可靠地通过。不再有因时间问题或不可预测的钱包行为导致的不稳定测试。

解决方案 3：真正的测试隔离

OnchainTestKit 为每个测试提供其自己隔离的 Anvil 区块链节点，从而消除了所有状态冲突：

// 每个测试都获得其自己的 LocalNodeManager
test('parallel test A', async ({ localNodeManager, smartContractManager }) => {
  // 自动在可用端口上启动 Anvil 节点（例如，10543）
  // 此测试的交易仅影响其自己的区块链
  await page.click('#swap-button');
  // 测试逻辑...
});

test('parallel test B', async ({ localNodeManager, smartContractManager }) => {
  // 自动在不同的端口上启动单独的 Anvil 节点（例如，10847）
  // 完全独立的区块链状态
  await page.click('#approve-button');
  // 测试逻辑...
});

LocalNodeManager 的工作方式：OnchainTestKit 自动在进程之间分配可用的端口，并为每个测试启动隔离的 Anvil 节点。它支持三种不同的并行测试策略：

1. Fork 现有网络：在特定的区块高度 fork 一个测试网或主网，而无需部署合约。非常适合针对现有协议部署进行测试：

.withLocalNode({
  forkUrl: process.env.BASE_MAINNET_RPC_URL,
  forkBlockNumber: process.env.E2E_TEST_FORK_BLOCK_NUMBER,
  chainId: 8453
})

2. 清理本地状态：从一个全新的区块链开始，并部署所有依赖的合约。非常适合测试新的协议或复杂的状态设置：

.withLocalNode({
  chainId: 84532,
  // 无 fork - 从干净状态开始
})

// 然后通过 smartContractManager 部署合约

3. 混合方法：Fork 一个网络并在其上部署额外的测试合约。将真实的协议状态与自定义的测试合约相结合：

.withLocalNode({
  forkUrl: process.env.BASE_SEPOLIA_RPC_URL,
  forkBlockNumber: 10_000_000n,
  chainId: 84532
})

// 然后根据需要部署额外的测试合约

每种方法都提供了完全的测试隔离，具有独立的区块链状态，允许测试操纵时间、账户余额和合约状态，而不会影响其他测试。

智能 RPC 路由：关键的创新之一是自动请求拦截。你的前端可以始终使用固定的 RPC URL，例如 localhost:8545，而 LocalNodeManager 会自动将这些请求路由到每个测试的正确的 Anvil 节点。无需动态配置不同的端口——框架会透明地处理路由。

自动清理：LocalNodeManager 处理完整的节点生命周期，在每个测试完成后优雅地终止每个 Anvil 进程。这确保了没有资源泄漏或端口冲突，即使运行包含数十个并行节点的大型测试套件也是如此。

结果：完全并行化的测试，没有协调开销。CI 时间从数小时缩短到数分钟。

解决方案 4：确定性的合约部署

OnchainTestKit 使用 CREATE2 弥合了 Solidity/TypeScript 的差距，以实现确定性的合约部署：

await smartContractManager.setContractState({
  deployments: [\
    {\
      name: 'MockUSDC',\
      salt: '0x1234...', // 用于确定性地址的 CREATE2 salt\
      deployer: admin,\
      args: ['USD Coin', 'USDC', 6]\
    },\
    {\
      name: 'DEXContract',\
      salt: '0x5678...',\
      deployer: admin,\
      args: [mockUsdcAddress]\
    }\
  ],
  calls: [\
    { target: mockUsdcAddress, functionName: 'mint', args: [user, amount], account: admin },\
    { target: mockUsdcAddress, functionName: 'approve', args: [dexAddress, amount], account: user }\
  ]
});

CREATE2 的工作方式：OnchainTestKit 使用带有固定 salts 的 CREATE2 部署来确保合约始终部署到相同的地址。SmartContractManager 在部署之前预测部署地址，检查这些地址上是否已存在合约，并自动从你的 out/ artifact 目录加载 Foundry artifacts。这在你的 Solidity 合约和 TypeScript 测试之间创建了一个无缝的桥梁。

Foundry 集成：自动加载编译后的合约 artifacts，消除了合约和测试团队之间手动 ABI 管理或部署脚本协调的需要。

结果：可靠的合约测试，具有可预测的地址。从智能合约交互到 UI 反馈的完整用户旅程在所有测试运行中都保持一致。

我们如何在 Verified Pools 中使用 OnchainTestKit

以下是我们 Verified Pools 项目中的一个真实示例，展示了 OnchainTestKit 如何将复杂的链上应用测试转化为简洁、可读的测试：

// walletConfig/metamaskWalletConfig.ts
import { baseSepolia } from 'viem/chains';
import { configure } from '@coinbase/onchaintestkit';

export const DEFAULT_PASSWORD = 'PASSWORD';
export const DEFAULT_SEED_PHRASE = process.env.E2E_TEST_SEED_PHRASE;

// 用于具有 Base Sepolia fork 的 MetaMask 测试的可重用配置
const metamaskConfig = configure()
  .withLocalNode({
    chainId: baseSepolia.id,
    forkUrl: process.env.E2E_TEST_FORK_URL,
    forkBlockNumber: BigInt(process.env.E2E_TEST_FORK_BLOCK_NUMBER ?? '0'),
    hardfork: 'cancun',
  })
  .withMetaMask()
  .withSeedPhrase({
    seedPhrase: DEFAULT_SEED_PHRASE ?? '',
    password: DEFAULT_PASSWORD,
  })
  .withNetwork({
    name: 'Base Sepolia',
    chainId: baseSepolia.id,
    symbol: 'ETH',
    rpcUrl: 'http://localhost:8545', // 固定 URL，自动路由到正确的端口
  })
  .build();

export { metamaskConfig };

此测试涵盖了 Verified Pools 中的完整用户旅程：

1. 将 MetaMask 钱包连接到链上应用
2. 导航到 swap 界面
3. 输入 swap 金额 (0.0001 ETH)
4. 执行 swap 交易
5. 处理所有必需的钱包弹窗（支出上限批准、Permit2 签名、交易确认）
6. 验证 swap 是否成功完成

// swap.spec.ts

import { createOnchainTest } from '@coinbase/onchaintestkit';
import { NotificationPageType } from '@coinbase/onchaintestkit/wallets/MetaMask';
import { ActionApprovalType, BaseActionType } from '@coinbase/onchaintestkit/wallets/BaseWallet';
import { metamaskConfig } from './walletConfig/metamaskWalletConfig';

const test = createOnchainTest(metamaskConfig);
const { expect } = test;

test.describe('Verified Pools Swap', () => {
  test('connect wallet and swap @tx', async ({ page, metamask }) => {
    if (!metamask) throw new Error('MetaMask fixture is required');

    // 导航到 swap 界面
    await page.goto('/swap');

    // 连接钱包 - OnchainTestKit 处理所有复杂性
    await page.getByTestId('ockConnectButton').first().click();
    await page.getByTestId('ockModalOverlay')
      .first()
      .getByRole('button', { name: 'MetaMask' })
      .click();
    await metamask.handleAction(BaseActionType.CONNECT_TO_DAPP);
    await page.getByRole('button', { name: /^Accept$/ }).click();

    // 设置 swap
    const inputField = page.locator('input[placeholder="0.0"]').first();
    await inputField.fill('0.0001');

    // 执行 swap
    await page.getByRole('button', { name: 'Swap' }).click();
    await page.getByRole('button', { name: 'Confirm' }).click();

    // 处理支出上限批准 (Permit2)
    let notificationType = await metamask.identifyNotificationType();
    if (notificationType === NotificationPageType.SpendingCap) {
      await metamask.handleAction(BaseActionType.CHANGE_SPENDING_CAP, {
        approvalType: ActionApprovalType.APPROVE,
      });
      notificationType = await metamask.identifyNotificationType();
    }

    // 处理 Permit2 的签名
    if (notificationType === NotificationPageType.SpendingCap) {
      await metamask.handleAction(BaseActionType.HANDLE_SIGNATURE, {
        approvalType: ActionApprovalType.APPROVE,
      });
      notificationType = await metamask.identifyNotificationType();
    }

    // 处理实际的 swap 交易
    if (notificationType === NotificationPageType.Transaction) {
      await metamask.handleAction(BaseActionType.HANDLE_TRANSACTION, {
        approvalType: ActionApprovalType.APPROVE,
      });
    }

    // 验证 swap 完成
    await expect(page.getByRole('link', { name: 'View on Explorer' })).toBeVisible({
      timeout: 10_000,
    });
  });
});

这说明了：

• 无需自定义钱包设置：OnchainTestKit 自动处理 MetaMask 的安装和配置
• Fork 测试：测试针对真实的 Base Sepolia 网络在部署了所有依赖合约的特定区块高度运行，但每个测试都获得其自己隔离的 fork
• 可靠的弹窗处理：复杂的钱包交互简化为简单的 handleAction 调用
• 智能 RPC 路由：前端使用固定的 localhost:8545，框架路由到正确的测试节点
• 自动清理：无需手动资源管理

在 OnchainTestKit 之前，同样的测试将需要数百行自定义钱包自动化代码。现在它简洁、可读且可维护。

使用 OnchainTestKit 进行生产 CI/CD

以下是我们在 Verified Pools CI 管道中大规模运行这些测试的方式：

## .github/workflows/playwright.yml

jobs:
  e2e-tests:
    # 为了简洁起见，省略了其他设置步骤
    # 安装 xvfb 用于无头浏览器测试

    - name: Install xvfb
      run: |
        sudo apt-get update
        sudo apt-get install -y xvfb

    - name: Install dependencies
      run: yarn install --frozen-lockfile

    - name: Install Playwright Browsers
      run: yarn playwright install --with-deps

    - name: Build application
      run: yarn build
      env:
        NEXT_PUBLIC_BASE_SEPOLIA_RPC_URLS: http://localhost:8545

    - name: Prepare MetaMask Extension
      run: yarn e2e:metamask:prepare

    # 并行运行交易测试，使用 10 个 workers
    - name: Run Playwright TX tests with xvfb
      run: xvfb-run --auto-servernum --server-args="-screen 0 1280x960x24" yarn playwright test --workers=10 --reporter=list,github
      env:
        E2E_TEST_SEED_PHRASE: ${{ secrets.E2E_TEST_SEED_PHRASE }}

关键的生产功能：

• 并行执行：--workers=10 同时运行 10 个测试，每个测试都有隔离的区块链节点
• 环境隔离：每个测试都获得其自己的 Base Sepolia fork，没有冲突
• 强大的 CI 设置：使用 xvfb 处理无头浏览器自动化和适当的清理

结果：我们的 CI 在不到 10 分钟的时间内并行运行 100 多个全面的链上应用测试。

立即试用 OnchainTestKit

OnchainTestKit 现已可用，并已发布到 NPM。要开始使用，请查看 GitHub 仓库 中的文档和示例。

对改进链上开发者体验感兴趣？

如果你对增加链上开发者的影响力感兴趣，请了解我们的 Onchain DevX 团队很乐意与你见面！ 我们正在招聘。

• 原文链接： blog.base.dev/introducin...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～