thrilltrack-explorer/tests/integration/README.md

# Integration Tests

This directory contains integration tests for the ThrillWiki submission pipeline and data integrity.

## Schema Validation Tests

**File**: `schema-validation.test.ts`

### Purpose

Automated tests that validate schema consistency across the entire submission pipeline:

- **Submission Tables**: Ensures submission tables match their corresponding main entity tables
- **Version Tables**: Validates version tables have all main table fields plus version metadata
- **Critical Fields**: Checks for known problematic fields (e.g., `ride_type` vs `category`)
- **Function Alignment**: Verifies critical database functions exist and are accessible

### Why This Matters

The submission pipeline depends on exact schema alignment between:
1. Main entity tables (`parks`, `rides`, `companies`, `ride_models`)
2. Submission tables (`park_submissions`, `ride_submissions`, etc.)
3. Version tables (`park_versions`, `ride_versions`, etc.)

**Without these tests**, schema mismatches can cause:
- ❌ Approval failures with cryptic "column does not exist" errors
- ❌ Data loss when fields are missing from submission tables
- ❌ Version history corruption when fields don't match
- ❌ Production incidents that are difficult to debug

**With these tests**, we catch issues:
- ✅ During development, before they reach production
- ✅ In CI/CD, preventing bad migrations from deploying
- ✅ Immediately after schema changes, with clear error messages

### Test Categories

#### 1. Entity Table Validation
Compares main entity tables with their submission counterparts:
```typescript
parks ↔ park_submissions
rides ↔ ride_submissions
companies ↔ company_submissions
ride_models ↔ ride_model_submissions
```

**Checks**:
- All fields from main table exist in submission table (except excluded metadata)
- Data types match exactly
- Required fields are marked NOT NULL in both

#### 2. Version Table Validation
Ensures version tables have complete field coverage:
```typescript
parks → park_versions
rides → ride_versions
companies → company_versions
ride_models → ride_model_versions
```

**Checks**:
- All main table fields exist (accounting for known name variations)
- Version metadata fields are present (`version_id`, `version_number`, etc.)
- Change tracking fields are properly defined

#### 3. Critical Field Validation
Tests specific known problem areas:

**Critical Test Cases**:
- ✅ `rides` table does NOT have `ride_type` (prevents "column does not exist" error)
- ✅ `rides` table DOES have `category` as NOT NULL
- ✅ `ride_models` table has BOTH `category` and `ride_type`
- ✅ All entities have required base fields (`id`, `name`, `slug`, etc.)
- ✅ All submission tables have `submission_id` foreign key

#### 4. Function Alignment
Validates critical database functions:
- `create_entity_from_submission`
- `update_entity_from_submission`
- `process_approval_transaction`

#### 5. Field Name Variations
Documents and validates known column name differences:
```typescript
ride_versions.height_requirement_cm ↔ rides.height_requirement
ride_versions.gforce_max ↔ rides.max_g_force
ride_versions.inversions_count ↔ rides.inversions
ride_versions.height_meters ↔ rides.max_height_meters
ride_versions.drop_meters ↔ rides.drop_height_meters
```

### Running the Tests

**Run all schema validation tests:**
```bash
npm run test:schema
```

**Run specific test suite:**
```bash
npx playwright test schema-validation --grep "Entity Tables"
```

**Run in UI mode for debugging:**
```bash
npx playwright test schema-validation --ui
```

**Generate detailed report:**
```bash
npx playwright test schema-validation --reporter=html
```

### Environment Setup

These tests require:
- `SUPABASE_SERVICE_ROLE_KEY` environment variable
- Access to the Supabase project database
- Playwright test runner

**Example `.env.test`:**
```env
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key_here
```

### Expected Output

**✅ All passing (healthy schema):**
```
  ✓ parks: submission table matches main table schema (245ms)
  ✓ rides: submission table matches main table schema (198ms)
  ✓ companies: submission table matches main table schema (187ms)
  ✓ ride_models: submission table matches main table schema (203ms)
  ✓ park_versions: has all main table fields plus version metadata (256ms)
  ✓ ride_versions: has all main table fields plus version metadata (234ms)
  ✓ rides table does NOT have ride_type column (145ms)
  ✓ rides table DOES have category column (NOT NULL) (152ms)
```

**❌ Failure example (schema mismatch):**
```
  ✕ rides: submission table matches main table schema (203ms)

    Error: ride_submissions is missing fields: category
    
    Expected: 0
    Received: 1
```

### Continuous Integration

Add to your CI/CD pipeline:

```yaml
# .github/workflows/test.yml
- name: Run Schema Validation Tests
  run: npm run test:schema
  env:
    SUPABASE_SERVICE_ROLE_KEY: ${{ secrets.SUPABASE_SERVICE_ROLE_KEY }}
```

This prevents schema mismatches from reaching production.

### When to Run

**Always run these tests:**
- ✅ After any database migration
- ✅ Before deploying submission pipeline changes
- ✅ After modifying entity schemas
- ✅ When adding new entity types
- ✅ In CI/CD for every pull request

**Especially critical after:**
- Adding/removing columns from entity tables
- Modifying data types
- Changing NOT NULL constraints
- Updating database functions

### Maintenance

**When adding new entity types:**
1. Add validation tests for the new entity
2. Add tests for submission table
3. Add tests for version table (if applicable)
4. Update this README

**When schema changes are intentional:**
1. Review failing tests carefully
2. Update `EXCLUDED_FIELDS` or `VERSION_METADATA_FIELDS` if needed
3. Document any new field name variations in `normalizeColumnName()`
4. Update `docs/submission-pipeline/SCHEMA_REFERENCE.md`

### Debugging Failed Tests

**"Missing fields" error:**
1. Check if field was recently added to main table
2. Verify migration added it to submission table too
3. Run migration to add missing field
4. Re-run tests

**"Type mismatch" error:**
1. Compare data types in both tables
2. Check for accidental type change in migration
3. Fix type inconsistency
4. Re-run tests

**"Column does not exist" in production:**
1. Run schema validation tests immediately
2. Identify which table is missing the field
3. Create emergency migration to add field
4. Deploy with high priority

### Related Documentation

- [Schema Reference](../../docs/submission-pipeline/SCHEMA_REFERENCE.md) - Complete field mappings
- [Submission Pipeline](../../docs/submission-pipeline/README.md) - Pipeline overview
- [Versioning System](../../docs/versioning/README.md) - Version table details
- [Moderation Workflow](../../docs/moderation/README.md) - Approval process

---

## Other Integration Tests

### Moderation Security Tests

**File**: `moderation-security.test.ts`

Tests role validation, lock enforcement, and rate limiting in the moderation system.

**Run:**
```bash
npx playwright test moderation-security
```

---

## Contributing

When adding new integration tests:
1. Follow existing test structure
2. Use descriptive test names
3. Add comments explaining what's being tested
4. Update this README
5. Ensure tests are idempotent (can run multiple times)
6. Clean up test data after completion