# API Test Cases

## Purpose
Define detailed API tests if an HTTP API is exposed for calendar/admin/caldav-support operations.

If no API is exposed beyond CalDAV and ICS endpoints, this file remains as the contract for future API introduction and should be marked `not-applicable` in CI.

## Assumed Endpoint Groups
- Admin calendar entries API (example: `/api/calendar/events`)
- Admin users/access API (example: `/api/calendar/users`)
- ICS endpoint (example: `/calendar.ics` or `/api/calendar/ics`)
- CalDAV endpoint (separately tested in E2E/CalDAV suites)

Adjust paths to actual implementation while preserving case coverage.

## Common Assertions
- AuthN/AuthZ enforced for each endpoint.
- Validation errors return structured error payloads.
- Deterministic timezone behavior (`Europe/London` default).
- No sensitive internals leaked in responses.

## Event API Tests

### API-EVT-001 Create Valid Event
- Fixture: CE-001
- Method: `POST /api/calendar/events`
- Assertions:
  - `201` created.
  - Response includes stable id and canonicalized fields.
  - Event visible in admin UI and public UI after create.

### API-EVT-002 Create Invalid Event
- Payload: missing `title` or end before start
- Assertions:
  - `400`/`422` validation failure.
  - Actionable field-level errors returned.
  - No partial data persisted.

### API-EVT-002b Unauthorized Event Write
- Method: `POST /wp-json/calendar/v1/events` without plugin or WordPress write auth
- Assertions:
  - Request is denied (`403`).
  - No event record is persisted.

### API-EVT-003 Read/List with Filters
- Fixtures: CE-002..CE-007
- Method: `GET /api/calendar/events?from=...&to=...&view=month`
- Assertions:
  - Date-window filtering includes expected occurrences.
  - Pagination/sorting (if present) stable and documented.

### API-EVT-004 Update with Concurrency
- Fixture: CE-001
- Method: `PUT/PATCH /api/calendar/events/{id}`
- Assertions:
  - Valid update returns success and modified timestamp/version.
  - Stale ETag/version returns precondition/conflict.
  - No silent overwrite on concurrent edits.

### API-EVT-005 Delete Single Event
- Fixture: CE-001
- Method: `DELETE /api/calendar/events/{id}`
- Assertions:
  - Delete succeeds with expected status.
  - Event absent from list, UI, and ICS.

### API-EVT-006 Delete One Recurrence Occurrence
- Fixture: CE-010
- Method: `DELETE /api/calendar/events/{id}/occurrences/{occurrence_key}` (or equivalent)
- Assertions:
  - Operation creates exception record.
  - Remaining series unchanged.
  - No split-series records created.

### API-EVT-007 Preview Occurrences (Valid + Invalid)
- Method: `POST /wp-json/calendar/v1/events/preview-occurrences`
- Assertions:
  - Valid recurrence payload returns computed preview items in requested window.
  - Invalid range (`end < start`) returns `422`.
  - Preview endpoint is non-destructive (does not create records).

### API-EVT-008 Monthly Ordinal Recurrence Parity
- Method: `POST /wp-json/calendar/v1/events` + `GET /events/{id}/occurrences`
- Assertions:
  - `repeat_nth_mode=weekday_of_month` with `repeat_nth_pos=-1` and weekday set maps to expected monthly dates.
  - Saved ordinal recurrence reloads without drift.
  - Series stays single UID-based sequence.

## User/Access API Tests

### API-USR-001 Register User
- Method: `POST /api/calendar/users/register`
- Assertions:
  - Account created as `pending_approval`.
  - Verification email dispatch recorded.

### API-USR-002 Verify Email
- Method: tokenized verification endpoint
- Assertions:
  - Valid token marks email verified while user remains `pending_approval`.
  - Reused/expired token fails cleanly.

### API-USR-003 Password Recovery
- Methods: forgot + reset endpoints
- Assertions:
  - Token issued and reset succeeds once.
  - Previous sessions/tokens invalidated.

### API-USR-004 Admin Approve/Remove
- Method: admin-only action endpoint
- Assertions:
  - Admin can set `pending_approval`/`active`.
  - Admin can remove defunct users.
  - Unauthorized user receives denial.
  - Audit log record created.

### API-USR-005 Remove User Revokes Access
- Method: admin `DELETE /wp-json/calendar/v1/admin/users/{id}` then user login/me checks
- Assertions:
  - Removed user can no longer authenticate (`401`).
  - Removed user sessions/tokens do not continue to authorize requests.

## ICS Endpoint API Tests

### API-ICS-001 Basic Response
- Method: `GET /calendar.ics`
- Assertions:
  - `200` status, `text/calendar` content type, UTF-8.
  - Valid VCALENDAR envelope.

### API-ICS-002 Recurrence + Exception Mapping
- Fixture: CE-010 with deleted occurrence exception
- Assertions:
  - RRULE is present for series.
  - Exception for deleted occurrence is exported.
  - No split-series artifact in output.

### API-ICS-003 Slugged Path Link Contract
- Method: set `url_slug`, render shortcode, inspect rendered links
- Assertions:
  - ICS link uses `/<url_slug>/calendar.ics`.
  - CalDAV link uses `/<url_slug>/caldav/`.
  - Link path changes match configured slug value.

## CalDAV Sync Compatibility Tests

### API-CALDAV-001 Collection URL Variant Compatibility
- Method: `REPORT sync-collection` against both:
  - `.../caldav/calendars/public/`
  - `.../caldav/calendars/public`
- Assertions:
  - Both return `207`.
  - Neither returns method errors due to trailing slash variant.

### API-CALDAV-002 Collection Availability Probe
- Method: `GET .../caldav/calendars/public/` (authenticated)
- Assertions:
  - Returns `200` (body may be empty).
  - Does not force client into temporary unavailable state on probe.

### API-CALDAV-003 No-Change Incremental Sync Stability
- Method:
  1. run `REPORT sync-collection` to obtain sync token
  2. rerun `REPORT sync-collection` with returned token and no intervening changes
- Assertions:
  - Returns `207`
  - Contains zero `<D:response>` change entries
  - Does not emit historical `404` tombstone floods for unchanged state

## Negative and Security Tests

### API-SEC-001 Unauthorized Access
- Assertions:
  - Unauthenticated requests blocked where required.
  - No data leakage in error responses.

### API-SEC-002 Input Fuzz/Injection
- Assertions:
  - Script/SQL-like payloads are rejected or safely encoded.
  - No server error or malformed persistence.

### API-SEC-003 Rate Limit Behavior
- Assertions:
  - Login/reset/verification endpoints throttle abusive attempts.

### API-SET-001 Table Prefix Setting
- Method: `GET/PATCH /wp-json/calendar/v1/settings` (admin context)
- Assertions:
  - `table_prefix` is visible in setup/admin workflow and defaults to `wp_cs_calendar`.
  - Changing table prefix to another valid value triggers table rename migration.
  - Existing data remains accessible after prefix change.

## Execution Cadence
- Run full API suite on PR and nightly builds.
- Run a trimmed API smoke subset on each commit (see `tests/smoke_tests.md`).