Control Methods API
Relevant source files
The following files were used as context for generating this wiki page:
The Control Methods API provides a set of programmatic interfaces designed to manipulate the state of the virtual EIP-1193 provider during E2E testing. These methods allow developers to simulate specific wallet behaviors—such as switching accounts, changing networks, or rejecting user requests—without requiring manual interaction with a browser extension.
These methods are exposed in two primary ways: as direct methods on the E2EProvider instance (accessible via page.evaluate() in browser contexts) and as standalone helper functions that operate on a provider instance. This dual-access pattern ensures compatibility across different testing environments and execution contexts.
Sources: README.md:121-125, src/provider.ts:133-145
API Access Patterns
The Control Methods API supports two distinct integration patterns depending on the testing framework and context:
- Direct Instance Methods: The
createE2EProviderfunction returns a provider that includes control methods directly on the object. This is the recommended approach for Playwright or Cypress tests where the provider is attached to the globalwindowobject. - Standalone Helpers: Functions exported from
src/provider-controls.tsthat take the provider as their first argument. These are useful when the provider is accessible in the same JavaScript execution context.
Control Method Interface
| Method | Parameters | Description |
|---|---|---|
setSigningAccount | account: SigningAccountInput | Updates the active account used for signing and write operations. |
setChain | chainId: number | Switches the provider to a different supported network and updates the RPC URL. |
setRejectSignature | reject: boolean | Toggles whether signature requests (e.g., personal_sign) should throw a 4001 error. |
setRejectTransaction | reject: boolean | Toggles whether transaction requests (eth_sendTransaction) should throw a 4001 error. |
disconnect | None | Emits a disconnect event and updates provider state. |
Sources: src/provider.ts:133-145, src/provider-controls.ts:1-30, README.md:127-148
Account Management
The setSigningAccount method allows for deterministic account switching. It resolves several input types into a valid viem Account or PrivateKeyAccount object, updating the internal walletClient and emitting accountsChanged events.
The logic handles index-based selection (0-9) from default Anvil accounts, raw private keys (66 characters), or specific Ethereum addresses (42 characters).
Sources: src/provider.ts:31-77, src/provider.ts:503-507, src/constants.ts:19-74
Network & Chain Control
The setChain method facilitates network switching by validating the target chainId against the supportedChainIds defined during provider initialization. When a valid switch occurs, the provider updates its internal RPC URL and recreates the walletClient to point to the new endpoint.
Chain Switching Flow
If the target chain is not found in the initial configuration, the API throws an error with code 4902 (Chain not added).
Sources: src/provider.ts:515-534, src/provider.ts:291-314, src/types.ts:114-118
Simulation of Failures
The API provides methods to simulate user rejection, which is critical for testing DApp error handling logic. Enabling these flags causes the provider to intercept specific JSON-RPC methods and return EIP-1193 compliant errors.
Rejection Matrix
| Method | Target RPC Methods | Error Code | Error Message |
|---|---|---|---|
setRejectSignature(true) | personal_sign, eth_sign, eth_signTypedData* | 4001 | User rejected the signature request. |
setRejectTransaction(true) | eth_sendTransaction | 4001 | User rejected the transaction request. |
Sources: src/provider.ts:213-231, src/types.ts:182-192, README.md:143-148
Internal State Management
All control methods interact with the __internal property of the E2EProviderWithInternal interface. This property exposes the underlying state, including the active account, current chain, and rejection flags, allowing the API to maintain synchronization between the virtual wallet and the DApp's view.
Conclusion
The Control Methods API is the core mechanism for driving deterministic behavior in the Walletless provider. By abstracting complex state transitions—such as re-instantiating wallet clients and managing RPC routing—into simple, high-level functions, it enables high-performance E2E testing of Web3 applications with production-realistic chain interactions.
Summary paragraph: The API ensures that developers can programmatically control every aspect of the wallet lifecycle, from account impersonation to network switching, while maintaining full EIP-1193 compliance.