# Local Database Requirements (Testing)

## Purpose
Define local database requirements for reliable, repeatable testing of the calendar plugin.

## Scope
This document applies to local development and automated test execution using the local compatibility harness.

It covers:

- Local test database setup
- Schema creation and migration behavior
- Test data seeding and isolation
- Reset/cleanup requirements between test runs

## Environment Assumptions
- Database runs locally or in a local containerized service.
- Test database is separate from production/staging databases.
- All plugin date/time values are treated as `Europe/London` unless a test explicitly validates timezone conversion behavior.

## Database Access Requirements
- Tests must connect using non-production credentials.
- Credentials are provided via local environment configuration (e.g., `credentials/.env`) and must not be hardcoded in source.
- Test runner/harness must fail fast with clear errors if DB connectivity is unavailable.

## Schema Requirements
- Plugin schema must be created using WordPress APIs used in runtime lifecycle (`$wpdb`, `dbDelta()`), not ad-hoc raw SQL scripts as the primary path.
- Schema initialization for tests must be idempotent.
- Schema versioning must be testable (fresh install and upgrade path).

## Required Data Coverage
Seed test data must include:

- Single non-recurring event
- All-day event
- Daily recurrence
- Weekly recurrence
- Monthly recurrence
- Yearly recurrence
- Custom recurrence with:
  - No end date
  - Count-limited (`create <n> appointments`)
  - Date-limited (`repeat until <date>`)
- Edge cases:
  - Month-end boundaries
  - Leap-year behavior
  - DST boundary behavior for `Europe/London`

## Isolation and Determinism
- Each test run must be deterministic.
- Test cases must not depend on leftover data from previous runs.
- Harness must provide one of:
  - Full DB reset before suite/test group, or
  - Transactional rollback strategy.

## Reset and Cleanup Requirements
- A documented command/process must reset local test DB to a known baseline.
- Cleanup must remove plugin test data and temporary artifacts.
- Cleanup must not affect non-test databases.

## Performance Expectations
- Local test database setup + seed should complete fast enough for iterative development.
- Query performance should be sufficient for day/week/month/year view tests without timeouts under expected local data volumes.

## Security Requirements
- No real production data may be used in local tests.
- Sensitive values (passwords, hostnames) must be stored outside committed requirement docs and source.
- Example values in docs must be clearly dummy placeholders.

## Validation Requirements
Test workflow must validate:

- Successful schema creation from clean state
- Successful migration from older schema version(s)
- CRUD correctness
- Recurrence expansion correctness
- Correct behavior of uninstall keep/remove data options
- ICS field mapping readiness based on stored data

## Documentation Requirements
Project docs must describe:

- Local DB engine/version prerequisites
- Connection settings required for compatibility harness
- Commands for setup, seed, reset, and teardown
- Troubleshooting steps for common DB issues in local testing