🏠 Overview › ✅ Implementation Tasks ›✅ epic-annual-impact-summary-foundation-task-011

Write unit tests for SummaryOfflineCache

epic-annual-impact-summary-foundation-task-011 — Write Flutter unit tests covering the SummaryOfflineCache: put and get round-trip serialisation, cache miss returns null, delete removes entry, clear empties the box, and isCached returns correct boolean. Use a temporary in-memory Hive test environment. Target 100% coverage of the public API surface.

high priority low complexity testing pending testing specialist Tier 4

Acceptance Criteria

put(key, annualSummary) followed by get(key) returns an AnnualSummary object that is deeply equal to the original (all fields match, including nested lists and enums)
get(key) returns null when no entry exists for that key (cache miss), without throwing any exception
delete(key) removes the entry; a subsequent get(key) returns null
clear() empties the box; get() on any previously cached key returns null after clear()
isCached(key) returns true immediately after a put() and false after a delete() or on a key that was never inserted
put() with an existing key overwrites the previous value; get() returns the new value
All tests run in an isolated in-memory Hive environment (Hive.init with a temp directory or hive_test package) with no shared state between test cases
Tests complete in under 500 ms total (no network I/O, pure in-memory)
Test file achieves 100% line and branch coverage of the SummaryOfflineCache public API as reported by `flutter test --coverage`
No production Hive box files are created or left on disk after the test suite runs (tearDown closes and deletes the test box)

Technical Requirements

frameworks
flutter_test
hive / hive_flutter (in-memory test mode)
hive_test or manual temp directory setup for isolation
apis
Hive.init(tempDir.path) or hive_test setupHive()
Hive.openBox<T>(boxName)
SummaryOfflineCache.put(key, value)
SummaryOfflineCache.get(key)
SummaryOfflineCache.delete(key)
SummaryOfflineCache.clear()
SummaryOfflineCache.isCached(key)
data models
annual_summary
performance requirements
All unit tests complete in under 500 ms with no file I/O to external storage
security requirements
Test data must not include real user UUIDs or PII; use fixture UUIDs such as '00000000-0000-0000-0000-000000000001'

Execution Context

Execution Tier
Tier 4

Tier 4 - 323 tasks

Can start after Tier 3 completes

Implementation Notes

Use the `hive_test` package (or manually call `Hive.init((await Directory.systemTemp.createTemp()).path)`) in setUpAll, and `Hive.close()` in tearDownAll. Register any required TypeAdapters for AnnualSummary in setUp before opening the box. Construct AnnualSummary fixtures using a factory constructor or builder to keep test setup concise. Use `expect(result, equals(expected))` with a custom matcher or `equatable` if AnnualSummary implements Equatable, or compare field by field.

Test the overwrite scenario explicitly: put key with value A, put same key with value B, get should return B. For isCached, test all three states: never inserted, after put, after delete. Keep each test method under 20 lines for readability.

Testing Requirements

Pure unit tests using flutter_test. No widget or integration test infrastructure needed. Use setUp/tearDown to initialise and close the Hive box for each test case, ensuring no shared state. Create a minimal AnnualSummary fixture with all required fields populated to test round-trip serialisation fidelity.

Group tests using flutter_test group() blocks: 'put and get', 'cache miss', 'delete', 'clear', 'isCached'. Run with `flutter test --coverage` and verify 100% coverage report for the SummaryOfflineCache class file.

Component
Summary Offline Cache
data low
Dependencies (1)
Build the SummaryOfflineCache class exposing put(summary), get(mentorId, year), getAll(mentorId), delete(mentorId, year), and clear() methods over the Hive box. Include cache-hit/miss logging, error handling for corrupted entries, and an isCached(mentorId, year) convenience method. This component is the sole abstraction over local persistence for summaries. epic-annual-impact-summary-foundation-task-004
Epic Risks (3)
medium impact medium prob dependency

Rive animation files may not be available at implementation time, blocking the wrapped-animation-controller from being fully tested. If asset delivery is delayed, the controller cannot be validated for memory-leak-free disposal.

Mitigation & Contingency

Mitigation: Implement the animation controller with stub/placeholder AnimationController instances first so the lifecycle and disposal logic can be unit-tested independently of Rive assets. Define a named animation registry interface early so UI components can reference animations by name without coupling to specific Rive files.

Contingency: If Rive assets are not delivered before Epic 3 begins, replace Rive animations with Flutter implicit animations (AnimatedOpacity, ScaleTransition) as a drop-in and schedule Rive integration as a follow-on task once assets arrive.

high impact medium prob technical

The annual_summaries Supabase RPC aggregating 12 months of activity records per mentor may exceed acceptable query latency (>2s) for mentors with high activity volumes such as the HLF mentor with 380 registrations cited in workshop notes.

Mitigation & Contingency

Mitigation: Design the RPC to materialise summary results into the annual_summaries table via a scheduled edge function rather than computing on demand. The repository reads pre-computed rows, keeping query latency constant regardless of activity volume.

Contingency: If on-demand queries are required for real-time period switching, add a PostgreSQL partial index on (mentor_id, activity_date) and implement a client-side loading skeleton so slow queries degrade gracefully rather than blocking the UI.

medium impact low prob technical

iOS requires photo library permission before saving a screenshot to the gallery. If the permission prompt is triggered at an unexpected point in the share flow, the UX breaks and users may deny permission permanently, making gallery save unavailable.

Mitigation & Contingency

Mitigation: Trigger the permission request only when the user explicitly chooses 'Save to gallery' in the share overlay, not on screen load. Implement a pre-prompt explanation screen following Apple HIG so users understand why the permission is needed before the system dialog appears.

Contingency: If permission is denied, gracefully fall back to clipboard copy and system share sheet options which do not require photo library access, and surface a non-blocking snackbar explaining the limitation.

Quick Links
All Tasks Execution Plan