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:
   ```bash
   export SUPABASE_SERVICE_ROLE_KEY="your-service-role-key"
   ```
3. **Test users** (optional, will be auto-created):
   ```bash
   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

```bash
# Install Playwright and browsers
npm install
npx playwright install
```

## Running Tests

### All tests
```bash
npx playwright test
```

### Specific test file
```bash
npx playwright test tests/e2e/auth/login.spec.ts
```

### Specific test suite
```bash
npx playwright test tests/e2e/submission/
```

### Run in headed mode (see browser)
```bash
npx playwright test --headed
```

### Run in UI mode (interactive)
```bash
npx playwright test --ui
```

### Run with specific browser
```bash
npx playwright test --project=chromium
npx playwright test --project=firefox
npx playwright test --project=webkit
```

### Run tests with specific user role
```bash
npx playwright test --project=moderator
npx playwright test --project=admin
```

## Debugging Tests

### Debug mode
```bash
npx playwright test --debug
```

### Show test report
```bash
npx playwright show-report
```

### View trace for failed test
```bash
npx playwright show-trace trace.zip
```

## Writing New Tests

### 1. Create a test file
```typescript
// 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)
```typescript
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
```typescript
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
```typescript
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:
```typescript
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:
```typescript
test('my slow test', async ({ page }) => {
  test.setTimeout(120000); // 2 minutes
  // ...
});
```

## Resources

- [Playwright Documentation](https://playwright.dev/)
- [Playwright Best Practices](https://playwright.dev/docs/best-practices)
- [ThrillWiki Testing Guide](../docs/TESTING_GUIDE.md)

## 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
5. Grafana Cloud Loki for centralized test logs

## Grafana Cloud Loki Integration

All test runs automatically send logs to Grafana Cloud Loki for centralized monitoring and analysis.

### Viewing Logs in Grafana Cloud

1. **Access Grafana Cloud**: Go to your Grafana Cloud instance
2. **Navigate to Explore**: Click "Explore" in the left sidebar
3. **Select Loki Data Source**: Choose your Loki data source from the dropdown
4. **Query Test Logs**: Use LogQL queries to filter logs

### Common LogQL Queries

```logql
# All Playwright test logs
{job="playwright_tests"}

# Logs for specific browser
{job="playwright_tests", browser="chromium"}

# Failed tests only
{job="playwright_tests", status="failed"}

# Tests from specific branch
{job="playwright_tests", branch="main"}

# Tests from specific GitHub run
{job="playwright_tests", run_id="1234567890"}

# Logs from specific test file
{job="playwright_tests"} |= "login.spec.ts"

# Failed tests with error messages
{job="playwright_tests", status="failed"} | json | line_format "{{.test_name}}: {{.error}}"
```

### Local Testing with Grafana Cloud

Test your Grafana Cloud integration locally:

```bash
# Set environment variables
export GRAFANA_LOKI_URL="https://logs-prod-us-central1.grafana.net"
export GRAFANA_LOKI_USERNAME="123456"  # Your instance ID
export GRAFANA_LOKI_PASSWORD="glc_xxxxxxxxxxxxx"  # Your API key

# Run test script
chmod +x scripts/test-grafana-cloud.sh
./scripts/test-grafana-cloud.sh

# Run tests with Loki reporter
npx playwright test tests/e2e/auth/login.spec.ts --project=chromium
```

### Required GitHub Secrets

For CI/CD integration, ensure these secrets are configured in your GitHub repository:

- `GRAFANA_LOKI_URL` - Your Grafana Cloud Loki endpoint (e.g., `https://logs-prod-us-central1.grafana.net`)
- `GRAFANA_LOKI_USERNAME` - Your Grafana Cloud instance ID
- `GRAFANA_LOKI_PASSWORD` - Your Grafana Cloud API key (starts with `glc_`)

### Troubleshooting Grafana Cloud Connection

**401 Unauthorized Error:**
- Check your `GRAFANA_LOKI_USERNAME` (should be your instance ID)
- Verify your `GRAFANA_LOKI_PASSWORD` (API key starting with `glc_`)
- Regenerate API key if needed (Security > API Keys in Grafana Cloud)

**Logs Not Appearing:**
- Verify the correct region in `GRAFANA_LOKI_URL`
- Check time range in Grafana Explore (default is last 5 minutes)
- Run test script to validate connection: `./scripts/test-grafana-cloud.sh`

**429 Rate Limit Error:**
- Reduce test concurrency in `playwright.config.ts`
- Increase `flushInterval` in Loki reporter options