Docs/Guides/Testing

Testing Guide

Unit and integration tests with Vitest, end-to-end tests with Playwright

Overview

EdgeURL uses two testing frameworks:

Vitest

Unit and integration tests. Uses happy-dom environment with React plugin support and V8 coverage provider.

Playwright

End-to-end browser tests across Chromium, Firefox, WebKit, and mobile viewports (Pixel 5, iPhone 12).

Unit and Integration Tests (Vitest)

Running Tests

npm run testRun all unit tests once

npm run test:watchRun tests in watch mode (re-runs on file changes)

npm run test:uiOpen Vitest UI in browser for interactive testing

npm run test:coverageRun tests with V8 coverage report (text, JSON, HTML)

Configuration

Vitest is configured in vitest.config.ts at the project root:

// Key configuration: { test: { environment: 'happy-dom', // DOM simulation globals: true, // Global test APIs (describe, it, expect) setupFiles: ['./tests/setup.ts'], exclude: [ '**/node_modules/**', '**/dist/**', '**/.next/**', '**/e2e/**', // E2E tests use Playwright '**/*.e2e.*', ], coverage: { provider: 'v8', reporter: ['text', 'json', 'html'], }, }, resolve: { alias: { '@': './' }, // Path alias matching tsconfig }, }

Writing Tests

Test files live in tests/__tests__/ mirroring the source directory structure. Globals mode is enabled, so you do not need to import describe, it, or expect.

// tests/__tests__/lib/example.test.ts import { myFunction } from '@/lib/example' describe('myFunction', () => { it('should return expected result', () => { const result = myFunction('input') expect(result).toBe('expected') }) it('should handle edge cases', () => { expect(() => myFunction('')).toThrow() }) })

Test Setup

The setup file at tests/setup.ts runs before all tests. It configures environment mocks, sets up test fixtures, and initializes any required test infrastructure.

End-to-End Tests (Playwright)

Running E2E Tests

npm run test:e2eRun all E2E tests

npm run test:e2e:uiOpen Playwright UI for interactive debugging

Configuration

Playwright is configured in playwright.config.ts:

// Key configuration: { testDir: './tests/e2e', fullyParallel: true, retries: process.env.CI ? 2 : 0, // Retry on CI only workers: process.env.CI ? 1 : undefined, reporter: 'html', use: { baseURL: 'http://localhost:3000', trace: 'on-first-retry', screenshot: 'only-on-failure', }, // Browser projects: // - Desktop Chrome, Firefox, WebKit // - Mobile Chrome (Pixel 5), Mobile Safari (iPhone 12) webServer: { command: 'npm run dev', url: 'http://localhost:3000', reuseExistingServer: !process.env.CI, }, }

Browser Coverage

E2E tests run across 5 browser configurations:

Chromium

Desktop Chrome

Firefox

Desktop Firefox

WebKit

Desktop Safari

Mobile Chrome

Pixel 5

Mobile Safari

iPhone 12

Writing E2E Tests

E2E test files live in tests/e2e/. Playwright automatically starts the dev server before running tests.

// tests/e2e/example.spec.ts import { test, expect } from '@playwright/test' test('homepage loads correctly', async ({ page }) => { await page.goto('/') await expect(page).toHaveTitle(/EdgeURL/) }) test('link creation flow', async ({ page }) => { await page.goto('/dashboard/links') // ... test the full user flow })

Best Practices

Test file naming

Use .test.ts for unit/integration tests and .spec.ts for E2E tests.

Path aliases

Use the @/ alias for imports in test files, matching the application code style.

Isolate tests

Each test should be independent. Do not rely on test execution order. Use setup and teardown hooks for shared state.

Mock external services

Mock Supabase, Stripe, Redis, and other external dependencies in unit tests. Use the setup file for common mocks.

Next Steps

→ Local Development Setup → Deployment Checklist → API Reference

Docs/Guides/Testing

Testing Guide

Unit and integration tests with Vitest, end-to-end tests with Playwright

Overview

EdgeURL uses two testing frameworks:

Vitest

Unit and integration tests. Uses happy-dom environment with React plugin support and V8 coverage provider.

Playwright

End-to-end browser tests across Chromium, Firefox, WebKit, and mobile viewports (Pixel 5, iPhone 12).

Unit and Integration Tests (Vitest)

Running Tests

npm run testRun all unit tests once

npm run test:watchRun tests in watch mode (re-runs on file changes)

npm run test:uiOpen Vitest UI in browser for interactive testing

npm run test:coverageRun tests with V8 coverage report (text, JSON, HTML)

Configuration

Vitest is configured in vitest.config.ts at the project root:

Writing Tests

Test files live in tests/__tests__/ mirroring the source directory structure. Globals mode is enabled, so you do not need to import describe, it, or expect.

Test Setup

The setup file at tests/setup.ts runs before all tests. It configures environment mocks, sets up test fixtures, and initializes any required test infrastructure.

End-to-End Tests (Playwright)

Running E2E Tests

npm run test:e2eRun all E2E tests

npm run test:e2e:uiOpen Playwright UI for interactive debugging

Configuration

Playwright is configured in playwright.config.ts:

Browser Coverage

E2E tests run across 5 browser configurations:

Chromium

Desktop Chrome

Firefox

Desktop Firefox

WebKit

Desktop Safari

Mobile Chrome

Pixel 5

Mobile Safari

iPhone 12

Writing E2E Tests

E2E test files live in tests/e2e/. Playwright automatically starts the dev server before running tests.

Best Practices

Test file naming

Use .test.ts for unit/integration tests and .spec.ts for E2E tests.

Path aliases

Use the @/ alias for imports in test files, matching the application code style.

Isolate tests

Each test should be independent. Do not rely on test execution order. Use setup and teardown hooks for shared state.

Mock external services

Mock Supabase, Stripe, Redis, and other external dependencies in unit tests. Use the setup file for common mocks.

Next Steps

→ Local Development Setup → Deployment Checklist → API Reference