Running Tests

The Supabase TDD Boilerplate follows a comprehensive three-layer testing approach to ensure your application's reliability. This guide will show you how to run these tests locally.

Three-Layer Testing Approach

Our testing strategy consists of three layers:

1. Unit Tests: Testing individual components and functions in isolation
2. Integration Tests: Testing component interactions and API endpoints
3. E2E Tests: Testing complete user flows with Playwright

Available Test Scripts

Our root package.json includes several scripts for running tests:

{
  "scripts": {
    "test": "NODE_OPTIONS='--experimental-vm-modules' vitest run --exclude \"**/*.e2e.{test,spec}.{ts,tsx}\" --exclude \"**/e2e/**\"",
    "test:e2e": "cd apps/web && npx playwright test",
    "test:e2e:ui": "cd apps/web && npx playwright test --ui",
    "test:e2e:debug": "cd apps/web && npx playwright test --debug",
    "test:e2e:report": "cd apps/web && npx playwright show-report",
    "test:integration": "NODE_ENV=development cd apps/web && vitest run -c vitest.integration.config.ts",
    "test:integration:watch": "NODE_ENV=development cd apps/web && vitest -c vitest.integration.config.ts"
  }
}

Test Script Descriptions

• test: Runs all unit tests using Vitest, excluding E2E tests. This is the default test command.
• test:e2e: Executes all end-to-end tests using Playwright in the web application.
• test:e2e:ui: Opens Playwright's UI mode for running and debugging E2E tests with a visual interface.
• test:e2e:debug: Runs E2E tests in debug mode, allowing step-by-step execution and inspection.
• test:e2e:report: Displays the HTML report of the last E2E test run.
• test:integration: Runs all integration tests in the web application using Vitest.
• test:integration:watch: Runs integration tests in watch mode, automatically re-running tests when files change.

Running Integration Tests

Integration tests focus on testing component interactions and API endpoints:

# Run all integration tests
pnpm test:integration

# Run integration tests in watch mode
pnpm test:integration --watch

Integration tests are located in:

apps/web/
├── components/     # Component interaction tests alongside components
└── api/           # API integration tests alongside API routes

apps/api/
├── routes/        # Route integration tests alongside routes
└── services/      # Service integration tests alongside services

Running E2E Tests

E2E tests use Playwright to test complete user flows:

# Run all E2E tests
pnpm test:e2e

# Run E2E tests in UI mode
pnpm test:e2e --ui

# Run E2E tests in debug mode
pnpm test:e2e --debug

E2E tests are located in:

apps/web/e2e/
├── auth/          # Authentication flows
├── dashboard/     # Dashboard flows
└── organization/  # Organization management flows

Writing Tests

When adding new features or modifying existing ones, follow these guidelines:

Unit Tests

• Place component tests alongside their components (e.g., Component.tsx and Component.test.tsx)
• Place hook tests alongside their hooks (e.g., useHook.ts and useHook.test.ts)
• Place utility tests alongside their utilities (e.g., utils.ts and utils.test.ts)
• Place API tests alongside their routes (e.g., route.ts and route.test.ts)
• Use .test.ts or .test.tsx extension

Integration Tests

• Place component interaction tests alongside their components (e.g., Component.tsx and Component.integration.ts)
• Place API integration tests alongside their API routes (e.g., route.ts and route.integration.ts)
• Place route integration tests alongside their routes
• Place service integration tests alongside their services
• Use .integration.ts extension

E2E Tests

• Place authentication tests in apps/web/e2e/auth/
• Place dashboard tests in apps/web/e2e/dashboard/
• Place organization tests in apps/web/e2e/organization/
• Use .spec.ts extension

Test Coverage

To generate and view test coverage reports:

# Generate coverage report
pnpm test:coverage

# View coverage report
open coverage/index.html

Next Steps

1. Set up Supabase locally
2. Configure the database
3. Set up Google Sign-In