---

name: e2e-test-optimizer description: Optimizes Playwright E2E tests by removing waitForTimeout anti-patterns, implementing smart waits, and enabling test sharding for parallel execution. Use when tests timeout, CI execution exceeds limits, or test reliability issues occur.

E2E Test Optimizer

Quick Start

This skill helps fix three critical E2E test issues:

1. Anti-pattern removal: Replace arbitrary waitForTimeout with smart waits
2. Test sharding: Enable parallel test execution in CI
3. Mock optimization: Reduce mock setup overhead

When to Use

• E2E tests timing out or failing due to arbitrary waits
• CI execution time exceeds 10 minutes
• Need test parallelization for faster feedback
• Test flakiness from race conditions

Smart Wait Patterns

Navigation Waits

Copy// ❌ Arbitrary wait
await page.click('[data-testid="nav-dashboard"]');
await page.waitForTimeout(1000);

// ✅ Wait for specific element
await page.click('[data-testid="nav-dashboard"]');
await expect(page.getByTestId('dashboard-content')).toBeVisible({
  timeout: 5000,
});

State Transition Waits

Copy// ❌ Arbitrary wait after action
await page.getByRole('button', { name: 'Generate' }).click();
await page.waitForTimeout(2000);

// ✅ Wait for loading state completion
await page.getByRole('button', { name: 'Generate' }).click();
await expect(page.getByTestId('loading-spinner')).not.toBeVisible();
await expect(page.getByTestId('result')).toBeVisible();

Network Waits

Copy// ❌ Arbitrary wait after submit
await page.getByRole('button', { name: 'Save' }).click();
await page.waitForTimeout(1500);

// ✅ Wait for network idle or success message
await page.getByRole('button', { name: 'Save' }).click();
await page.waitForLoadState('networkidle');
// OR
await expect(page.getByText('Saved successfully')).toBeVisible();

Test Sharding Setup

Add to .github/workflows/ci.yml:

Copye2e-tests:
  name: 🧪 E2E Tests [Shard ${{ matrix.shard }}/3]
  runs-on: ubuntu-latest
  timeout-minutes: 30
  needs: build-and-test
  strategy:
    fail-fast: false
    matrix:
      shard: [1, 2, 3]
  steps:
    - name: Run Playwright tests
      run: pnpm exec playwright test --shard=${{ matrix.shard }}/3
      env:
        CI: true

Expected improvement: 60-65% faster (27 minutes → 9-10 minutes)

Detection Commands

Copy# Find all waitForTimeout usage
grep -r "waitForTimeout" tests/specs/*.spec.ts

# Count per file
grep -c "waitForTimeout" tests/specs/*.spec.ts

Standard Test Structure

Copyimport { test, expect } from '@playwright/test';
import { setupGeminiMock } from '../utils/mock-ai-gateway';

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

  test('should perform action', async ({ page }) => {
    // Navigate
    await page.getByTestId('nav-target').click();
    await expect(page.getByTestId('target-page')).toBeVisible();

    // Interact
    await page.getByRole('button', { name: 'Action' }).click();
    await expect(page.getByTestId('loading')).not.toBeVisible();

    // Assert
    await expect(page.getByTestId('result')).toBeVisible();
  });
});

Element Selection Priority

Copy// ✅ Best: data-testid (stable, explicit)
await page.getByTestId('project-card');

// ✅ Good: role + name (semantic, accessible)
await page.getByRole('button', { name: 'Create' });

// ⚠️ OK: text (can break with i18n)
await page.getByText('Dashboard');

// ❌ Avoid: CSS selectors (brittle)
await page.locator('.project-card > div.title');

Optimization Workflow

Phase 1: Analysis

1. Scan test files for waitForTimeout
2. Count occurrences per file
3. Prioritize files by occurrence count

Phase 2: Fix Anti-Patterns

1. Start with highest-priority file
2. Replace each waitForTimeout with smart wait
3. Run tests after each file: playwright test path/to/file.spec.ts
4. Commit per-file changes

Phase 3: Implement Sharding

1. Update CI workflow with matrix strategy
2. Test locally: playwright test --shard=1/3
3. Push and monitor all 3 shards in CI

Phase 4: Validation

1. Verify all tests pass
2. Confirm execution time < 10 minutes
3. Check shard balance (±2 min variance acceptable)

Common Issues

Tests still timing out after fix

• Increase timeout on slow operations: expect(...).toBeVisible({ timeout: 10000 })

Unbalanced shards (one takes much longer)

• Use --grep to manually distribute heavy tests across shards

Mock setup still slow

• Implement global browser warm-up (see MOCK-OPTIMIZATION-GUIDE.md in tests/docs)

Success Criteria

• Zero waitForTimeout calls in active tests
• CI execution time < 10 minutes
• All shards complete within ±2 minutes of each other
• 100% test pass rate (no flaky tests)

References

See tests/docs/ for detailed guides:

• MOCK-OPTIMIZATION-GUIDE.md - Mock performance patterns
• MOCK-PERFORMANCE-ANALYSIS.md - Optimization results

External documentation:

• Playwright Best Practices: https://playwright.dev/docs/best-practices
• Test Sharding: https://playwright.dev/docs/test-sharding