Add integration tests with disposable MySQL and runtime schema validation

[Copilot]

Summary

Implements full-stack integration testing with testcontainers-managed MySQL and Zod-based runtime schema validation to catch database schema mismatches before production. Tests run against actual DDL from init.sql, validating the complete data flow from database queries through API responses.

---

Type of Change

• 🧰 Maintenance / Tooling
• 🧾 Documentation Update

---

📄 Documentation

• All of the following applicable documentation changes were added
  • TESTING.md - Integration test guide and schema validation
  • INTEGRATION_TESTS_SUMMARY.md - Technical implementation details
  • QUICK_REFERENCE.md - Developer quick start guide
  • PR_SUMMARY.md - Comprehensive summary
• No documentation changes required

---

🧪 Testing

Architecture

Disposable Test Database

• Testcontainers spins up MySQL 8.3 container per test run
• Auto-seeds from server/docker/ddl/init.sql
• Isolated environment with cleanup between tests

Schema Validation

• Zod schemas define runtime contracts for all API responses
• 24 schema tests validate type safety, enums, ranges
• Catches mismatches: field renames, type changes, missing fields

Integration Tests

• Full CRUD flow for missions API tested against real database
• No mocks - exercises actual SQL queries and data transformations
• Schema validation on every response

Test Statistics

• Unit tests: 107 (was 83, +24)
• Schema tests: 24 (new)
• Integration tests: Full mission flow suite (new)
• Total: 131+ server tests

How Schema Mismatches Are Caught

// Example: Database field renamed
Database: latitude → lat
Integration test runs with real MySQL
Response: { lat: 49.939 }
Schema expects: { latitude: number }
❌ Test fails: "Expected latitude, got lat"
Developer fixes before merge

Three-layer validation catches breaking changes:

1. Database query (field presence)
2. Schema validation (type/structure match)
3. Integration test (assertion correctness)

Running Tests

# Unit tests (fast, no Docker) - 107 tests
cd server && npm test

# Schema validation - 24 tests
npm test -- schemas.test.mjs

# Integration tests (requires Docker) - ~30-60s
npm run test:integration

CI Pipeline

Server Unit Tests (107 tests, ~1.2s)
    ↓
Integration Tests (disposable MySQL, ~30-60s) ← NEW
    ↓
Client Tests (55 tests)
    ↓
E2E Tests (Playwright)

Integration tests run after unit tests pass, using testcontainers for MySQL. PR blocked if tests fail.

Key Files

Implementation

• server/src/schemas/api.schemas.mjs - Zod schemas (Bot, Mission, Temperature, Battery, Position)
• server/src/middleware/validation.middleware.mjs - Optional response validation middleware
• server/src/__tests__/integration/test-database.mjs - Testcontainers setup
• server/src/__tests__/integration/missions.integration.test.mjs - Full mission CRUD tests
• server/src/__tests__/schemas.test.mjs - 24 schema validation tests

Configuration

• server/vitest.integration.config.mjs - Integration test config (180s timeout)
• .github/workflows/ci-tests.yml - New integration-tests job

Schema Example

export const MissionSchema = z.object({
  missionID: z.number().int().positive(),
  missionName: z.string(),
  areaCoordinates: z.union([
    z.object({
      north: z.number(),
      south: z.number(),
      east: z.number(),
      west: z.number(),
    }),
    z.string(),
    z.null(),
  ]).optional(),
  progress: z.number().min(0).max(100).optional().nullable(),
  assignedBots: z.array(z.number().int()).optional(),
  // ...
});

// In tests
const validation = safeValidateSchema(MissionSchema, response.body);
expect(validation.success).toBe(true);

Integration Test Pattern

describe('Integration - Mission Flow', () => {
  let testDb, app;

  beforeAll(async () => {
    testDb = await createTestDatabase();  // Spin up MySQL container
    app = createTestApp(testDb.getConfig());
  }, 180000);

  afterAll(async () => {
    await testDb.stop();  // Cleanup
  });

  it('should create mission and validate schema', async () => {
    const response = await request(app)
      .post('/api/missions')
      .send({ missionName: 'Test', areaCoordinates: null })
      .expect(201);

    const validation = safeValidateSchema(MissionIdResponseSchema, response.body);
    expect(validation.success).toBe(true);
  });
});

---

Image of GUI change (if applicable)

N/A - Infrastructure changes only

---

✅ Pre-Merge Checklist

• PR started as a Draft
• Linked to correct Notion Task
• Branch includes updated documentation
• Code reviewed by peer
• Ready for final review by Software Lead
• All tests and builds pass
• Notion task updated to Ready for Review

---

🧾 Notes (Optional)

Dependencies Added

• testcontainers@^11.11.0 - Docker container management for tests
• zod@^4.3.6 - Runtime schema validation

Performance

• Unit tests: ~1.2s
• Integration tests: ~30-60s (first run ~1min for MySQL image download)
• Schema validation adds <1ms per response in test mode

Future Enhancements

• Add bot and temperature integration tests
• Enable validation middleware on all production routes
• Socket.io real-time data flow integration tests

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.