Plain English E2E Testing

Write end-to-end tests in plain markdown. Claude interprets and executes them using Playwright. No CSS selectors to maintain, no fragile test code.

Why This Approach

Traditional E2E tests are:

Fragile - CSS selectors break with every UI change
Hard to maintain - Test code often outlives the features it tests
Developer-only - QA and product can't read or write them

Plain English tests are:

Resilient - Claude finds elements by intent, not selectors
Self-documenting - Tests read like user stories
Team-accessible - Anyone can write and understand them

How to Use

Basic Command

/e2e

This runs all test files in your e2e/ or tests/e2e/ directory.

Test File Format

Create .md files with test scenarios:

# Login Flow

## Happy Path
1. Navigate to /login
2. Enter "testuser@example.com" in the email field
3. Enter "password123" in the password field
4. Click the "Sign In" button
5. Verify the dashboard is displayed
6. Verify welcome message contains "testuser"

## Invalid Credentials
1. Navigate to /login
2. Enter "wrong@example.com" in the email field
3. Enter "wrongpassword" in the password field
4. Click the "Sign In" button
5. Verify error message "Invalid credentials" is displayed
6. Verify still on login page

Supported Actions

Navigation

Navigate to /path
Navigate to https://example.com
Go back / Go forward
Refresh the page

Interactions

Click the "Button Text" button
Click the link containing "text"
Enter "value" in the [field name] field
Select "option" from the [dropdown name] dropdown
Check the [checkbox name] checkbox
Uncheck the [checkbox name] checkbox
Scroll to [element description]
Hover over [element description]

Verification

Verify [element] is displayed/visible
Verify [element] is not displayed/hidden
Verify [element] contains "text"
Verify [element] equals "exact text"
Verify page title is "Title"
Verify URL contains "/path"
Verify URL is "exact/url"

Waits

Wait for [element] to appear
Wait for [element] to disappear
Wait 2 seconds
Wait for network to be idle

Data-Driven

For each row in data.csv: [actions using {{column_name}}]

Test Organization

project/
  e2e/
    login.md
    checkout.md
    user-profile.md
    data/
      users.csv
      products.json

Running Specific Tests

/e2e login.md

/e2e checkout.md --headed

Configuration

Create e2e/config.md for shared settings:

# E2E Configuration

## Base URL
http://localhost:3000

## Default Timeout
30 seconds

## Before Each Test
1. Clear cookies
2. Clear local storage

## After Each Test
1. Take screenshot if failed
2. Save console logs if failed

## Test Users
- admin: admin@example.com / adminpass
- user: user@example.com / userpass

Screenshot on Failure

When a test fails, Claude automatically:

Takes a screenshot of the current state
Saves it to e2e/screenshots/[test-name]-[timestamp].png
Includes the screenshot in the failure report

Example Session

User: /e2e

Claude: Running E2E tests...

e2e/login.md
  ✓ Happy Path (2.3s)
  ✓ Invalid Credentials (1.8s)
  ✓ Forgot Password Flow (3.1s)

e2e/checkout.md
  ✓ Add to Cart (1.5s)
  ✗ Complete Purchase (4.2s)
    Failed at step 5: "Click the 'Pay Now' button"
    Error: Button not found - payment form not loaded
    Screenshot: e2e/screenshots/checkout-complete-purchase-1704672000.png

e2e/user-profile.md
  ✓ Update Name (2.0s)
  ✓ Change Password (2.8s)

Results: 6 passed, 1 failed

Best Practices

One scenario per section - Keep tests focused
Use descriptive names - "Checkout with coupon" not "Test 3"
Include setup steps - Don't assume state from other tests
Test the happy path first - Then edge cases
Keep tests independent - Each test should work in isolation

Integration with CI

Run in headless mode for CI:

claude -p "Run /e2e --headless and report results"

Limitations

Complex JavaScript interactions may need explicit waits
Canvas/WebGL elements can't be verified by content
Shadow DOM requires explicit handling
Some anti-bot protections may interfere

Credits

Inspired by @Shpigford's approach to using markdown for E2E tests with Claude and Playwright.

e2e-testing