e2e-testing-for-webapps

Files (15)

• SKILL.md
• ADVANCED-TECHNIQUES.md · references/
• AI-VISUAL-ANALYSIS.md · references/
• AUTHENTICATION.md · references/
• CONSOLE-MONITORING.md · references/
• DIAGNOSTIC-TOOLS.md · references/
• FAILURE-INJECTION.md · references/
• INTERACTIVE-SESSIONS.md · references/
• PAGE-OBJECTS.md · references/
• QUICK-REFERENCE.md · references/
• REPORTING.md · references/
• SCREENSHOTS.md · references/
• SYSTEMATIC-TESTING.md · references/
• VISUAL-QA.md · references/
• validate-e2e.sh · scripts/

SKILL.md (first lines)

# E2E Testing for Web & Electron Apps

> **Two modes:** Batch testing (CI/test suites) and Interactive debugging (persistent browser sessions for iterative QA). Both share the same QA methodology.

> **Stack:** Next.js 16 + Playwright + Supabase Auth + agent-native vision

## Architecture

```
┌──────────────────────────────────────────────────────────────────────────┐
│                       E2E TESTING ARCHITECTURE                          │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   MODE 1: BATCH (CI / Test Suites)                                      │
│   ═══════════════════════════════                                       │
│   Playwright Test runner → auth setup → test specs → reports            │
│   ✓ Headless CI  ✓ Parallel workers  ✓ Retries  ✓ Artifacts            │
│                                                                         │
│   MODE 2: INTERACTIVE (Debugging / Iterative QA)                        │
│   ═══════════════════════════════════════════════                       │
│   Persistent browser session → live reload → functional QA → visual QA  │
│   ✓ Desktop/Mobile/Electron  ✓ Session reuse  ✓ Screenshot analysis     │
│                                                                         │
│   SHARED INFRASTRUCTURE                                                 │
│   ═════════════════════                                                  │
│   1. Auth bypass: Supabase test users with email/password (no OAuth)    │
│   2. Console monitoring: capture runtime, network, hydration errors     │
│   3. Page Objects: BasePage → DashboardPage, SettingsPage, etc.         │
│   4. AI visual analysis: Screenshots → agent-native vision → QA        │
│   5. Diagnostic tools: DOM health check, layout snapshot diff, styles │
│   6. Failure injection: network, input stress, state corruption       │
│   7. QA methodology: inventory → functional QA → visual QA → signoff   │
│                                                                         │
└──────────────────────────────────────────────────────────────────────────┘
```

---

## Quick Start: Batch Testing

```bash
# 1. Install Playwright
bun add -D @playwright/test && bunx playwright install chromium

# 2. Create test user in Supabase (bypasses Google OAuth)
bun scripts/provision-e2e-test-users.ts --user=primary

# 3. Run tests against production
E2E_TEST_EMAIL=test@app.test E2E_TEST_PASSWORD=xxx bun run test:e2e:prod
```

## Quick Start: Interactive Debugging

```bash
# 1. Install Playwright (npm for js_repl compat, bun for everything else)
test -f package.json || npm init -y
npm install playwright
npx playwright install chromium

# 2. Bootstrap persistent session (js_repl, Node REPL, or script)
node -e "import('playwright').then(() => console.log('ready'))"
```

Then launch a browser and start testing — see [INTERACTIVE-SESSIONS.md](references/INTERACTIVE-SESSIONS.md).

---

## The Google OAuth Bypass

**Problem:** Google blocks automated logins (CAPTCHA, headless detection).

**Solution:** Create test users with email/password auth in Supabase — same app, different auth method.

```typescript
// Sign in via Supabase (NOT Google OAuth)
const { data, error } = await supabase.auth.signInWithPassword({
  email: process.env.E2E_TEST_EMAIL,     // e2e-test@app.test
  password: process.env.E2E_TEST_PASSWORD,
});
// Inject session cookies into browser context
await context.addCookies([
  { name: 'sb-access-token', value: data.session.access_token, domain: '...', ... },
]);
```

**Why `.test` TLD?** IANA-reserved, never resolves — test emails can't leak to real inboxes.

**Deep dive:** [AUTHENTICATION.md](references/AUTHENTICATION.md)

---

## QA Inventory Methodology

Before testing, build a coverage list from **three sources:**

1. **User's requested requirements** — what was asked for
2. **Implemented features/behaviors** — what you actually built
3. **Claims in the final response** — what you intend to sign off on

Everything in any of those three sources must map to at least one QA check.

For each item, note:
- The intended functional check (user input → expected result)
- The specific state where visual check must happen
- The evidence to capture (screenshot, assertion)

Add at least **2 exploratory/off-happy-path scenarios** that could expose fragile behavior.

Update the inventory during testing if exploration reveals additional controls, states, or claims.

---

## Workflow

### Batch Mode Phases

| Phase | Steps |
|-------|-------|
| **1. Setup** | Install Playwright, create test users, configure storage state |

From danzam98/claude-skills-toolkit, MIT.

More from danzam98/claude-skills-toolkit