f6875beae5
Add unified versioning headers, shared glossary, and Phase 2 forward plans to iOS testing documentation. Enhance test harness with time warp simulation, force reschedule, and structured logging. Expand negative-path test scenarios and add telemetry JSON schema for Phase 2 integration. Changes: - Create IOS_PREFETCH_GLOSSARY.md for consolidated terminology - Add unified versioning (v1.0.1) and cross-links between testing docs - Enhance test harness with simulateTimeWarp() and forceRescheduleAll() - Add Swift Logger categories (plugin, fetch, scheduler, storage) - Expand negative-path tests (storage unavailable, JWT expiration, timezone drift) - Add telemetry JSON schema placeholder for Phase 2 Prometheus integration - Add Phase 2 Forward Plan sections to both documents - Add copy-paste command examples throughout (LLDB, Swift, bash) - Document persistent schedule snapshot and log validation script (Phase 2) All improvements maintain Phase 1 focus while preparing for Phase 2 telemetry integration and CI automation.
3.1 KiB
iOS Prefetch Glossary
Purpose: Shared terminology definitions for iOS prefetch testing and implementation
Last Updated: 2025-11-15
Status: 🎯 ACTIVE - Reference glossary for iOS prefetch documentation
Core Terms
BGTaskScheduler – iOS framework for scheduling background tasks (BGAppRefreshTask / BGProcessingTask). Provides heuristic-based background execution, not exact timing guarantees.
BGAppRefreshTask – Specific BGTaskScheduler task type for background app refresh. Used for prefetch operations that need to run periodically.
UNUserNotificationCenter – iOS notification framework for scheduling and delivering user notifications. Handles permission requests and notification delivery.
T-Lead – The lead time between prefetch and notification fire, e.g., 5 minutes. Prefetch is scheduled at notificationTime - T-Lead.
earliestBeginDate – The earliest time iOS may execute a BGTask. This is a hint, not a guarantee; iOS may run the task later based on heuristics.
UTC – Coordinated Universal Time. All internal timestamps are stored in UTC to avoid DST and timezone issues.
Behavior Classification
Bucket A/B/C – Deterministic vs heuristic classification used in Behavior Classification:
- Bucket A (Deterministic): Test in Simulator and Device - Logic correctness
- Bucket B (Partially Deterministic): Test flow in Simulator, timing on Device
- Bucket C (Heuristic): Test on Real Device only - Timing and reliability
Deterministic – Behavior that produces the same results given the same inputs, regardless of when or where it runs. Can be fully tested in simulator.
Heuristic – Behavior controlled by iOS system heuristics (user patterns, battery, network, etc.). Timing is not guaranteed and must be tested on real devices.
Testing Terms
Happy Path – The expected successful execution flow: Schedule → BGTask → Fetch → Cache → Notification Delivery.
Negative Path – Failure scenarios that test error handling: Network failures, permission denials, expired tokens, etc.
Telemetry – Structured metrics and counters emitted by the plugin for observability (e.g., dnp_prefetch_scheduled_total).
Log Sequence – The ordered sequence of log messages that indicate successful execution of a prefetch cycle.
Platform Terms
Simulator – iOS Simulator for testing logic correctness. BGTask execution can be manually triggered.
Real Device – Physical iOS device for testing timing and reliability. BGTask execution is controlled by iOS heuristics.
Background App Refresh – iOS system setting that controls whether apps can perform background tasks. Must be enabled for BGTask execution.
Low Power Mode – iOS system mode that may delay or disable background tasks to conserve battery.
References
- Testing Guide:
doc/test-app-ios/IOS_PREFETCH_TESTING.md - Test App Requirements:
doc/test-app-ios/IOS_TEST_APP_REQUIREMENTS.md - Main Directive:
doc/directives/0003-iOS-Android-Parity-Directive.md
Status: 🎯 READY FOR USE
Maintainer: Matthew Raymer