calendar-plugin/requirements/local-database.md

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