> ## Documentation Index
> Fetch the complete documentation index at: https://initialabs-docs-aligning-interwovenkit-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Warning>
  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.
</Warning>

## 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.

```tsx theme={null}
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

<ParamField path="mnemonic" type="string">
  BIP-39 mnemonic phrase. Provide either `mnemonic` or `privateKey`.
</ParamField>

<ParamField path="privateKey" type="`0x${string}`">
  Hex-encoded private key with `0x` prefix. Provide either `mnemonic` or
  `privateKey`.
</ParamField>

<ParamField path="id" type="string" default="&#x22;testWallet&#x22;">
  Wagmi connector ID. Set this when running multiple test wallets in the same
  config.
</ParamField>

<ParamField path="name" type="string" default="&#x22;Test Wallet&#x22;">
  Display name shown in the wallet selection UI.
</ParamField>

<ParamField path="rpcUrls" type="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.
</ParamField>

<ParamField path="debug" type="boolean" default="false">
  When `true`, logs every RPC call to the console.
</ParamField>

<ParamField path="sendTransactionOverrides" type="{ 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).
</ParamField>

### 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

```ts theme={null}
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`](../components/interwovenkit-provider).

```tsx theme={null}
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

<ParamField path="mnemonic" type="string" required>
  BIP-39 mnemonic phrase used to derive Cosmos accounts.
</ParamField>

<ParamField path="name" type="string" default="&#x22;Test Cosmos Wallet&#x22;">
  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).
</ParamField>

<ParamField path="image" type="string">
  Wallet icon URL. Omit to show the default placeholder.
</ParamField>

<ParamField path="chains" type="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`).
</ParamField>

<ParamField path="debug" type="boolean" default="false">
  When `true`, logs signer creation to the console.
</ParamField>

### Return value

```ts theme={null}
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`](../components/interwovenkit-provider) for the
  `cosmosWallets` prop and the related `CosmosWallet` type.