Browser Window Injection

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/provider.ts
• src/connector.ts
• src/constants.ts
• src/types.ts
• test/provider.spec.ts

Browser Window Injection refers to the process of exposing the @wonderland/walletless virtual EIP-1193 provider to the global window object in a browser environment. This mechanism allows E2E testing tools, such as Playwright or Cypress, to interact directly with the provider's internal state and control its behavior during automated test execution. By injecting the provider, developers can programmatically trigger account switches, chain changes, and simulate transaction rejections via page.evaluate() or similar browser execution contexts.

This injection strategy serves as a "man-in-the-middle" between the DApp UI and the blockchain (typically an Anvil node). While the DApp continues to interact with the standard EIP-1193 interface, the injected provider routes read requests to an RPC endpoint and handles write operations through local signing or simulated failures.

Sources: README.md:12-25, README.md:143-157

Architecture and Data Flow

The injected provider implements a hybrid routing logic. It distinguishes between different types of Ethereum JSON-RPC methods to determine whether to forward them to a remote node or handle them locally.

Request Routing Logic

The provider categorizes incoming requests into three primary groups:

1. Read Methods: Forwarded directly to the configured Anvil RPC URL using native fetch.
2. Write Methods: Handled locally by a viem wallet client that signs transactions or messages using a local private key.
3. Wallet Methods: Handled internally to manage provider state such as the current active account or chain ID.

The diagram shows how the provider acts as a proxy, routing different request types based on the method name.
Sources: README.md:15-25, src/provider.ts:391-419, src/constants.ts:114-177

Provider Control via Injection

When testing with browser automation tools, the provider is typically assigned to a custom property on the window object. This enables the test runner to invoke specific control methods that are not part of the standard EIP-1193 specification but are essential for test orchestration.

Key Control Methods

The following methods are exposed on the E2EProvider instance to facilitate testing:

Method	Parameters	Description
setSigningAccount	SigningAccountInput	Switches the active signing account by index, address, or private key.
setChain	number	Updates the provider's current chain and switches the active RPC URL.
setRejectSignature	boolean	Toggles whether signature requests should be automatically rejected with error 4001.
setRejectTransaction	boolean	Toggles whether transaction requests should be automatically rejected with error 4001.
disconnect	None	Emits a disconnect event to simulate a lost wallet connection.

Sources: src/provider.ts:466-508, README.md:113-138

Sequence: Playwright Integration

The following sequence diagram illustrates how a test runner interacts with the injected provider to simulate a user rejecting a transaction.

Implementation Details

Internal State Management

The injected provider maintains an InternalState object that tracks configuration and volatile testing flags. This state is strictly separated from the public EIP-1193 interface but is accessible for verification in tests.

interface InternalState {
    account: PrivateKeyAccount | Account;
    walletClient: ReturnType<typeof createWalletClient>;
    chains: CompatibleChain[];
    currentChain: CompatibleChain;
    rpcUrl: string;
    rpcUrls: Record<number, string>;
    rejectSignature: boolean;
    rejectTransaction: boolean;
}

Sources: src/provider.ts:98-107

Account Resolution

The setSigningAccount method supports multiple input formats, making it versatile for different testing scenarios. It can resolve accounts from Anvil's default 10 accounts or accept custom viem Account objects.

• Numeric Index (0-9): Selects from the deterministic ANVIL_ACCOUNTS list.
• Address (42 chars): Matches an address against the Anvil defaults.
• Hex (66 chars): Uses a raw private key to create a new PrivateKeyAccount.
• Account Object: Uses a pre-configured viem account directly.

Sources: src/provider.ts:43-85, src/constants.ts:16-56

Integration with Wagmi

When using the e2eConnector within a Wagmi configuration, the injection process can be handled by passing an external provider instance. This ensures that the same instance used by Wagmi is the one exposed on the window object for the test runner.

const provider = createE2EProvider({ ... });
// Inject into global scope
(window as any).__e2eTestProvider = provider;

const config = createConfig({
    connectors: [e2eConnector({ provider })],
    // ...
});

Sources: README.md:151-157, src/connector.ts:119-141

Summary

Browser Window Injection is the core enablement strategy for @wonderland/walletless in E2E environments. By exposing a controllable, virtualized provider to the global scope, it allows developers to achieve high-performance testing (up to 16x speedup over extension-based tools) while maintaining full compatibility with the Ethereum provider standard and popular libraries like Wagmi and Viem.

Sources: README.md:33-43, package.json:2-10