Keep/keep-notes/tests/migration/README.md

Migration Tests

This directory contains comprehensive test suites for validating Prisma schema and data migrations for the Keep notes application.

Test Files

• setup.ts - Test utilities for database setup, teardown, and test data generation
• schema-migration.test.ts - Validates schema migrations (tables, columns, indexes, relationships)
• data-migration.test.ts - Validates data migration (transformation, integrity, edge cases)
• rollback.test.ts - Validates rollback capability and data recovery
• performance.test.ts - Validates migration performance with various dataset sizes
• integrity.test.ts - Validates data integrity (no loss/corruption, foreign keys, indexes)

Running Tests

Run all migration tests

npm run test:migration

Run migration tests in watch mode

npm run test:migration:watch

Run specific test file

npm run test:unit tests/migration/schema-migration.test.ts

Run tests with coverage

npm run test:unit:coverage

Test Coverage Goals

• Minimum threshold: 80% coverage for migration-related code
• Coverage areas: Migration scripts, test utilities, schema transformations
• Exclude from coverage: Test files themselves (*.test.ts)

Test Structure

Schema Migration Tests

• Core table existence (User, Note, Notebook, Label, etc.)
• AI feature tables (AiFeedback, MemoryEchoInsight, UserAISettings)
• Note table AI fields (autoGenerated, aiProvider, aiConfidence, etc.)
• Index creation on critical fields
• Foreign key relationships
• Unique constraints
• Default values

Data Migration Tests

• Empty database migration
• Basic note migration
• AI fields data migration
• AiFeedback data migration
• MemoryEchoInsight data migration
• UserAISettings data migration
• Data integrity verification
• Edge cases (empty strings, long content, special characters)
• Performance benchmarks

Rollback Tests

• Schema state verification
• Column/table rollback simulation
• Data recovery after rollback
• Orphaned record handling
• Rollback safety checks
• Rollback error handling

Performance Tests

• Empty migration (< 1 second)
• Small dataset (10 notes) (< 1 second)
• Medium dataset (100 notes) (< 5 seconds)
• Target dataset (1,000 notes) (< 30 seconds)
• Stress test (10,000 notes) (< 30 seconds)
• AI features performance
• Database size tracking
• Concurrent operations

Integrity Tests

• No data loss
• No data corruption
• Foreign key relationship maintenance
• Index integrity
• AI fields preservation
• Batch operations integrity
• Data type integrity

Test Utilities

The setup.ts file provides reusable utilities:

• setupTestEnvironment() - Initialize test environment
• createTestPrismaClient() - Create isolated Prisma client
• initializeTestDatabase() - Apply all migrations
• cleanupTestDatabase() - Clean up test database
• createSampleNotes() - Generate sample test notes
• createSampleAINotes() - Generate AI-enabled test notes
• measureExecutionTime() - Performance measurement helper
• verifyDataIntegrity() - Data integrity checks
• verifyTableExists() - Table existence verification
• verifyColumnExists() - Column existence verification
• verifyIndexExists() - Index existence verification
• getTableSchema() - Get table schema information
• getDatabaseSize() - Get database file size

Acceptance Criteria Coverage

✅ AC 1: Unit tests exist for all migration scripts ✅ AC 2: Integration tests verify database state before/after migrations ✅ AC 3: Test suite validates rollback capability ✅ AC 4: Performance tests ensure migrations complete within acceptable limits ✅ AC 5: Tests verify data integrity (no loss/corruption) ✅ AC 6: Test coverage meets minimum threshold (80%)

CI/CD Integration

These tests are configured to run in CI/CD pipelines:

# Example CI configuration
- name: Run migration tests
  run: npm run test:migration

- name: Check coverage
  run: npm run test:unit:coverage

Isolation

Each test suite runs in an isolated test database:

• Location: prisma/test-databases/migration-test.db
• Lifecycle: Created before test suite, deleted after
• Conflict: No conflict with development database

Troubleshooting

Tests fail with database locked error

Ensure no other process is using the test database. The test utilities automatically clean up the test database.

Tests timeout

Increase timeout values in vitest.config.ts if necessary.

Coverage below threshold

Review coverage report in coverage/index.html to identify untested code.

Contributing

When adding new migrations:

1. Add corresponding test cases in appropriate test files
2. Update this README with new test coverage
3. Ensure coverage threshold (80%) is maintained
4. Run all migration tests before committing