End-to-end integration and smoke test suite
epic-external-system-integration-configuration-backend-infrastructure-task-016 — Write an end-to-end test suite covering the full integration pipeline: Edge Function receives a dispatch request, retrieves credentials from Vault, routes to a mock adapter, returns a structured result; Sync Scheduler reads cron config, creates a run log entry, invokes the Edge Function, and updates status to completed; Health Monitor runs checks against mock endpoints, stores results, and transitions status correctly. Include negative-path tests for auth failures and timeouts.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 5 - 253 tasks
Can start after Tier 4 completes
Handles integration between different epics or system components. Requires coordination across multiple development streams.
Implementation Notes
Start by setting up the mock adapter registry — a simple in-memory map from integration type key to a mock handler that returns configurable responses. Use Supabase's local CLI (`supabase start`) to spin up a local Postgres instance for run_log and health_check tables. For Vault mock, create a simple key-value store seeded with test credentials keyed by org_id + integration_type. Structure tests so each suite is independently runnable.
Pay special attention to the status machine in HealthMonitor — tests must cover every valid transition (unknown→healthy, healthy→degraded, degraded→failed) and invalid transitions must be asserted to be no-ops. For timeout simulation, use a configurable delay in the mock adapter and set the Edge Function's timeout threshold to a low value (e.g., 500ms) in the test config. Avoid sharing mutable state between test cases to prevent flakiness.
Testing Requirements
This task IS the testing task. Write integration tests using Deno's built-in test runner for Edge Functions and flutter_test for any Dart-side invocation layers. Structure tests in three suites: (1) EdgeFunctionSuite — dispatch, credential retrieval, adapter routing, and response shape; (2) SyncSchedulerSuite — cron config read, run_log lifecycle, Edge Function invocation, status update; (3) HealthMonitorSuite — endpoint check, result storage, status transition. Each suite must have at least one happy-path and two negative-path tests.
Use beforeEach/afterEach hooks to reset mock state and database rows. Target 100% coverage of all public Edge Function handler branches. Mock all external HTTP calls using a local mock server (e.g., Deno's built-in fetch mock or a lightweight HTTP mock library).
Supabase Edge Functions have cold start latency that can cause the first sync invocation after idle periods to fail or timeout when the external API has a short connection window, leading to missed scheduled syncs that go undetected.
Mitigation & Contingency
Mitigation: Configure Edge Function memory and implement a warm-up ping mechanism before heavy sync invocations. Set generous timeout values on the external API calls. Log all cold-start incidents for monitoring.
Contingency: If cold starts cause consistent sync failures, migrate the sync scheduler to a persistent Supabase cron job that pre-warms the function 30 seconds before the scheduled sync time.
The sync scheduler must execute jobs at predictable times for financial reporting accuracy. Drift in cron execution timing (due to Supabase infrastructure delays) could cause syncs to run at wrong times, leading to missing data in accounting exports or duplicate exports across reporting periods.
Mitigation & Contingency
Mitigation: Implement idempotency keys based on integration ID + scheduled period, so re-runs of a delayed sync cannot create duplicate exports. Log actual execution timestamps vs scheduled timestamps and alert on drift exceeding 5 minutes.
Contingency: If scheduler reliability is insufficient, integrate with a dedicated cron service (e.g., pg_cron on Supabase) for millisecond-precise scheduling, replacing the application-level scheduler.
Aggressive health monitoring ping frequency could trigger rate limiting on external APIs (especially Xledger and Dynamics), causing legitimate export calls to fail after the monitor exhausts the API's request quota.
Mitigation & Contingency
Mitigation: Use lightweight health check endpoints (HEAD requests or vendor-specific ping/status endpoints) rather than data requests. Set health check frequency to once per 15 minutes minimum. Implement exponential backoff after consecutive failures.
Contingency: If rate limiting occurs, disable active health monitoring for the affected integration type and switch to passive health detection (mark unhealthy only when a scheduled sync fails).