# e2e-testing

> End-to-end testing with Playwright. Integrated into APEX EXAMINE phase. A feature CANNOT pass unless E2E test succeeds. Required for Ralph loop completion.

- Author: Nova
- Repository: One-Up-Dev/autonomous-apex-ralph
- Version: 20260127171406
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/One-Up-Dev/autonomous-apex-ralph
- Web: https://mule.run/skillshub/@@One-Up-Dev/autonomous-apex-ralph~e2e-testing:20260127171406

---

---
name: e2e-testing
description: End-to-end testing with Playwright. Integrated into APEX EXAMINE phase. A feature CANNOT pass unless E2E test succeeds. Required for Ralph loop completion.
---

# E2E Testing Skill

Real browser testing with Playwright. **No feature passes without E2E verification.**

## Critical Rule

```
⚠️ A feature is NOT complete until E2E test passes.

passes: true → ONLY after Playwright confirms it works
```

## Integration with Ralph Loop

```
┌─────────────────────────────────────────────────────────────────┐
│                    RALPH + E2E LOOP                             │
│                                                                 │
│  APEX EXECUTE → Code implemented                                │
│       ↓                                                         │
│  APEX EXAMINE:                                                  │
│    1. npm run build ✓                                          │
│    2. npm run lint ✓                                           │
│    3. Start dev server                                          │
│    4. Run Playwright test for THIS feature                      │
│       ↓                                                         │
│  E2E passes?                                                    │
│    ├─ YES → <promise>DONE</promise>                            │
│    │        → passes: true                                      │
│    │        → Next feature                                      │
│    │                                                            │
│    └─ NO → Ralph retry                                         │
│            → Fix based on test output                           │
│            → Re-run E2E                                         │
│            → Max 3 retries, then deep-research                  │
└─────────────────────────────────────────────────────────────────┘
```

## Setup

### 1. Install Playwright

```bash
npm install -D @playwright/test
npx playwright install chromium
```

### 2. Create playwright.config.ts

```typescript
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './e2e',
  timeout: 30000,
  retries: 0,  // Ralph handles retries
  use: {
    baseURL: 'http://localhost:5173',
    headless: true,
    screenshot: 'only-on-failure',
  },
  webServer: {
    command: 'npm run dev',
    port: 5173,
    reuseExistingServer: true,
  },
});
```

### 3. Test Structure

```
e2e/
├── features/
│   ├── ui-001-header.spec.ts
│   ├── ui-002-task-input.spec.ts
│   ├── func-001-add-task.spec.ts
│   └── ...
└── helpers/
    └── test-utils.ts
```

## Generating Tests from feature_list.json

For each feature, generate a test file:

```typescript
// e2e/features/func-001-add-task.spec.ts
import { test, expect } from '@playwright/test';

test.describe('func-001: Add new task', () => {
  test('should add task via Enter key', async ({ page }) => {
    await page.goto('/');
    
    // Type task
    await page.fill('[data-testid="task-input"]', 'Buy groceries');
    await page.keyboard.press('Enter');
    
    // Verify task appears
    await expect(page.locator('[data-testid="task-item"]')).toContainText('Buy groceries');
  });

  test('should add task via Add button', async ({ page }) => {
    await page.goto('/');
    
    await page.fill('[data-testid="task-input"]', 'Walk the dog');
    await page.click('[data-testid="add-button"]');
    
    await expect(page.locator('[data-testid="task-item"]')).toContainText('Walk the dog');
  });
});
```

## Test ID Convention

**MANDATORY:** All interactive elements must have `data-testid`:

```tsx
// ✅ Correct
<input data-testid="task-input" ... />
<button data-testid="add-button">Add</button>
<div data-testid="task-item">...</div>

// ❌ Wrong - No test ID
<input placeholder="Add task" />
```

## Running Tests

### Single Feature

```bash
# Test specific feature
npx playwright test e2e/features/func-001-add-task.spec.ts
```

### All Features

```bash
npx playwright test
```

### With UI (debugging)

```bash
npx playwright test --ui
```

## Interpreting Results

### Pass
```
✓ func-001-add-task.spec.ts (2 tests)
```
→ Feature complete, mark `passes: true`

### Fail
```
✗ func-001-add-task.spec.ts
  - should add task via Add button
    Error: expect(locator).toContainText('Walk the dog')
    Received: ""
```
→ Ralph retry, fix the bug, re-run test

## Scripts

### generate_e2e_tests.py

Generates Playwright tests from feature_list.json:

```bash
python scripts/generate_e2e_tests.py \
  --feature-list feature_list.json \
  --output-dir e2e/features/
```

### run_feature_test.sh

Run E2E test for specific feature:

```bash
./scripts/run_feature_test.sh func-001
```

## Best Practices

1. **One test file per feature** - Easy to run individually
2. **Always use data-testid** - Stable selectors
3. **Test user flows** - Not implementation details
4. **Screenshot on failure** - Debug easily
5. **Keep tests fast** - Under 10s each