Integration Testing for Export Pipeline End-to-End

epic-bufdir-report-export-core-backend-task-017 — Write integration tests covering the full export pipeline: seed test activity data for a multi-chapter org, call the edge function in preview mode and assert the canonical payload structure, then call in finalize mode for both CSV and PDF formats and assert file upload and history record creation. Test duplicate detection with seeded overlapping records. Test scope roll-up by verifying national scope includes activities from all child chapters. Test RLS enforcement by asserting cross-org data isolation.

high priority high complexity testing pending testing specialist Tier 9

Acceptance Criteria

Seed test: a multi-chapter org (minimum 3 child chapters) with at least 20 activity records spread across chapters and date ranges is correctly seeded and torn down within each test run

Preview mode: calling the edge function with mode=preview returns a canonical Bufdir JSON payload that matches the defined schema exactly, with no file upload to storage and no generated_reports record created

Finalize CSV mode: calling with mode=finalize&format=csv produces a valid CSV file uploaded to the bufdir-exports bucket at the correct path, a generated_reports record with status=completed, and a non-null storage_path

Finalize PDF mode: calling with mode=finalize&format=pdf produces a valid PDF file uploaded to storage, a generated_reports record with status=completed, and correct file_size_bytes populated

Duplicate detection: seeding overlapping activity records (same participant, date, activity_type) and running the export results in only one deduplicated entry in the payload, not multiple

Scope roll-up: requesting national-scope export aggregates activities from all child chapters and their sub-chapters, and the total count in the payload equals the sum of all chapter-level counts

RLS enforcement: an authenticated user from org_A calling the edge function with org_id=org_B receives a 403 or empty result and no data from org_B is present in the returned payload

Error recording: a simulated storage upload failure results in a generated_reports record with status=failed and a non-null error_message, with no partial file left in the bucket

All integration tests are idempotent and can be run repeatedly against a test Supabase environment without leaving residual data

Test suite completes within 5 minutes total to remain viable in CI pipelines

Technical Requirements

frameworks

flutter_test

Supabase Edge Functions (Deno runtime for edge function invocation)

Supabase client Dart SDK for data seeding and teardown

apis

Supabase Edge Functions invoke API (POST /functions/v1/bufdir-export)

Supabase Storage API for asserting file existence and deletion

Supabase PostgREST API for seeding and querying generated_reports and activities tables

data models

Activity records (multi-chapter seeded data)

generated_reports audit record

Canonical Bufdir JSON payload schema

Organisation and chapter hierarchy

performance requirements

Full integration test suite must complete within 5 minutes

Each individual test case must complete within 60 seconds including edge function cold start

Data seeding and teardown must not exceed 10 seconds per test

security requirements

Tests must use dedicated test Supabase project or isolated schema — never run against production

RLS test must use two separately authenticated JWT tokens representing different orgs

Test credentials must be loaded from environment variables, never hardcoded

All seeded test data must use clearly namespaced org IDs (e.g. test-org-*) to prevent collision

Execution Context

Execution Tier

Tier 9

Tier 9 - 22 tasks

Can start after Tier 8 completes

View Full Execution Plan

Implementation Notes

The most critical complexity here is the RLS test: you need two separate Supabase clients authenticated as users from different orgs. Use service-role key only for data seeding/teardown setup, never in the actual test assertions that validate access control. For scope roll-up, pre-calculate expected counts during seeding so assertions are deterministic. For duplicate detection, insert identical records with the same deduplication key (define what the key is in coordination with task-013) and assert the output count.

Structure test files as: `test/integration/bufdir_export_preview_test.dart`, `test/integration/bufdir_export_finalize_test.dart`, `test/integration/bufdir_export_rls_test.dart`, `test/integration/bufdir_export_scope_test.dart`. Add a `test/integration/README.md` explaining how to configure the test environment variables. Edge function cold starts on free-tier Supabase can take 3-5 seconds — add a warmup call in `setUpAll` and retry logic (max 3 retries, 2s backoff) for the first invocation of each test group.

Testing Requirements

Integration tests only — this task IS the testing task. Use flutter_test with a real Supabase test environment. Structure tests in groups: (1) Preview mode group, (2) CSV finalize group, (3) PDF finalize group, (4) Duplicate detection group, (5) Scope roll-up group, (6) RLS enforcement group, (7) Error path group. Each group must have a shared setUp that seeds required data and a tearDown that deletes all seeded records.

Assert on response HTTP status codes, JSON payload field presence and types, Supabase Storage object existence, and generated_reports table state. Do not use mocks for the edge function itself — invoke it over HTTP to test the real Deno runtime. Mock external PDF/CSV libraries only if they require filesystem access unavailable in test environment.

Component

Bufdir Export Edge Function

infrastructure high

Dependencies (2)

Implement the export history list Flutter widget that reads from the generated_reports repository and displays past exports in reverse chronological order. Each list item shows: export date, scope label, period, format badge (CSV/PDF), file size, and a re-download button. Wire the re-download button to call the edge function re-download endpoint and trigger the file download handler. Show empty state when no exports exist for the org scope. epic-bufdir-report-export-core-backend-task-016 Implement the finalize export path in the edge function that runs aggregation, serialization, then invokes either the CSV or PDF generation service based on the requested format. Upload the resulting binary to the Supabase export storage bucket under a deterministic path (org_id/year/period/filename). Record the export in the generated_reports repository with metadata (requested_by, scope, period, format, file_path, file_size, generated_at). Return a signed download URL valid for 24 hours. epic-bufdir-report-export-core-backend-task-013

Epic Risks (3)

high impact medium prob technical

Supabase Edge Functions have a default execution timeout. For large national-scope exports aggregating tens of thousands of activities across 1,400 chapters, the edge function may time out before completing, leaving coordinators with a failed export and no partial output.

Mitigation & Contingency

Mitigation: Optimise the aggregation SQL using pre-materialised aggregation views or RPC functions that run inside the database rather than iterating records in Deno. Profile query execution time against realistic production data volumes early. Request an elevated timeout limit from Supabase if needed. Implement progress checkpointing so the export can be resumed from the last completed aggregation batch.

Contingency: For organisations exceeding a configurable threshold (e.g. >5,000 activities), switch to an asynchronous export pattern: the edge function writes a 'pending' audit record and enqueues the job; the client polls for completion and is notified via Supabase Realtime when the file is ready.

medium impact medium prob technical

Server-side PDF generation in a Deno Edge Function environment restricts library choices. Many popular PDF libraries require Node.js APIs not available in Deno, or produce large bundle sizes that exceed edge function limits. Choosing the wrong library could block the entire PDF generation path.

Mitigation & Contingency

Mitigation: Spike PDF library selection as the first task of this epic, evaluating at least two Deno-compatible options (e.g. pdf-lib, jsPDF with Deno compatibility shim). Test bundle size and basic rendering before committing to an implementation. Document the chosen library's constraints.

Contingency: If no suitable Deno-native PDF library is found, generate a well-structured HTML report from the edge function and use a headless Chromium service (e.g. Browserless, Gotenberg) for HTML-to-PDF conversion, or temporarily ship CSV-only export while the PDF path is resolved.

high impact high prob technical

Peer mentors affiliated with multiple chapters (a documented NHF scenario) must not be double-counted in participant totals. Incorrect deduplication logic would overreport participation figures to Bufdir, which could be discovered during audit and damage organisational credibility.

Mitigation & Contingency

Mitigation: Define and document the deduplication contract explicitly before coding: deduplication is per-person per-period, not per-activity. Build dedicated unit tests with fixtures containing the exact multi-chapter membership patterns described in NHF's documentation. Have a NHF representative validate test fixture outputs against known-good manual counts.

Contingency: If deduplication logic produces results that cannot be verified against manual counts before launch, surface a deduplication warning in the export preview listing the affected peer mentor IDs, and require explicit coordinator acknowledgement before finalising the export.

Quick Links

All Tasks Execution Plan