Integration test: HLF website sync end-to-end flow
epic-peer-mentor-pause-management-automated-expiry-task-011 — Write integration tests for HLFWebsiteSyncService covering: mentor paused triggers removal from Dynamics portal listing; mentor expired_cert triggers removal; mentor reinstated with valid cert triggers restoration; retry logic fires on transient API errors; failure alerting fires after max retries; audit log entries are correct for all scenarios. Use a mocked Dynamics portal API for deterministic test control.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 6 - 158 tasks
Can start after Tier 5 completes
Implementation Notes
The key challenge in these tests is the async nature of the queue processor — triggering a status change and then asserting downstream effects requires polling or explicit invocation. Prefer direct Edge Function invocation in tests (call the queue processor HTTP endpoint explicitly after seeding the sync_queue row) over relying on pg_cron timing. This makes tests deterministic and fast. For backoff delay testing, inject a configurable delay multiplier via an Edge Function env var so tests use 10ms instead of 2000ms base delay.
For the concurrent isolation test, seed two pending sync operations, configure the mock to fail the first permanently (403) and succeed the second (200), invoke the queue processor with SKIP LOCKED semantics active, and assert both rows reach their expected final states independently. Reuse the TestCertificationSeeder helper from task-010 for any certification seeding needs.
Testing Requirements
Integration tests using flutter_test with a Supabase test client. Each test: seeds required mentor/certification data; triggers a status change via direct Supabase insert/update; waits for queue processor Edge Function to run (or invokes it directly in test); asserts database state (sync_queue status, audit log rows, dead_letter_queue rows); asserts mock HTTP server received expected requests with correct payloads. Use a configurable backoff delay multiplier (e.g., BACKOFF_MULTIPLIER_MS=10 in test mode) to reduce actual wait times for retry tests. A test helper class TestDynamicsMockServer wraps WireMock configuration for common scenarios (always-success, always-503, fail-twice-then-succeed).
Run in CI as part of the standard test pipeline.
The nightly expiry checker may run multiple times due to scheduler retries or infrastructure issues, causing duplicate auto-transitions and duplicate coordinator notifications that erode trust in the notification system.
Mitigation & Contingency
Mitigation: Implement idempotency via a unique constraint on (mentor_id, threshold_day, certification_expiry_date) in the cert_expiry_reminders table. Auto-transitions should be wrapped in a Postgres RPC that checks current status before applying, making repeated invocations safe.
Contingency: Add a compensation query in the reconciliation log that detects duplicate log entries for the same certification period and alerts the operations team for manual review within 24 hours.
The HLF Dynamics portal API may have eventual-consistency behaviour or rate limits that cause website listing updates to lag behind status changes, leaving expired mentors visible on the public website for an unacceptable window.
Mitigation & Contingency
Mitigation: Design the sync service to be triggered immediately on status transitions (event-driven via database webhook) in addition to the nightly batch run. Implement a reconciliation job that verifies sync state against app state and re-triggers any divergent records.
Contingency: If real-time sync cannot be guaranteed, implement a manual 'force sync' action in the coordinator dashboard so coordinators can trigger an immediate re-sync for urgent cases. Document the expected sync lag in coordinator onboarding materials.
Stakeholder requests to extend the expiry checker to handle additional certification types, grace periods, or organisation-specific threshold configurations may significantly increase scope beyond what is designed here, delaying delivery.
Mitigation & Contingency
Mitigation: Parameterise threshold day values (30, 14, 7) via configuration repository rather than hard-coding them, enabling per-organisation customisation without code changes. Document that grace period logic and additional cert types are out of scope for this epic and require a dedicated follow-up.
Contingency: Deliver the feature with hard-coded HLF-standard thresholds first and introduce the configuration repository as a follow-up task in the next sprint, using a feature flag to enable per-org threshold overrides.
Dynamics portal API credentials stored as environment secrets in Supabase Edge Function configuration may be rotated or invalidated by HLF IT without notice, causing silent sync failures that go undetected for multiple days.
Mitigation & Contingency
Mitigation: Implement credential health-check calls on each scheduler run and emit an immediate alert on auth failure rather than only alerting after N consecutive failures. Document the credential rotation procedure with HLF IT and establish a rotation notification protocol.
Contingency: Maintain a break-glass manual sync script accessible to HLF administrators that can re-execute the Dynamics sync with newly provided credentials while the automated system is restored.