Testing Helpers

Overview

createTestWalletConnector creates a wagmi-compatible, in-memory EVM wallet connector backed by a mnemonic or private key.
createTestCosmosWallet creates a Cosmos wallet entry that appears in the Bridge wallet picker, derived lazily per chain prefix from a mnemonic.
Use these helpers when you want deterministic wallet behavior in automated tests (Playwright, Cypress, Vitest) or local development without browser extensions or external wallet apps.

These helpers are intended for testing and local development only. They read raw mnemonics and private keys directly from your environment. Never ship them, or wallets created with them, with real user funds.

Prerequisites

Must run in a browser-like environment for the EVM connector because it is implemented as an injected wagmi connector.
Provide test credentials via environment variables (e.g. TEST_MNEMONIC, TEST_PRIVATE_KEY, TEST_COSMOS_MNEMONIC) — never hardcode them in source.

`createTestWalletConnector`

An EVM wallet connector that handles chain switching, message signing, and transaction submission entirely in memory. Standard contract interactions and RPC reads (gas estimation, receipts, etc.) are proxied to the chain’s RPC node.

import { createConfig, http } from 'wagmi'
import { mainnet } from 'wagmi/chains'
import { createTestWalletConnector } from '@initia/interwovenkit-react'

const testConnector = createTestWalletConnector({
  mnemonic: process.env.TEST_MNEMONIC!,
  // Or: privateKey: process.env.TEST_PRIVATE_KEY as `0x${string}`,
})

const wagmiConfig = createConfig({
  connectors: [testConnector],
  chains: [mainnet],
  transports: { [mainnet.id]: http() },
})

Config

string

BIP-39 mnemonic phrase. Provide either mnemonic or privateKey.

`0x${string}`

Hex-encoded private key with 0x prefix. Provide either mnemonic or privateKey.

string

default:"\"testWallet\""

Wagmi connector ID. Set this when running multiple test wallets in the same config.

string

default:"\"Test Wallet\""

Display name shown in the wallet selection UI.

Record<number, string>

CORS-friendly RPC URLs keyed by EVM chain ID. User-provided URLs override the built-in defaults (Ethereum mainnet, Arbitrum One, Base) for matching chain IDs.

boolean

default:"false"

When true, logs every RPC call to the console.

{ gas?: bigint; maxFeePerGas?: bigint; maxPriorityFeePerGas?: bigint }

Overrides applied to every eth_sendTransaction call. Useful for forcing failure scenarios in tests (e.g. { gas: 21000n } to trigger out-of-gas reverts on contract calls, or { maxFeePerGas: 1n } to land below the base fee).

Supported EIP-1193 methods

Method	Behavior
`eth_requestAccounts`, `eth_accounts`	Returns the derived account address
`eth_chainId`	Returns the current chain ID (hex)
`personal_sign`	Signs the message with the test account
`eth_signTypedData`, `eth_signTypedData_v4`	Signs raw bytes (not EIP-712 compliant — sufficient for InterwovenKit’s flows)
`wallet_switchEthereumChain`	Switches chain. Auto-registers from configured RPC URLs. Throws 4902 if unknown.
`wallet_addEthereumChain`	Registers a new chain with its RPC URL
`wallet_getPermissions`, `wallet_requestPermissions`	Returns the `eth_accounts` permission
`eth_sendTransaction`	Signs locally via viem and broadcasts to the RPC node
Any other method	Proxied to the current chain’s RPC node

Return value

function createTestWalletConnector(config: CreateTestWalletConfig): Connector

`createTestCosmosWallet`

Returns a CosmosWallet entry that appears in the Bridge wallet picker alongside Keplr and Leap. Pass it through the cosmosWallets prop on InterwovenKitProvider.

import {
  createTestCosmosWallet,
  InterwovenKitProvider,
  MAINNET,
} from '@initia/interwovenkit-react'

const testCosmosWallet = createTestCosmosWallet({
  mnemonic: process.env.TEST_COSMOS_MNEMONIC!,
})

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <InterwovenKitProvider {...MAINNET} cosmosWallets={[testCosmosWallet]}>
      {children}
    </InterwovenKitProvider>
  )
}

Config

string

required

BIP-39 mnemonic phrase used to derive Cosmos accounts.

string

default:"\"Test Cosmos Wallet\""

Display name shown in the Bridge wallet selection list. A matching name replaces the built-in wallet with the same name (e.g. naming this Keplr replaces the Keplr entry).

string

Wallet icon URL. Omit to show the default placeholder.

Record<string, { prefix: string }>

Override the bech32 prefix for specific chain IDs. By default the prefix is derived from the chain ID stem (e.g. noble-1 → noble). Use this for chains whose prefix differs from the stem (e.g. cosmoshub-4 → cosmos).

boolean

default:"false"

When true, logs signer creation to the console.

Return value

function createTestCosmosWallet(
  config: CreateTestCosmosWalletConfig,
): CosmosWallet

Notes

createTestWalletConnector accepts either a mnemonic or a privateKey, not both. Built-in CORS-safe RPCs are provided for Ethereum mainnet, Arbitrum One, and Base; pass rpcUrls to add or override others.
wallet_addEthereumChain does not auto-switch to the newly added chain, unlike MetaMask. Call wallet_switchEthereumChain afterwards to activate it.
eth_signTypedData and eth_signTypedData_v4 sign raw bytes rather than performing full EIP-712 encoding. InterwovenKit only relies on personal_sign for key derivation, so this is sufficient for its flows but signatures will not validate against on-chain EIP-712 verifiers (e.g. Permit2).
createTestCosmosWallet caches one signer per derived bech32 prefix, so repeated tests are deterministic and fast.
See InterwovenKitProvider for the cosmosWallets prop and the related CosmosWallet type.

InterwovenKit

Integrations

Features

API Reference

Overview

Prerequisites

`createTestWalletConnector`

Config

Supported EIP-1193 methods

Return value

`createTestCosmosWallet`

Config

Return value

Notes

​Overview

​Prerequisites

​createTestWalletConnector

​Config

​Supported EIP-1193 methods

​Return value

​createTestCosmosWallet

​Config

​Return value

​Notes

Overview

Prerequisites

`createTestWalletConnector`

Config

Supported EIP-1193 methods

Return value

`createTestCosmosWallet`

Config

Return value

Notes