@finn_gal/patchright-wallet-mock-ts/README.md

Mock Web3 Browser wallets, like Metamask, in Patchright tests.

# Playwright Wallet Mock TS

A TypeScript library for mocking Web3 browser wallets (like MetaMask) in Playwright tests. This package provides a simple way to simulate wallet interactions in your dApp tests.

## Features

- Mock Ethereum wallet (MetaMask-like) in Playwright tests
- Support for EIP-1193 standard
- Local API server for making wallet requests
- Automatic port allocation for the API server
- TypeScript support

## Installation

```bash
npm install @finn_gal/playwright-wallet-mock-ts
```

## Usage

### Basic Usage

```typescript
import { chromium } from "playwright";
import { installMockWallet } from "@finn_gal/playwright-wallet-mock-ts";
import { privateKeyToAccount } from "viem/accounts";
import { mainnet } from "viem/chains";
import { http } from "viem";

async function testDapp() {
  const browser = await chromium.launch({
    headless: false,
  });
  const context = await browser.newContext();
  const page = await context.newPage();
  
  // Install the mock wallet
  await installMockWallet({
    page,
    account: privateKeyToAccount(
      "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80", // Example private key (don't use in production)
    ),
    defaultChain: mainnet,
    transports: { [mainnet.id]: http() },
    debug: true,
  });

  // Navigate to your dApp
  await page.goto("https://your-dapp-url.com");
  
  // Your wallet is now available in the page as window.ethereum
  // You can interact with your dApp as if MetaMask was installed
  
  await browser.close();
}

testDapp().catch(console.error);
```

### Making EIP-1193 Requests

The library sets up a local API server that handles EIP-1193 requests. In the browser context, you can use `window.eip1193Request` to make requests:

```typescript
// In browser context
const accounts = await window.eip1193Request({
  method: "eth_accounts",
  params: []
});

const balance = await window.eip1193Request({
  method: "eth_getBalance",
  params: [accounts[0], "latest"]
});
```

### API Reference

#### installMockWallet(options)

Installs a mock wallet in the Playwright page.

Options:
- `page`: Playwright Page object
- `account`: Viem LocalAccount object
- `transports` (optional): Record of chain ID to Transport mappings
- `defaultChain` (optional): Default chain to use
- `debug` (optional): Enable debug logging
- `wallet` (optional): Use a pre-configured wallet instance instead of creating a new one

#### eip1193Request Parameters

- `method`: The EIP-1193 method to call (e.g., "eth_accounts", "eth_getBalance")
- `params`: Array of parameters for the method
- `uuid`: Wallet UUID (automatically managed by the library)
- `debug`: Enable debug logging

## Examples

### Testing a Connect Wallet Button

```typescript
import { test, expect } from "@playwright/test";
import { installMockWallet } from "@finn_gal/playwright-wallet-mock-ts";
import { privateKeyToAccount } from "viem/accounts";
import { mainnet } from "viem/chains";
import { http } from "viem";

test("connect wallet button works", async ({ page }) => {
  await installMockWallet({
    page,
    account: privateKeyToAccount(
      "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
    ),
    defaultChain: mainnet,
    transports: { [mainnet.id]: http() },
    debug: true,
  });

  await page.goto("https://your-dapp-url.com");
  
  // Click the connect wallet button
  await page.getByRole("button", { name: "Connect Wallet" }).click();
  
  // Check if the wallet address is displayed
  await expect(page.getByText("0x71C7656EC7ab88b098defB751B7401B5f6d8976F")).toBeVisible();
});
```

## License

ISC