thrilltrack-explorer/tests/README.md

ThrillWiki E2E Testing with Playwright

This directory contains comprehensive end-to-end tests for ThrillWiki using Playwright.

Overview

These tests replace the problematic backend integration tests with proper browser-based E2E tests that:

• ✅ Test the actual user experience
• ✅ Respect security policies (RLS)
• ✅ Validate the complete submission → moderation → approval flow
• ✅ Run in real browsers (Chromium, Firefox, WebKit)
• ✅ Support parallel execution for speed
• ✅ Capture videos and screenshots on failure

Directory Structure

tests/
├── e2e/                          # End-to-end test specs
│   ├── auth/                     # Authentication tests
│   ├── submission/               # Entity submission tests
│   ├── moderation/               # Moderation queue tests
│   ├── versioning/               # Version history tests
│   ├── admin/                    # Admin panel tests
│   └── public/                   # Public browsing tests
├── fixtures/                     # Test fixtures and helpers
│   ├── auth.ts                   # Authentication helpers
│   ├── database.ts               # Direct DB access for setup/teardown
│   └── test-data.ts              # Test data generators
├── helpers/                      # Utility functions
│   └── page-objects/             # Page Object Models
├── setup/                        # Global setup and teardown
│   ├── global-setup.ts           # Runs before all tests
│   └── global-teardown.ts        # Runs after all tests
└── README.md                     # This file

Prerequisites

1. Node.js and npm installed
2. Supabase service role key for test setup/teardown:

   export SUPABASE_SERVICE_ROLE_KEY="your-service-role-key"
   

3. Test users (optional, will be auto-created):

   export TEST_USER_EMAIL="test-user@thrillwiki.test"
   export TEST_USER_PASSWORD="TestUser123!"
   export TEST_MODERATOR_EMAIL="test-moderator@thrillwiki.test"
   export TEST_MODERATOR_PASSWORD="TestModerator123!"
   

Installation

# Install Playwright and browsers
npm install
npx playwright install

Running Tests

All tests

npx playwright test

Specific test file

npx playwright test tests/e2e/auth/login.spec.ts

Specific test suite

npx playwright test tests/e2e/submission/

Run in headed mode (see browser)

npx playwright test --headed

Run in UI mode (interactive)

npx playwright test --ui

Run with specific browser

npx playwright test --project=chromium
npx playwright test --project=firefox
npx playwright test --project=webkit

Run tests with specific user role

npx playwright test --project=moderator
npx playwright test --project=admin

Debugging Tests

Debug mode

npx playwright test --debug

Show test report

npx playwright show-report

View trace for failed test

npx playwright show-trace trace.zip

Writing New Tests

1. Create a test file

// tests/e2e/feature/my-feature.spec.ts
import { test, expect } from '@playwright/test';

test.describe('My Feature', () => {
  test('should do something', async ({ page }) => {
    await page.goto('/my-feature');
    await expect(page.getByText('Hello')).toBeVisible();
  });
});

2. Use Page Objects (recommended)

import { MyFeaturePage } from '../../helpers/page-objects/MyFeaturePage';

test('should use page object', async ({ page }) => {
  const myFeature = new MyFeaturePage(page);
  await myFeature.goto();
  await myFeature.doSomething();
  await myFeature.expectSuccess();
});

3. Use test data generators

import { generateParkData } from '../../fixtures/test-data';

test('should create park', async ({ page }) => {
  const parkData = generateParkData({ name: 'Custom Park' });
  // Use parkData in your test
});

4. Clean up test data

import { cleanupTestData } from '../../fixtures/database';

test.afterAll(async () => {
  await cleanupTestData();
});

Test Data Management

All test data is automatically marked with is_test_data: true and cleaned up after tests run.

Manual cleanup

If tests fail and leave data behind:

import { cleanupTestData } from './fixtures/database';
await cleanupTestData();

Or use the "Emergency Cleanup" button in the admin UI at /admin/settings.

Authentication

Tests use pre-authenticated browser contexts to avoid logging in for every test:

• .auth/user.json - Regular user
• .auth/moderator.json - Moderator with AAL2
• .auth/admin.json - Admin with AAL2
• .auth/superuser.json - Superuser with AAL2

These are created automatically during global setup.

CI/CD Integration

Tests run automatically on GitHub Actions:

• On every pull request
• On push to main branch
• Results posted as PR comments

See .github/workflows/playwright.yml for configuration.

Best Practices

1. Use Page Objects - Encapsulate page interactions
2. Mark test data - Always set is_test_data: true
3. Clean up - Use test.afterAll() or test.afterEach()
4. Use fixtures - Reuse auth, database, and test data helpers
5. Test user flows - Not individual functions
6. Avoid hardcoded waits - Use waitForLoadState() or waitForSelector()
7. Take screenshots - On failure (automatic)
8. Parallelize - Tests run in parallel by default

Common Issues

"Service role key not configured"

Set the SUPABASE_SERVICE_ROLE_KEY environment variable.

"Test data not cleaned up"

Run npx playwright test --project=cleanup or use the admin UI emergency cleanup button.

"Lock timeout"

Some tests involving moderation locks may take longer. Increase timeout:

test('my slow test', async ({ page }) => {
  test.setTimeout(120000); // 2 minutes
  // ...
});

Resources

• Playwright Documentation
• Playwright Best Practices
• ThrillWiki Testing Guide

Support

For questions or issues with tests, check:

1. This README
2. Playwright docs
3. Test failure screenshots/videos in test-results/
4. GitHub Actions logs for CI failures