WebApp E2E Tester

End-to-end web application testing with Playwright, featuring auto-correction, parallel execution, and intelligent test generation.

Features

• 🤖 Auto-Test Generation - Automatically discover and generate tests from any web application
• 🔧 AI-Powered Auto-Correction - Intelligently fix failing tests using advanced AI agents (Kimi, Claude, OpenCode)
• ⚡ Parallel Execution - Run tests across multiple workers and browsers simultaneously
• 📊 Comprehensive Reporting - HTML, JSON, and JUnit reports with trend analysis
• 🎯 Smart Selectors - Automatically prefer stable selectors (data-testid, ARIA roles)
• 🔄 Auto-Retry - Automatically retry flaky tests with intelligent strategies
• 🧠 Agent Integration - Support for multiple AI coding agents for enhanced test fixing
• 🐳 Docker Ready - Pre-configured Docker setup for CI/CD pipelines

Installation

Global Installation (CLI)

npm install -g webapp-e2e-tester

Project Installation

npm install -D webapp-e2e-tester

Prerequisites

• Node.js >= 16
• Playwright (auto-installed on first run)

Quick Start

1. Initialize Project

# Initialize Playwright with E2E testing setup
e2e-test init

# Or with custom directory
e2e-test init --dir ./my-project

2. Generate Tests Automatically

# Auto-discover and generate tests from your app
e2e-test generate --url http://localhost:3000

# Or with more options
e2e-test generate \
  --url http://localhost:3000 \
  --output ./e2e/tests \
  --flows auth,crud,form \
  --coverage comprehensive

3. Run Tests

# Run tests with parallel execution
e2e-test run

# Run with auto-correction enabled
e2e-test run --auto-correct --retries 3

# Run specific project (browser)
e2e-test run --project chromium --grep "auth"

# Run in headed mode (visible browser)
e2e-test run --headed

# Run with AI agent auto-correction
e2e-test run --auto-correct --agent-type kimi

AI Agent Integration

The tool supports integration with various AI coding agents for enhanced test auto-correction:

Supported Agents

• Kimi - Specialized in fixing E2E test failures
• Claude Code - Advanced test fixing with best practices
• OpenCode - Focused on test automation improvements
• Generic - Standard AI agent prompts

Usage with AI Agents

# Use Kimi AI for auto-correction
e2e-test run --auto-correct --agent-type kimi

# Use Claude Code for complex fixes
e2e-test run --auto-correct --agent-type claude

# Use OpenCode for automation improvements
e2e-test run --auto-correct --agent-type opencode

Agent Features

• Context-Aware Prompts - Each agent receives tailored prompts based on failure type
• Selector Optimization - AI suggests stable selectors (data-testid, ARIA roles)
• Timing Fixes - Intelligent wait strategies and timeout adjustments
• Assertion Improvements - More flexible and reliable test assertions

4. Analyze Results

# Generate analysis report
e2e-test analyze

# Output as JSON
e2e-test analyze --format json --output report.json

# Generate HTML report
e2e-test analyze --format html --output report.html

CLI Commands

e2e-test run - Run Tests

Run E2E tests with parallel execution and optional auto-correction.

Options:
  -c, --config <path>      Playwright config file (default: playwright.config.ts)
  -w, --workers <n>        Number of parallel workers (default: 4)
  -r, --retries <n>        Number of retries (default: 2)
  --auto-correct           Enable AI-powered test auto-correction
  --report <types>         Report formats: html,json,junit (default: html,json)
  --screenshots <when>     Screenshot capture: on-failure|on|off (default: on-failure)
  --video <when>           Video capture: on-first-retry|on|off (default: on-first-retry)
  --project <name>         Run specific project/browser
  --grep <pattern>         Run tests matching pattern
  --headed                 Run in headed mode (visible browser)
  --debug                  Enable debug logging
  --timeout <ms>           Test timeout (default: 30000)
  -u, --update-snapshots   Update screenshot snapshots

e2e-test generate - Generate Tests

Auto-discover user flows and generate test suites.

Options:
  -u, --url <url>          Target application URL (required)
  -o, --output <dir>       Output directory (default: ./e2e/tests)
  -f, --flows <types>      Flow types: auth,crud,form,nav,all (default: all)
  --coverage <level>       Coverage level: basic|standard|comprehensive (default: comprehensive)
  -i, --interactive        Interactive mode - confirm each flow
  --skip-auth              Skip authentication flows

e2e-test analyze - Analyze Results

Analyze test results and generate comprehensive reports.

Options:
  -i, --input <dir>        Input directory with test results (default: ./e2e/results)
  -f, --format <format>    Output format: summary|json|markdown|html (default: summary)
  -o, --output <file>      Output file for report
  --no-trends              Disable trend analysis

e2e-test init - Initialize Project

Set up a new Playwright project.

Options:
  -d, --dir <directory>    Project directory (default: .)
  --typescript             Use TypeScript (default)
  --javascript             Use JavaScript instead
  --no-install             Skip browser installation

e2e-test quick - Quick Test

Generate and run tests in one command.

Options:
  -u, --url <url>          Target application URL (required)
  --workers <n>            Number of workers (default: 2)
  --auto-correct           Enable auto-correction (default: true)

e2e-test doctor - Environment Check

Diagnose common issues with Playwright setup.

Usage: e2e-test doctor

Auto-Correction

The auto-correction feature can automatically fix common test failures:

Supported Fixes

| Failure Type | Fix Applied | |--------------|-------------| | Selector strict mode | Adds .first() to ambiguous selectors | | Element not found | Increases timeout, adds explicit waits | | Timeout errors | Adds networkidle waits after navigation | | Visibility issues | Adds scrollIntoViewIfNeeded() | | Assertion failures | Switches to more flexible assertions |

Usage

# Enable auto-correction
e2e-test run --auto-correct --retries 3

When a test fails:

1. The failure is analyzed
2. Appropriate fixes are applied
3. Test is re-run
4. If successful, fixes are kept; otherwise, original is restored

Programmatic Usage

Use in your Node.js scripts:

const { SmartRunner, TestGenerator, ReportAnalyzer } = require('webapp-e2e-tester');

// Run tests
const runner = new SmartRunner({
  workers: 4,
  autoCorrect: true,
  retries: 2
});

const result = await runner.run();
console.log(`Pass rate: ${result.stats.passRate}`);

// Generate tests
const generator = new TestGenerator({
  url: 'http://localhost:3000',
  outputDir: './e2e/tests'
});

await generator.generate();

// Analyze results
const analyzer = new ReportAnalyzer({
  inputDir: './e2e/results',
  outputFormat: 'html'
});

await analyzer.analyze();

Configuration

playwright.config.ts

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './e2e/tests',
  outputDir: './e2e/results',
  
  fullyParallel: true,
  workers: process.env.CI ? 4 : undefined,
  retries: process.env.CI ? 2 : 1,
  
  reporter: [
    ['html', { open: 'never' }],
    ['json', { outputFile: 'e2e/results/report.json' }],
    ['junit', { outputFile: 'e2e/results/junit.xml' }],
  ],
  
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
  
  use: {
    baseURL: process.env.BASE_URL || 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
});

Docker Usage

Dockerfile

FROM mcr.microsoft.com/playwright:v1.40.0-jammy

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .

CMD ["e2e-test", "run", "--workers=4", "--auto-correct"]

docker-compose.yml

version: '3.8'

services:
  e2e-tests:
    build: .
    environment:
      - BASE_URL=http://app:3000
      - CI=true
    volumes:
      - ./e2e/results:/app/e2e/results

CI/CD Integration

GitHub Actions

name: E2E Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 18
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run E2E tests
        run: npx e2e-test run --workers=4 --auto-correct
      
      - name: Upload results
        uses: actions/upload-artifact@v3
        with:
          name: test-results
          path: e2e/results/

GitLab CI

e2e_tests:
  image: mcr.microsoft.com/playwright:v1.40.0-jammy
  script:
    - npm ci
    - npx e2e-test run --workers=4 --auto-correct
  artifacts:
    paths:
      - e2e/results/

Best Practices

1. Use data-testid Attributes

<button data-testid="submit-button">Submit</button>

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

2. Prefer Web-First Assertions

// ✅ Good - auto-retrying
await expect(page.locator('.status')).toHaveText('Success');

// ❌ Bad - immediate check
expect(await page.locator('.status').textContent()).toBe('Success');

3. Use Page Objects

// pages/LoginPage.js
export class LoginPage {
  constructor(page) {
    this.page = page;
    this.emailInput = page.locator('[data-testid="email"]');
    this.submitButton = page.locator('[data-testid="submit"]');
  }
  
  async login(email, password) {
    await this.emailInput.fill(email);
    await this.submitButton.click();
  }
}

4. Parallel Execution

# Use multiple workers
e2e-test run --workers=4

5. Retry Flaky Tests

# Auto-retry with correction
e2e-test run --retries=3 --auto-correct

Troubleshooting

Browsers not found

npx playwright install

Permission errors

# Linux/Mac
sudo npx playwright install-deps

# Windows (run as Administrator)
npx playwright install-deps

Tests timing out

Increase timeout in config:

export default defineConfig({
  timeout: 60000, // 60 seconds
  expect: {
    timeout: 10000
  }
});

License

MIT © Prakash Garg

Contributing

Contributions welcome! Please read CONTRIBUTING.md for details.

Changelog

See CHANGELOG.md for version history.