impersonator/docs/e2e-testing.md

E2E Testing Guide

This guide explains how to run and write E2E tests using Playwright.

Setup

Installation

E2E tests use Playwright. Install dependencies:

pnpm install
pnpm exec playwright install

Running Tests

Run All Tests

pnpm test:e2e

Run Tests in UI Mode

pnpm test:e2e:ui

Run Tests in Debug Mode

pnpm test:e2e:debug

Run Specific Test File

pnpm exec playwright test e2e/wallet-connection.spec.ts

Run Tests in Specific Browser

pnpm exec playwright test --project=chromium
pnpm exec playwright test --project=firefox
pnpm exec playwright test --project=webkit

Writing Tests

Test Structure

import { test, expect } from '@playwright/test';

test.describe('Feature Name', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/');
  });

  test('should do something', async ({ page }) => {
    // Test code here
    await expect(page.locator('selector')).toBeVisible();
  });
});

Common Patterns

Navigation

await page.goto('/');
await page.goto('/smart-wallet');

Element Interaction

// Click
await page.click('button');

// Fill input
await page.fill('input[name="address"]', '0x123...');

// Select option
await page.selectOption('select', 'value');

Assertions

// Visibility
await expect(page.locator('.element')).toBeVisible();

// Text content
await expect(page.locator('h1')).toHaveText('Title');

// Value
await expect(page.locator('input')).toHaveValue('value');

Waiting

// Wait for element
await page.waitForSelector('.element');

// Wait for navigation
await page.waitForNavigation();

// Wait for network
await page.waitForLoadState('networkidle');

Test Files

Current Test Files

• e2e/example.spec.ts - Basic application tests
• e2e/wallet-connection.spec.ts - Wallet connection flow
• e2e/smart-wallet.spec.ts - Smart wallet functionality

Adding New Tests

1. Create a new file in e2e/ directory
2. Name it feature-name.spec.ts
3. Write tests following the structure above
4. Run tests to verify

CI/CD Integration

E2E tests run automatically on:

• Pull requests to main or develop
• Pushes to main or develop
• Manual workflow dispatch

See .github/workflows/e2e.yml for configuration.

Best Practices

1. Use Descriptive Test Names

// Good
test('should display error when address is invalid', ...);

// Bad
test('test1', ...);

2. Use Data Attributes for Selectors

// Good
await page.click('[data-testid="connect-button"]');

// Avoid
await page.click('.btn-primary');

3. Keep Tests Independent

Each test should be able to run independently without relying on other tests.

4. Clean Up After Tests

test.afterEach(async ({ page }) => {
  // Cleanup code
});

5. Use Page Object Model for Complex Flows

class WalletPage {
  constructor(private page: Page) {}
  
  async connectWallet(address: string) {
    await this.page.fill('[data-testid="address-input"]', address);
    await this.page.click('[data-testid="connect-button"]');
  }
}

Debugging

Visual Debugging

pnpm test:e2e:ui

Screenshots

Screenshots are automatically taken on test failure.

Videos

Videos are recorded for failed tests.

Trace Viewer

pnpm exec playwright show-trace trace.zip

Performance Testing

Measure Load Time

test('should load quickly', async ({ page }) => {
  const startTime = Date.now();
  await page.goto('/');
  const loadTime = Date.now() - startTime;
  
  expect(loadTime).toBeLessThan(3000); // 3 seconds
});

Resources

• Playwright Documentation
• Playwright Best Practices
• Test Configuration