create-e2e-test

name	create-e2e-test
description	Create Playwright E2E tests for user flows. Use when testing complete user journeys, protected routes, form submissions, or cross-page navigation.

Create E2E Test

Creates Playwright end-to-end tests following Iridium testing patterns.

When to Use

• Testing complete user flows (sign-in → action → sign-out)
• Testing protected routes and middleware
• Verifying form submissions and validation
• User asks to "add E2E test", "test user flow", or "integration test"

Test Location & Naming

tests/
├── authentication.spec.ts    # Auth flow tests
├── dashboard.spec.ts         # Dashboard feature tests
├── profile.spec.ts           # Profile management tests
└── home.spec.ts              # Public page tests

Naming: *.spec.ts for all Playwright tests

Basic Test Structure

import { test, expect } from '@playwright/test';

test.describe('Feature Name', () => {
    test('should do something', async ({ page }) => {
        await page.goto('/');

        await expect(
            page.getByRole('heading', { name: 'Title' }),
        ).toBeVisible();
    });
});

Pattern 1: Testing Public Pages

import { test, expect } from '@playwright/test';

test.describe('Landing Page', () => {
    test('displays hero content', async ({ page }) => {
        await page.goto('/');

        await expect(
            page.getByRole('heading', { name: /welcome/i }),
        ).toBeVisible();
        await expect(page.getByText(/get started/i)).toBeVisible();
    });

    test('has correct meta tags', async ({ page }) => {
        await page.goto('/');

        await expect(page).toHaveTitle('Iridium');

        const metaDescription = page.locator('meta[name="description"]');
        await expect(metaDescription).toHaveAttribute(
            'content',
            /production-ready/i,
        );
    });

    test('navigates to sign-in page', async ({ page }) => {
        await page.goto();

         page.(, { :  }).();

         (page).();
    });
});

Pattern 2: Testing Protected Routes

import { test, expect } from '@playwright/test';

test.describe('Protected Routes', () => {
    test('redirects unauthenticated users to sign-in', async ({ page }) => {
        await page.goto('/dashboard');

        // Middleware should redirect to sign-in
        await expect(page).toHaveURL(/sign-in/);
    });

    test('displays dashboard for authenticated users', async ({ page }) => {
        // Login first (see authentication pattern below)
        await page.goto('/sign-in');
        await page.getByLabel(/email/i).fill('[e-mail]');
        await page.getByLabel(/password/i).fill('Admin123!');
        await page.getByRole('button', { name: /sign in/i }).click();

        // Wait for redirect to dashboard
        await expect(page).toHaveURL(/dashboard/);
        await expect(page.()).();
    });
});

Pattern 3: Testing Form Interactions

import { test, expect } from '@playwright/test';

test.describe('Sign In Form', () => {
    test.beforeEach(async ({ page }) => {
        await page.goto('/sign-in');
    });

    test('shows validation errors for empty submission', async ({ page }) => {
        await page.getByRole('button', { name: /sign in/i }).click();

        await expect(page.getByText(/email is required/i)).toBeVisible();
        await expect(page.getByText(/password is required/i)).toBeVisible();
    });

    test('shows error for invalid credentials', async ({ page }) => {
        await page.getByLabel(/email/i).fill('[e-mail]');
        await page.getByLabel(/password/i).fill('wrongpassword');
        await page.getByRole('button', { name: /sign in/i }).();

         (page.()).();
    });

    (,  ({ page }) => {
         page.().();
         page.().();
         page.(, { :  }).();

         (page).();
    });
});

Pattern 4: Testing API Calls via UI

import { test, expect } from '@playwright/test';

test.describe('Profile Update', () => {
    test('saves profile changes successfully', async ({ page }) => {
        // Login first
        await page.goto('/sign-in');
        await page.getByLabel(/email/i).fill('[e-mail]');
        await page.getByLabel(/password/i).fill('Admin123!');
        await page.getByRole('button', { name: /sign in/i }).click();
        await expect(page).toHaveURL(/dashboard/);

        // Navigate to profile
        await page.goto('/portal');

        // Listen for API response
        const responsePromise = page.waitForResponse(
            (response) =>
                response.url().includes('/api/profile') &&
                response.status() === 200,
        );

        
         page.().();
         page.(, { :  }).();

        
         responsePromise;

        
         (page.()).();
    });
});

Pattern 5: Testing Role-Based Access

import { test, expect } from '@playwright/test';

test.describe('Role-Based Access', () => {
    test('admin can access admin routes', async ({ page }) => {
        // Login as admin
        await page.goto('/sign-in');
        await page.getByLabel(/email/i).fill('[e-mail]');
        await page.getByLabel(/password/i).fill('Admin123!');
        await page.getByRole('button', { name: /sign in/i }).click();

        await page.goto('/admin');
        await expect(page.getByText(/admin panel/i)).toBeVisible();
    });

    test('regular user cannot access admin routes', async ({ page }) => {
        // Login as regular user
        await page.goto('/sign-in');
        await page.getByLabel(/email/i).fill();
         page.().();
         page.(, { :  }).();

         page.();

        
         (page.()).();
    });
});

Selectors - Best Practices

DO use semantic selectors:

page.getByRole('button', { name: /submit/i })
page.getByRole('heading', { name: /welcome/i })
page.getByLabel(/email/i)
page.getByText(/success/i)
page.getByRole('link', { name: /sign in/i })

DON'T use CSS selectors:

// ❌ Avoid these
page.locator('.btn-primary')
page.locator('#submit-button')
page.locator('div.form-field input')

Running E2E Tests

npm run e2e           # Headless mode (CI)
npm run e2e:ui        # Visual UI mode (recommended for dev)
npm run e2e:headed    # See browser during tests
npm run e2e:debug     # Step-by-step debugging
npm run e2e:report    # View HTML report

Test Credentials

From prisma/seed.ts:

Email	Password	Role
[e-mail]	Admin123!	ADMIN
[e-mail]	Editor123!	EDITOR
[e-mail]	User123!	USER

Configuration

Tests are configured in playwright.config.ts:

• Base URL: http://localhost:5173
• Browsers: Chromium, Firefox, WebKit
• Auto-start: Playwright starts dev server automatically

Common Assertions

// URL assertions
await expect(page).toHaveURL(/dashboard/);
await expect(page).toHaveURL('http://localhost:5173/profile');

// Title assertion
await expect(page).toHaveTitle('Dashboard - Iridium');

// Element visibility
await expect(page.getByText('Hello')).toBeVisible();
await expect(page.getByRole('button')).toBeDisabled();

// Count assertions
await expect(page.getByRole('listitem')).toHaveCount(5);

// Attribute assertions
await expect(page.locator('input')).toHaveValue('[e-mail]');

CI/CD Integration

E2E tests run in GitHub Actions. Key points:

• Uses SQLite in-memory for Prisma client generation
• Playwright auto-starts dev server
• HTML reports uploaded as artifacts

Anti-Patterns

• Using CSS class selectors instead of semantic selectors
• Hardcoding wait times (page.waitForTimeout(1000))
• Testing implementation details
• Not waiting for elements before interacting
• Missing authentication setup for protected routes

Full Reference

See .github/instructions/playwright.instructions.md for comprehensive documentation.