docs(ios): add comprehensive testing guide and refine iOS parity directive
Add iOS prefetch testing guide with detailed procedures, log checklists, and behavior classification. Enhance iOS test app requirements with security constraints, sign-off checklists, and changelog structure. Update main directive with testing strategy and method behavior mapping. Changes: - Add IOS_PREFETCH_TESTING.md with simulator/device test plans, log diagnostics, telemetry expectations, and test run templates - Add DailyNotificationBackgroundTaskTestHarness.swift as reference implementation for BGTaskScheduler testing - Enhance IOS_TEST_APP_REQUIREMENTS.md with security/privacy constraints, review checklists, CI hints, and glossary cross-links - Update 0003-iOS-Android-Parity-Directive.md with testing strategy section, method behavior classification, and validation matrix updates All documents now include changelog stubs, cross-references, and completion criteria for Phase 1 implementation and testing.
This commit is contained in:
Matthew Raymer
@@ -792,6 +792,46 @@ A "successful run" is defined as: BGTask handler invoked, content fetch complete
|
||||
|
||||
## Validation & QA Plan
|
||||
|
||||
### Testing Strategy
|
||||
|
||||
**Comprehensive testing guide:** See `doc/test-app-ios/IOS_PREFETCH_TESTING.md` for detailed testing procedures, log checklists, and behavior classification.
|
||||
|
||||
**Key Testing Principles:**
|
||||
- **Simulator:** Test logic correctness (deterministic behavior)
|
||||
- **Real Device:** Test timing and reliability (heuristic behavior)
|
||||
- **Log-Driven:** Use structured logging to trace full execution paths
|
||||
- **Failure Modes:** Test negative paths (network failures, permission denials)
|
||||
|
||||
**Behavior Classification:**
|
||||
- **🟢 Deterministic:** Code logic, error handling, data processing (test in simulator)
|
||||
- **🟡 Partially Deterministic:** Scheduling logic works, but timing is heuristic (test flow in simulator, timing on device)
|
||||
- **🔴 Heuristic:** Background execution timing, notification delivery timing (test on real device only)
|
||||
|
||||
### Method Behavior Classification
|
||||
|
||||
**🟢 Deterministic Methods (Test in Simulator):**
|
||||
- `configure()` - Configuration logic
|
||||
- `getLastNotification()` - Data retrieval
|
||||
- `cancelAllNotifications()` - Cancellation logic
|
||||
- `getNotificationStatus()` - Status calculation
|
||||
- `updateSettings()` - Settings update logic
|
||||
- `getBatteryStatus()` - Battery state reading
|
||||
- `getPowerState()` - Power state reading
|
||||
- `getRollingWindowStats()` - Statistics calculation
|
||||
- `testJWTGeneration()` - JWT generation logic
|
||||
- `testEndorserAPI()` - API call logic
|
||||
|
||||
**🟡 Partially Deterministic Methods (Test Flow in Simulator, Timing on Device):**
|
||||
- `scheduleDailyNotification()` - Scheduling logic is deterministic, but iOS delivery timing is heuristic
|
||||
- `maintainRollingWindow()` - Logic is deterministic, but when iOS allows execution is heuristic
|
||||
|
||||
**🔴 Heuristic Methods (Test on Real Device Only):**
|
||||
- Background task execution timing (BGTaskScheduler) - iOS controls when tasks run
|
||||
- Notification delivery timing (UNUserNotificationCenter) - iOS controls delivery timing
|
||||
- Reboot recovery detection (uptime comparison) - May vary based on system state
|
||||
|
||||
**See `doc/test-app-ios/IOS_PREFETCH_TESTING.md` for detailed testing procedures for each behavior class.**
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- [ ] Test all new methods match Android behavior
|
||||
@@ -811,12 +851,13 @@ A "successful run" is defined as: BGTask handler invoked, content fetch complete
|
||||
|
||||
### Manual Testing
|
||||
|
||||
- [ ] Test on iOS Simulator (primary)
|
||||
- [ ] Test on physical iOS devices (validation)
|
||||
- [ ] Test on iOS Simulator (primary) - Logic correctness
|
||||
- [ ] Test on physical iOS devices (validation) - Timing and reliability
|
||||
- [ ] Test Background App Refresh settings
|
||||
- [ ] Test notification permissions
|
||||
- [ ] Test battery optimization scenarios
|
||||
- [ ] Test app lifecycle events
|
||||
- [ ] Test prefetch execution (see `doc/test-app-ios/IOS_PREFETCH_TESTING.md`)
|
||||
|
||||
---
|
||||
|
||||
@@ -1049,6 +1090,7 @@ scripts/
|
||||
- `ios/Plugin/DailyNotificationDatabase.swift` - Database (CoreData)
|
||||
- `ios/Plugin/DailyNotificationRollingWindow.swift` - Rolling window
|
||||
- `ios/Plugin/DailyNotificationTTLEnforcer.swift` - TTL enforcement
|
||||
- `ios/Plugin/DailyNotificationBackgroundTaskTestHarness.swift` - BGTaskScheduler test harness (reference implementation)
|
||||
- `ios/Plugin/DailyNotificationETagManager.swift` - ETag management
|
||||
- `ios/Plugin/DailyNotificationBackgroundTaskManager.swift` - Background tasks
|
||||
|
||||
@@ -1061,6 +1103,7 @@ scripts/
|
||||
- `doc/implementation-roadmap.md` - Implementation roadmap
|
||||
- `doc/INTEGRATION_CHECKLIST.md` - Integration checklist
|
||||
- `doc/test-app-ios/IOS_TEST_APP_REQUIREMENTS.md` - iOS test app detailed requirements (must be created in Phase 1)
|
||||
- `doc/test-app-ios/IOS_PREFETCH_TESTING.md` - Comprehensive iOS prefetch testing guide (testing procedures, log checklists, behavior classification)
|
||||
- `README.md` - Project documentation
|
||||
|
||||
---
|
||||
@@ -1447,6 +1490,7 @@ scripts/
|
||||
|---------|-----------------|----------------|-------------|-------|
|
||||
| Daily notification | Exact ±0s | ±180s tolerance¹ | Test case: verify **observed** delivery within 3 min window | 1 |
|
||||
| Daily prefetch | Worker at exact time | BGTask within 15 min window | Logs + UI: check fetch timestamp | 1 |
|
||||
| Prefetch execution | Deterministic logic | Heuristic timing (device-only) | Simulator: logic correctness; Device: timing verification (see `IOS_PREFETCH_TESTING.md`) | 1 |
|
||||
| Rolling window | 2 days ahead | iOS 64 limit enforced | Stats call: verify pending count ≤ 64 | 2 |
|
||||
| TTL enforcement | Discard stale at fire | Same: discard stale at fire | Deliver-time check: verify TTL validation | 2 |
|
||||
| Reboot recovery | BOOT_COMPLETED | Uptime comparison | App launch: verify reschedule after reboot | 2 |
|
||||
@@ -1513,12 +1557,20 @@ scripts/
|
||||
- Verify task registered in AppDelegate before app finishes launching
|
||||
- **Simulator-only debugging trick:** Use LLDB command to manually trigger: `e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.timesafari.dailynotification.fetch"]`
|
||||
- Note: This is for simulator testing only, not available in production
|
||||
- **Testing Guide:** See `doc/test-app-ios/IOS_PREFETCH_TESTING.md` for comprehensive testing procedures
|
||||
|
||||
2. **Notifications Not Delivering:**
|
||||
- Check notification permissions: `UNUserNotificationCenter.current().getNotificationSettings()`
|
||||
- Verify notification scheduled: `UNUserNotificationCenter.current().getPendingNotificationRequests()`
|
||||
- Check notification category registered
|
||||
|
||||
3. **Prefetch Not Executing:**
|
||||
- Verify BGTask scheduled: Check logs for `[DNP-FETCH] BGAppRefreshTask scheduled`
|
||||
- Check Background App Refresh enabled in Settings
|
||||
- In Simulator: Use Xcode → Debug → Simulate Background Fetch
|
||||
- On Device: Check logs via Xcode Devices console
|
||||
- **Testing Guide:** See `doc/test-app-ios/IOS_PREFETCH_TESTING.md` for detailed troubleshooting
|
||||
|
||||
3. **Build Failures:**
|
||||
- Ensure CocoaPods installed: `pod install`
|
||||
- Check Capacitor plugin path in `capacitor.plugins.json`
|
||||
|
||||
Reference in New Issue
Block a user