Integration test orchestrator happy path and failure modes
epic-bufdir-reporting-export-core-logic-task-013 — Write integration tests for BufdirExportOrchestratorService using fakes for all sub-services. Test cases: successful end-to-end export returning a valid download artifact, activity query failure triggering fatal abort with audit record marked failed, column mapper validation errors producing PartialFailureReport, and file storage failure rolling back to failed audit status. Confirm audit record reaches a terminal status in all scenarios.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 5 - 253 tasks
Can start after Tier 4 completes
Implementation Notes
Structure fakes as simple Dart classes implementing the service interface rather than using code-generated mocks — this avoids build_runner overhead in CI. Define a shared TestFixtures class with static factory methods for valid and invalid input data to keep test bodies readable. The orchestrator likely uses async/await chains; wrap orchestrator calls in expectLater or await and then assert sequentially. For the rollback scenario, verify the audit repository fake received exactly two calls: one INSERT (initiated) and one UPDATE (failed) — recording call order is important.
Use addTearDown inside each test to reset fake call logs. Follow the Arrange–Act–Assert pattern strictly; avoid logic inside the assert phase. If the orchestrator accepts a dependency-injected clock, inject a fixed DateTime in tests to make created_at assertions deterministic.
Testing Requirements
Integration tests only — no unit tests for individual service methods in this task. Use flutter_test with a group() block per scenario (happy_path, activity_failure, mapper_validation_failure, storage_failure). Each group contains setUp() that constructs fresh fakes and a tearDown() asserting no unexpected interactions. Assert both the returned value type and the audit record final state for every scenario.
Do not use real Supabase connections; all I/O is intercepted by fakes. Coverage target: 100% of orchestrator public method branches exercised across the four groups.
Bufdir's column schema may have per-field business rules (conditional required fields, cross-field validation, organisation-specific category taxonomies) that cannot be expressed in a simple key-value mapping configuration. If the configuration model is too simple, supporting NHF's specific requirements will require hardcoded organisation logic, undermining the configuration-driven design.
Mitigation & Contingency
Mitigation: Design the column configuration schema as a full JSON document supporting field-level transformation rules, conditional expressions, and org-specific value enumerations. Validate the design against a real NHF Bufdir Excel template before implementation begins.
Contingency: If the configuration model cannot express all required rules, implement a thin transformation plugin interface where org-specific logic can be added as a named Dart class registered against the organisation ID, with the JSON config covering only the common cases.
For large organisations like NHF with potentially tens of thousands of activity records, the full export pipeline (query + map + generate + bundle + upload) may exceed Supabase Edge Function execution time limits (typically 150s), causing silent timeouts that leave audit records in a pending state indefinitely.
Mitigation & Contingency
Mitigation: Implement the orchestrator as a background Dart isolate with progress streaming rather than a synchronous Edge Function call. Use chunked processing for the query and mapping phases to reduce peak memory usage. Profile against realistic NHF data volumes in a staging environment.
Contingency: If processing time cannot be reduced below the timeout threshold, implement an asynchronous job model where the export is queued, processed in the background, and the user is notified via push notification when the download is ready — treating it as an eventual rather than synchronous operation.