wagmi Mock Connector 详解：用假钱包打通 Ethereum 应用的连接、签名与多链测试

wagmi Mock Connector 详解用假钱包打通 Ethereum 应用的连接、签名与多链测试【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmiMock Connector 是 wagmi 官方提供的“测试替身”钱包它以固定的地址列表模拟真实浏览器钱包MetaMask 等的行为让连接connect、账号查询、消息签名、Typed Data 签名、链切换等钱包相关流程无需真实钱包即可跑通。读完本文你将掌握如何在createConfig中注册 mock connector、如何通过features特性开关精确编排各种成功/失败分支并能从 mock.ts 的源码理解它如何拦截和转发 EIP-1193 RPC 方法。定位与适用场景wagmi 的连接器Connector负责桥接应用与钱包。Mock Connector 的价值在于单元测试 / E2E 测试不依赖任何浏览器扩展稳定复现eth_requestAccounts、personal_sign、eth_signTypedData_v4等交互CI 环境真实钱包在持续集成中不可用mock 连接器提供了确定性的账号与响应错误分支演练通过features开关让connect、签名、切链等操作抛出UserRejectedRequestError验证应用的错误处理路径。从源码结构看mock 连接器是连接器工厂的完整实现它调用 createConnector 定义工厂函数该函数本质上是一个带完整类型约束的恒等函数真正的行为都在传入的对象里并实现了setup、connect、disconnect、getAccounts、getChainId、isAuthorized、switchChain、onAccountsChanged、onChainChanged、onDisconnect、getProvider等全套连接器接口见 mock.ts 第 76-159 行。安装与导入Mock Connector 同时从wagmi核心的connectors导出包和wagmi/connectors子路径导出。在 wagmi/connectors 的导出入口 中可以看到export { type MockParameters, mock, // ... } from wagmi/core因此两种导入方式等价文档推荐使用连接器包路径import { mock } from wagmi/connectors基础用法在 createConfig 中注册完整的最小配置示例如下来自 官方文档mainnet与sepolia为wagmi/chains内置链import { createConfig, http } from wagmi import { mainnet, sepolia } from wagmi/chains import { mock } from wagmi/connectors export const config createConfig({ chains: [mainnet, sepolia], connectors: [ mock({ accounts: [ 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266, 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, 0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC, ], }), ], transports: { [mainnet.id]: http(), [sepolia.id]: http(), }, })要点accounts是必填项类型约束为至少 1 个地址的只读元组readonly [Address, ...Address[]]见 MockParameters 定义mock.ts 第 27-40 行transports中的http()端点真实生效——mock 连接器并非凭空造数据未拦截的方法会经该 transport 的 URL 走真实 RPC详见下文“请求处理管线”setup阶段会把connectedChainId初始化为config.chains[0].idmock.ts 第 80-82 行即默认连接第一条配置的链。仓库自身测试也采用同样模式mock.test.ts 通过config._internal.connectors.setup(connectorFn)实例化连接器其中accounts直接取自 测试常量——该常量用助记词派生出 10 个确定性地址保证测试可重复。参数详解类型定义为MockParameters可通过import { type MockParameters } from wagmi/connectors引用export type MockParameters { accounts: readonly [Address, ...Address[]] features?: | { defaultConnected?: boolean | undefined connectError?: boolean | Error | undefined switchChainError?: boolean | Error | undefined signMessageError?: boolean | Error | undefined signTypedDataError?: boolean | Error | undefined reconnect?: boolean | undefined watchAssetError?: boolean | Error | undefined } | undefined }accountsreadonly [Address, ...Address[]]连接器使用的地址列表。所有eth_accounts/eth_requestAccounts响应、connect返回结果、getAccounts的返回值都来自它。示例import { mock } from wagmi/connectors const connector mock({ accounts: [ 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266, 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, 0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC, 0x90F79bf6EB2c4f870365E785982E1f101E93b906, 0x15d34aaf54267db7d7c367839aaf71a00a2c6a65, 0x9965507D1a55bcC2695C58ba16FB37d819B0A4dc, 0x976EA74026E726554dB657fA54763abd0C3a0aa9, 0x14dC79964da2C08b23698B3D3cc7Ca32193d9955, 0x23618e81E3f5cdF7f54C3d65f7FBc0aBf5B21E8f, 0xa0Ee7A142d267C1f36714E4a8F75612F20a79720, ], })features特性开关集合用于改变 wagmi 内部行为。boolean值表示“抛出一个通用的UserRejectedRequestError”传Error实例则原样抛出该错误。import { mock } from wagmi/connectors import { UserRejectedRequestError } from viem const connector mock({ accounts: [ 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266, 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, 0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC, ], features: { connectError: new UserRejectedRequestError(new Error(Failed to connect.)), reconnect: false, }, })各开关的语义均对应 mock.ts 中的实现开关类型作用defaultConnectedboolean连接器是否默认处于已连接状态默认false见 mock.ts 第 45-47 行 的默认值合并逻辑connectErrorboolean \| Error调用connector.connect时抛出错误第 83-88 行reconnectboolean是否启用重连。isAuthorized只有在features.reconnect为真且已连接且有账号时才返回true第 127-132 行signMessageErrorboolean \| Error调用personal_sign时抛出错误signTypedDataErrorboolean \| Error调用eth_signTypedData_v4时抛出错误switchChainErrorboolean \| Error调用connector.switchChainwallet_switchEthereumChain时抛出错误watchAssetErrorboolean \| Error调用wallet_watchAsset时抛出错误源码中存在此开关官方参数文档中未列出源码解析请求处理管线Mock Connector 的核心在getProvider它基于 viem 的customtransport 构造一个 EIP-1193 providerrequest函数按方法名分派mock.ts 第 159-336 行。分派顺序如下本地应答的 eth 方法eth_chainId直接返回当前connectedChainId的十六进制eth_accounts/eth_requestAccounts直接返回parameters.accounts。签名方法带错误开关eth_signTypedData_v4若features.signTypedDataError置位则抛错否则透传到 RPCpersonal_sign若features.signMessageError置位则抛错否则改写为eth_sign并交换参数顺序personal_sign的参数是[message, address]eth_sign是[address, message]见 第 315-327 行再走真实 RPC 用端点签名——这意味着transports中配置的链必须有可用的签名能力端点如测试网节点或 anvil。钱包方法wallet_switchEthereumChain受switchChainError控制成功后更新connectedChainId并触发onChainChanged使 wagmi 内部的链状态同步wallet_watchAsset受watchAssetError控制成功时返回connected布尔值wallet_getCapabilities返回固定形状的能力数据对特定 paymaster 地址报告sessionKeys.supported: true等第 204-223 行用于测试 ERC-7677 能力发现流程wallet_sendCalls/wallet_getCallsStatus实现 ERC-7683 批量调用Atomic Transactions语义——把每个 call 逐条以eth_sendTransaction发到 RPC收集哈希后以keccak256(JSON.stringify(calls))作为批量 ID 存入内存transactionCache查询状态时逐条取回执并组装WalletCallReceipt无回执则返回status: 100Pending有回执则返回status: 200第 225-310 行wallet_showCallsStatus空实现直接返回。兜底转发其余方法如eth_sign、eth_sendTransaction等原样rpc.http(url, { body })发送到该链 transport 的 HTTP 端点出错时包装成 viem 的RpcRequestError抛出。connect本身的流程第 83-112 行为先检查connectError→ 请求eth_requestAccounts拿账号 → 若请求了其他chainId则自动switchChain→ 置connected true→ 返回{ accounts, chainId }。当以withCapabilities: true调用时返回的 accounts 会是{ address, capabilities }形态——连接器在类型层面通过泛型withCapabilities让 TypeScript 推导出对应返回类型第 49-72 行这一点由 mock.test.ts 的 connect#withCapabilities 用例 做了运行时与类型双重验证。测试用例对行为的验证mock.test.ts 对关键行为做了快照级验证可作为预期行为的权威参照connectError分支features: { connectError: true }时connector.connect()抛出[UserRejectedRequestError: User rejected the request. Details: Failed to connect.]各签名/钱包方法的错误分支signMessageError、signTypedDataError、switchChainError、watchAssetError同时开启时对应的personal_sign、eth_signTypedData_v4、wallet_switchEthereumChain、wallet_watchAsset分别抛出带有Failed to sign message.、Failed to sign typed data.、Failed to switch chain.等 Details 的UserRejectedRequestError重连{ defaultConnected: true, reconnect: true }组合下connector.isAuthorized()解析为真值。这组用例表明defaultConnected只设置内部连接标志位isAuthorized的判定额外依赖reconnect开关两者需要按场景搭配使用。使用建议与限制签名依赖真实节点mock 连接器并不伪造签名结果personal_sign/eth_sign会转发到transports配置的真实 HTTP 端点测试环境通常应指向本地 anvil/foundry 节点等有签名能力的端点批量调用状态只存内存transactionCache是普通Map连接器实例销毁后状态即丢失跨进程测试需要重新发送watchAssetError的错误文案是Failed to switch chain.mock.ts 第 194-200 行 的提示信息复用了切链的文案断言该分支时注意 Details 文案switchChain只能切换到config.chains中已配置的链未配置时抛出SwitchChainError内含ChainNotConfiguredError第 133-143 行。相关文件索引官方文档site/shared/connectors/mock.md核心实现packages/core/src/connectors/mock.ts行为测试packages/core/src/connectors/mock.test.ts连接器工厂类型契约packages/core/src/connectors/createConnector.tswagmi/connectors导出入口packages/connectors/src/exports/index.ts测试用确定性账号常量packages/test/src/constants.ts各框架React/Vue/Solid的注册测试配置packages/register-tests/react/src/config.ts【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考