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:

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:

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:

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:

npm run test:schema

Run specific test suite:

npx playwright test schema-validation --grep "Entity Tables"

Run in UI mode for debugging:

npx playwright test schema-validation --ui

Generate detailed report:

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:

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:

# .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 - Complete field mappings
• Submission Pipeline - Pipeline overview
• Versioning System - Version table details
• Moderation Workflow - 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:

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