Introduction & Philosophy
Relevant source files
The following files were used as context for generating this wiki page:
The @wonderland/walletless library is a lightweight, high-performance E2E (End-to-End) testing solution for Web3 Decentralized Applications (DApps). It provides a virtual EIP-1193 provider that acts as a "man-in-the-middle" between the DApp UI and the Ethereum network. By virtualizing wallet interactions and localizing signing logic, it eliminates the overhead of browser extensions like MetaMask, enabling deterministic and significantly faster testing cycles.
Sources: README.md:1-12, package.json:2-6
The core philosophy centers on maintaining 100% chain realism while providing developers with total control over the wallet environment. It is designed to be framework-agnostic, working seamlessly with tools like Cypress, Playwright, or Vitest, and integrates natively with the Wagmi/Viem ecosystem.
Sources: README.md:27-35, src/provider.ts:103-110
Core Architecture: The Man-in-the-Middle Pattern
The system architecture is built around a request-routing logic that bifurcates EIP-1193 RPC calls into three distinct categories: Read, Write, and Wallet/State methods.
Request Routing Logic
The provider intercepts all request calls and determines the destination based on the method name:
- Read Operations: Methods like
eth_calloreth_getBalanceare forwarded directly to a specified RPC URL (typically a local Anvil instance). - Write Operations: Methods like
eth_sendTransactionorpersonal_signare handled locally using a private key and a ViemwalletClient. - Wallet/State Methods: Methods that manage provider state, such as
eth_accountsorwallet_switchEthereumChain, are resolved within the provider's internal state.
Sources: src/provider.ts:114-121, src/provider.ts:468-485, src/constants.ts:108-185
The following diagram illustrates the flow of different request types through the provider:
The provider distinguishes between methods to ensure that state-changing actions are controlled by the test suite while data-fetching remains realistic.
Sources: README.md:14-25, src/provider.ts:487-505
Design Principles
1. Deterministic Performance
By removing the dependency on external browser extensions and their associated UI latencies, Walletless achieves significant speedups in E2E suites. Benchmarks show up to a 16x improvement in "Real" execution time compared to traditional extension-based testing tools like Synpress.
Sources: README.md:37-45
2. High-Fidelity Chain Realism
Unlike mocks that simulate return values, Walletless interacts with real RPC endpoints. This ensures that the DApp logic (e.g., gas estimation, transaction receipts) is tested against actual blockchain behavior, albeit in a controlled local environment like Anvil.
Sources: README.md:24-25, src/provider.ts:107-110
3. Total Test Control
The provider exposes an "internal" API specifically for test runners. This allows developers to programmatically trigger edge cases that are difficult to simulate in a real wallet:
- Signature/Transaction Rejection: Forcing a
4001error to test error handling. - Account Switching: Instantly changing the active signer by index, address, or private key.
- Chain Management: Simulating network switches and validating multi-chain configurations.
Sources: README.md:104-124, src/provider.ts:544-590
Key Components & Data Structures
The system is composed of two primary layers: the EIP-1193 Provider and the Wagmi Connector.
Technical Specification Table
| Component | Description | Primary File |
|---|---|---|
createE2EProvider | Factory function that generates the virtual EIP-1193 provider. | src/provider.ts |
e2eConnector | A Wagmi-compatible connector that wraps the provider for React/Wagmi apps. | src/connector.ts |
InternalState | Holds the active walletClient, account, current rpcUrl, and rejection flags. | src/provider.ts:86-95 |
ANVIL_ACCOUNTS | A set of 10 deterministic accounts pre-loaded in Anvil for easy testing. | src/constants.ts:20-71 |
Method Categories
The library maintains strict lists of how every Ethereum RPC method should be handled:
| Category | Example Methods | Handling Logic |
|---|---|---|
| Read | eth_getBalance, eth_call | Forwarded via fetch to rpcUrl. |
| Write | eth_sendTransaction, personal_sign | Signed with internal.walletClient. |
| Wallet | eth_accounts, wallet_switchEthereumChain | Resolved using internal.state. |
Sources: src/constants.ts:108-164, src/provider.ts:490-505
Sequence: Transaction Signing Flow
The following sequence diagram shows the interaction when a DApp attempts to send a transaction through the Walletless provider.
Transaction requests are intercepted and handled locally using the configured account, avoiding any manual confirmation steps.
Sources: src/provider.ts:333-375, src/types.ts:162-171
Conclusion
The @wonderland/walletless project philosophy is rooted in removing friction from the Web3 development lifecycle. By treating the wallet as a programmable piece of infrastructure rather than a manual dependency, it allows for CI/CD friendly, high-speed, and technically accurate testing of complex decentralized applications.
Sources: README.md:27-35, package.json:2-10