Skip to content
Skills Library
Programming · Testing

v1-e2e-testing

/v1-e2e-testing

Use when implementing or debugging browser end-to-end tests, especially Playwright or flaky tests. Triggers on "E2E test", "Playwright", or "flaky browser test".

Author
v1-io ↗
Repository
v1tamins ↗
Licence
MIT
Last repository change
24.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
1
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/with_server.py

What it does and when to use it

Use when implementing or debugging browser end-to-end tests, especially Playwright or flaky tests. Triggers on "E2E test", "Playwright", or "flaky browser test".

Triggers from the description

E2E testPlaywrightflaky browser test
Original author description

Use when implementing or debugging browser end-to-end tests, especially Playwright or flaky tests. Triggers on "E2E test", "Playwright", or "flaky browser test".

How it works

  1. Quick Start
  2. When to Use E2E Tests
  3. Decision Tree
  4. Debugging Reproduction Loops
  5. Playwright Configuration
  6. Page Object Model
  7. Selectors (Priority Order)
  8. Waiting Strategies
  9. Authentication
  10. Debugging
Original SKILL.md headings · 321 lines, 1,232 words
SKILL.md preview
---
name: v1-e2e-testing
description: Use when implementing or debugging browser end-to-end tests, especially Playwright or flaky tests. Triggers on "E2E test", "Playwright", or "flaky browser test".
---
# E2E Testing with Playwright

Build reliable, fast E2E test suites that catch regressions and enable confident deployments.

## Quick Start

The server helper requires POSIX process groups (macOS/Linux). Run the shell
blocks with Bash; if your tool defaults to zsh or another shell, select Bash
before executing them. Cache glob handling depends on that shell.

**Test a local web application:**

```bash
# If server not running, resolve the bundled helper first
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
RESOLVER=""
for candidate in \
  "$REPO_ROOT/plugins/v1tamins/scripts/resolve-skill-root.sh" \
  "${CLAUDE_PLUGIN_ROOT:-}/scripts/resolve-skill-root.sh" \
  "$HOME/.claude/skills/v1-e2e-testing/../../scripts/resolve-skill-root.sh" \
  "$HOME/.codex/skills/v1-e2e-testing/../../scripts/resolve-skill-root.sh" \
  "$HOME/.claude/plugins/cache"/*/v1tamins/*/scripts/resolve-skill-root.sh \
  "$HOME/.codex/plugins/cache/v1tamins/v1tamins"/*/scripts/resolve-skill-root.sh; do
  [ -x "$candidate" ] && RESOLVER="$candidate" && break
done
if [ -z "${RESOLVER:-}" ]; then
  echo "ERROR: Could not find resolve-skill-root.sh" >&2
  exit 1
fi
SKILL_ROOT="$("$RESOLVER" v1-e2e-testing scripts/with_server.py)"

python3 "$SKILL_ROOT/scripts/with_server.py" --server "npm run dev" --port 3000 -- python your_test.py

# If server already running, write Playwright directly
```

**Basic Playwright test:**

```python
from playwright.sync_api import expect, sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()
    page.goto('http://localhost:3000')
    expect(page.get_by_role('button', name='Login')).to_be_visible()  # Wait for the app to render

    # Reconnaissance first
    page.screenshot(path='/tmp/inspect.png', full_page=True)

    # Then actions
    page.get_by_role('button', name='Login').click()
    browser.close()
```

## When to Use E2E Tests

**Good for:**
- Critical user journeys (login, checkout, signup)
- Complex interactions (drag-and-drop, multi-step forms)
- Cross-browser compatibility
- Real API integration
- Authentication flows
- Reproducing browser-only bugs when a deterministic or high-rate feedback loop is needed for debugging

**Not for:**
- Unit-level logic (use unit tests)
- API contracts (use integration tests)
- Every edge case (too slow)
- Internal implementation details

## Decision Tree

```
User task → Is it static HTML?
    ├─ Yes → Read HTML file directly for selectors
    │         └─ Write Playwright script using selectors
    │
    └─ No (dynamic webapp) → Is the server already running?
        ├─ No → Use scripts/with_server.py
        │
        └─ Yes → Reconnaissance-then-action:
            1. Navigate and assert a key element is visible
            2. Take screenshot or inspect DOM
            3. Identify selectors from rendered state
            4. Execute actions with discovered selectors
```

## Debugging Reproduction Loops

When using Playwright as a debug loop, make the script prove the specific symptom the user reported:

- Assert on the exact wrong state, console error, failed network response, URL, or visible element
- Loop flaky triggers enough times to measure the failure rate before changing code
- Capture screenshots, console logs, and network responses only where they distinguish hypotheses
- Promote the script into a regression test only when it exercises the real user path that caused the bug

## Playwright Configuration

```typescript
// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./e2e",
  timeout: 30000,
  expect: { timeout: 5000 },
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: [["html"], ["github"]],
  use: {
    baseURL: "http://localhost:3000",
    trace: "on-first-retry",
    screenshot: "only-on-failure",
    video: "retain-on-failure",
  },
  projects: [
    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
    { name: "webkit", use: { ...devices["Desktop Safari"] } },
    { name: "mobile", use: { ...devices["iPhone 13"] } },
  ],
});
```

## Page Object Model

Encapsulate page logic in classes:

```typescript
// pages/LoginPage.ts
import { Page, Locator } from "@playwright/test";

export class LoginPage {
  readonly page: Page;
  readonly emailInput: Locator;
  readonly passwordInput: Locator;
  readonly loginButton: Locator;

  constructor(page: Page) {
    this.page = page;
    this.emailInput = page.getByLabel("Email");
    this.passwordInput = page.getByLabel("Password");
    this.loginButton = page.getByRole("button", { name: "Login" });
  }

  async goto() {
    await this.page.goto("/login");
  }

  async login(email: string, password: string) {
    await this.emailInput.fill(email);
    await this.passwordInput.fill(password);
    await this.loginButton.click();
  }
}

// Usage in tests
test("successful login", async ({ page }) => {
  const loginPage = new LoginPage(page);
  await loginPage.goto();
  await loginPage.login("user@example.com", "password123");
  await expect(page).toHaveURL("/dashboard");
});
```

## Selectors (Priority Order)

1. **Role-based (best):** `page.getByRole('button', { name: 'Submit' })`
2. **Label (for forms):** `page.getByLabel('Email')`
3. **Placeholder:** `page.getByPlaceholder('Search...')`
4. **Test ID:** `page.getByTestId('submit-button')`
5. **Text:** `page.getByText('Welcome')`
6. **CSS (avoid):** `page.locator('.btn-primary')` - brittle!

**Multi-candidate strategy for Auth0/iframes:**

```typescript
// Frame-aware selectors
const frame = page.frameLocator('[data-testid="auth0-frame"]');
await frame.getByRole('textbox', { name: 'Email' }).fill(email);
```

## Waiting Strategies

```typescript
// BAD: Fixed timeouts
await page.waitForTimeout(3000); // Flaky!

// GOOD: Wait for specific conditions
await page.waitForURL("/dashboard");

// BETTER: Auto-waiting with assertions
await expect(page.getByText("Welcome")).toBeVisible();
await expect(page.getByRole("button")).toBeEnabled();

// Wait for API response
const responsePromise = page.waitForResponse(
  (res) => res.url().includes("/api/users") && res.status() === 200
);
await page.getByRole("button", { name: "Load" }).click();
await responsePromise;
```

## Authentication

**Storage state for pre-auth (recommended):**

```typescript
// global-setup.ts
async function globalSetup() {
  const browser = await chromium.launch();
  const page = await browser.newPage();

  await page.goto("/login");
  await page.getByLabel("Email").fill(process.env.TEST_USER!);
  await page.getByLabel("Password").fill(process.env.TEST_PASSWORD!);
  await page.getByRole("button", { name: "Login" }).click();
  await page.waitForURL("/dashboard");

  await page.context().storageState({ path: "auth.json" });
  await browser.close();
}

// playwright.config.ts
use: {
  storageState: "auth.json",
}
```

## Debugging

```bash
# Headed mode
npx playwright test --headed

# Debug mode (step through)
npx playwright test --debug

# Pause in test
await page.pause();  # Opens inspector

# Trace viewer
npx playwright show-trace trace.zip
```

**Add test steps for reporting:**

```typescript
test('checkout flow', async ({ page }) => {
  await test.step('Add item to cart', async () => {
    await page.goto('/products');
    await page.getByRole('button', { name: 'Add to Cart' }).click();
  });

  await test.step('Proceed to checkout', async () => {
    await page.goto('/cart');
    await page.getByRole('button', { name: 'Checkout' }).click();
  });
});
```

## Flaky Test Prevention

| Cause | Fix |
|-------|-----|
| Fixed timeouts | Use web-first assertions (`expect(locator).toBeVisible()`) |
| Race conditions | Wait for specific state before acting |
| Test interdependence | Make tests independent, clean up data |
| Stale selectors | Use role-based selectors, avoid CSS classes |
| Animation interference | Wait for animations, disable in test mode |

**Root cause checklist:**
- [ ] Using `waitForTimeout()` anywhere? Replace with proper waits
- [ ] Tests share state? Add proper setup/teardown
- [ ] Selectors rely on CSS classes? Use role/label/testid
- [ ] Network timing issues? Wait for specific responses

## Scripts Reference

**`scripts/with_server.py`** - Server lifecycle management

Requires Python 3 and POSIX process groups (macOS/Linux). Server commands must
stay in the foreground. The helper rejects a port that already has a listener,
fails when a server command exits before readiness, and stops each launched
process group, including shell-wrapper descendants, on completion or startup
failure. SIGINT, SIGTERM, and SIGHUP also stop the owned server and test command
groups, with exit status `128 + signal number`. SIGKILL cannot trigger cleanup.
It returns the test command's exit status normally; setup errors return nonzero.
TCP readiness only means the port accepts connections. Keep the application
assertions in the test; an open port does not prove that the intended page or
API is healthy. Use an already-running server directly when that is intended.

```bash
# Single server (resolve SKILL_ROOT as shown in Quick Start)
python3 "$SKILL_ROOT/scripts/with_server.py" --server "npm run dev" --port 3000 -- python test.py

# Multiple servers (backend + frontend)
python3 "$SKILL_ROOT/scripts/with_server.py" \
  --server "cd backend && python server.py" --port 3000 \
  --server "cd frontend && npm run dev" --port 5173 \
  -- python test.py
```

Run `python3 "$SKILL_ROOT/scripts/with_server.py" --help` first.

## Common Pitfalls

- **Inspecting DOM before the app renders:** Assert a key element is visible before reading the DOM on dynamic apps
- **Brittle CSS selectors:** Avoid `.btn.btn-primary`, use roles
- **Tests depend on order:** Each test must be independent
- **No cleanup:** Create and destroy test data per test
- **Over-testing with E2E:** Use unit tests for edge cases

## Reference Files

For advanced Playwright patterns, see:
- **[references/patterns.md](references/patterns.md)** - Network mocking, visual regression, fixtures
Files in this package (4)
  • SKILL.md 10 KB
  • agents/openai.yaml 1 KB
  • references/patterns.md 9 KB
  • scripts/with_server.py 8 KB

Versions

The database has no other skills named v1-e2e-testing.

Database snapshot: 13.11.2026 · package version 624b76339da9 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100playwright-e2e-testing
    Write, fix, or review Playwright end-to-end tests, especially for Next.js apps - locators, auth via storageState, flaky waits, server-side fetch mocking, CI against a production build. Use for *.spec.ts / e2e/ / playwright.config changes or flaky browser tests. For unit and…
  • 100e2e-testing
    Author, maintain, run, and debug resilient end-to-end browser tests (Playwright, Cypress) for critical user journeys. Use when writing automated E2E tests, codifying acceptance criteria into browser suites, or diagnosing flaky browser tests.
  • 100e2e-playwright-testing
    End-to-end testing with Playwright for web applications. Use when writing E2E tests, browser automation, form submission testing, or user flow testing. Triggers on "playwright", "e2e test", "browser test", "end-to-end", "form flow testing", or test files in tests/e2e/.
  • 100playwright-expert
    Use when writing E2E tests with Playwright, setting up test infrastructure, or debugging flaky browser tests. Invoke to write test scripts, create page objects, configure test fixtures, set up reporters, add CI integration, implement API mocking, or perform visual regression…
  • 100e2e-testing
    Plans, generates, runs, and heals Playwright end-to-end tests through a spec-first loop with Playwright Test Agents and `@playwright/mcp`. Use when adding E2E coverage or hardening a flaky flow; triggers on "add e2e", "test this flow", "verify the user journey", "/e2e-testing".
  • 95playwright-test
    Creates Playwright browser-based end-to-end tests for Next.js pages covering complete user journeys from start to finish. Use when the user asks to "write Playwright tests", "create e2e tests", "write integration tests", "test in the browser", or mentions end-to-end testing,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.