docs(ios): enhance testing docs with Phase 2 readiness and tooling improvements
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.
This commit is contained in:
Matthew Raymer
@@ -2,11 +2,12 @@
|
||||
|
||||
**Purpose:** What the iOS test app must provide so that the testing guide can be executed with parity vs Android
|
||||
|
||||
**Plugin Target:** DailyNotificationPlugin v3.x (iOS)
|
||||
**Phase:** Phase 1 – Prefetch MVP
|
||||
**Version:** 1.0.1
|
||||
**Scope:** Phase 1 Prefetch MVP
|
||||
**Next Target:** Phase 2 (Rolling Window + TTL Telemetry)
|
||||
**Maintainer:** Matthew Raymer
|
||||
**Status:** 📋 **REQUIRED FOR PHASE 1**
|
||||
**Date:** 2025-11-15
|
||||
**Author:** Matthew Raymer
|
||||
**Directive Reference:** `doc/directives/0003-iOS-Android-Parity-Directive.md`
|
||||
|
||||
**Note:** This app exists to support the prefetch testing scenarios in `doc/test-app-ios/IOS_PREFETCH_TESTING.md`.
|
||||
@@ -15,7 +16,7 @@
|
||||
- **Android:** Exact alarms via AlarmManager / WorkManager
|
||||
- **iOS:** Heuristic BGTaskScheduler (see glossary); no hard guarantee of 5-min prefetch
|
||||
|
||||
**Glossary:** See glossary in `IOS_PREFETCH_TESTING.md` for terminology.
|
||||
**Glossary:** See `doc/test-app-ios/IOS_PREFETCH_GLOSSARY.md` for complete terminology definitions.
|
||||
|
||||
---
|
||||
|
||||
@@ -186,6 +187,39 @@ Use the build script:
|
||||
./scripts/build-ios-test-app.sh --device
|
||||
```
|
||||
|
||||
**Phase 2 Enhancement:** Refactor into modular subcommands:
|
||||
|
||||
```bash
|
||||
./scripts/build-ios-test-app.sh setup # pod install + sync
|
||||
./scripts/build-ios-test-app.sh run-sim # build + run simulator
|
||||
./scripts/build-ios-test-app.sh device # build + deploy device
|
||||
```
|
||||
|
||||
**Copy-Paste Commands:**
|
||||
|
||||
```bash
|
||||
# Setup (first time or after dependency changes)
|
||||
cd test-apps/ios-test-app
|
||||
pod install
|
||||
npx cap sync ios
|
||||
|
||||
# Build for simulator
|
||||
xcodebuild -workspace App.xcworkspace \
|
||||
-scheme ios-test-app \
|
||||
-configuration Debug \
|
||||
-sdk iphonesimulator \
|
||||
-destination 'platform=iOS Simulator,name=iPhone 15' \
|
||||
build
|
||||
|
||||
# Run on simulator
|
||||
xcodebuild -workspace App.xcworkspace \
|
||||
-scheme ios-test-app \
|
||||
-configuration Debug \
|
||||
-sdk iphonesimulator \
|
||||
-destination 'platform=iOS Simulator,name=iPhone 15' \
|
||||
test
|
||||
```
|
||||
|
||||
### Future CI Integration (Optional)
|
||||
|
||||
**Note for Phase 2+:** Consider adding `xcodebuild`-based CI job that:
|
||||
@@ -193,10 +227,16 @@ Use the build script:
|
||||
- Runs a minimal UI test that:
|
||||
- Launches app
|
||||
- Calls `configure()` and `getNotificationStatus()`
|
||||
- Validates log sequence + successful fetch simulation via LLDB trigger
|
||||
- This ensures test app remains buildable as plugin evolves
|
||||
|
||||
**Phase 1:** Manual testing only; CI integration is out of scope.
|
||||
|
||||
**CI Readiness (Phase 2):**
|
||||
- Add `xcodebuild` target for "Prefetch Integration Test"
|
||||
- Validate log sequence + successful fetch simulation via LLDB trigger
|
||||
- Use log validation script (`validate-ios-logs.sh`) for automated sequence checking
|
||||
|
||||
### Build Requirements
|
||||
|
||||
**Required Tools:**
|
||||
@@ -268,6 +308,26 @@ po await UNUserNotificationCenter.current().notificationSettings()
|
||||
e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.timesafari.dailynotification.fetch"]
|
||||
```
|
||||
|
||||
**Copy-Paste Commands:**
|
||||
|
||||
```swift
|
||||
// In Xcode LLDB console:
|
||||
// Check pending notifications
|
||||
po UNUserNotificationCenter.current().pendingNotificationRequests()
|
||||
|
||||
// Check permission status
|
||||
po await UNUserNotificationCenter.current().notificationSettings()
|
||||
|
||||
// Manually trigger BGTask (simulator only)
|
||||
e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.timesafari.dailynotification.fetch"]
|
||||
|
||||
// Force reschedule all tasks (test harness)
|
||||
po DailyNotificationBackgroundTaskTestHarness.forceRescheduleAll()
|
||||
|
||||
// Simulate time warp (test harness)
|
||||
po DailyNotificationBackgroundTaskTestHarness.simulateTimeWarp(minutesForward: 60)
|
||||
```
|
||||
|
||||
### Console.app Logging
|
||||
|
||||
1. Open Console.app (Applications → Utilities)
|
||||
@@ -280,6 +340,26 @@ e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWith
|
||||
- `DNP-SCHEDULER:` - Scheduling operations
|
||||
- `DNP-STORAGE:` - Storage operations
|
||||
|
||||
**Structured Logging (Swift Logger):**
|
||||
|
||||
The plugin uses Swift `Logger` categories for structured logging:
|
||||
- `com.timesafari.dailynotification.plugin` - Plugin operations
|
||||
- `com.timesafari.dailynotification.fetch` - Fetch operations
|
||||
- `com.timesafari.dailynotification.scheduler` - Scheduling operations
|
||||
- `com.timesafari.dailynotification.storage` - Storage operations
|
||||
|
||||
Filter in Console.app by subsystem: `com.timesafari.dailynotification`
|
||||
|
||||
**Phase 2: Log Validation Script**
|
||||
|
||||
Add helper script (`validate-ios-logs.sh`) to grep for required sequence markers:
|
||||
|
||||
```bash
|
||||
grep -E "\[DNP-(FETCH|SCHEDULER|PLUGIN)\]" device.log | ./scripts/validate-ios-logs.sh
|
||||
```
|
||||
|
||||
This confirms that all critical log steps occurred in proper order and flags missing or out-of-order events automatically.
|
||||
|
||||
### Common Debugging Scenarios
|
||||
|
||||
**Scenario: BGTask not running when expected → follow this checklist:**
|
||||
@@ -472,6 +552,15 @@ Since this test app is for internal testing, it can expose more tools:
|
||||
|
||||
### Dev-Only Toggles
|
||||
|
||||
| Button | Action | Purpose |
|
||||
|--------|--------|---------|
|
||||
| "Simulate BGTask Now" | Calls LLDB trigger | Quick sanity test |
|
||||
| "Schedule 1-min Notification" | Auto schedules T-Lead=1 | Edge case testing |
|
||||
| "Simulate DST Shift" | Adds +1 hr offset | DST handling check |
|
||||
| "Show Cached Payload" | Displays JSON cache | Prefetch validation |
|
||||
| "Force Reschedule All" | Calls `forceRescheduleAll()` | BGTask recovery testing |
|
||||
| "Time Warp +N Minutes" | Calls `simulateTimeWarp()` | Accelerated TTL/T-Lead tests |
|
||||
|
||||
1. **Force Schedule Notification N Minutes from Now**
|
||||
- Bypass normal scheduling UI
|
||||
- Directly call `scheduleDailyNotification()` with calculated time
|
||||
@@ -491,8 +580,28 @@ Since this test app is for internal testing, it can expose more tools:
|
||||
- Button to manually trigger BGTask (simulator only)
|
||||
- Wraps the LLDB command in UI for convenience
|
||||
|
||||
5. **UI Feedback Enhancements**
|
||||
- Add persistent toast/log area showing step-by-step plugin state ("Registered", "Scheduled", "BGTask fired", etc.)
|
||||
- Include color-coded state indicators for each stage (🟢 OK, 🟡 Pending, 🔴 Error)
|
||||
|
||||
These features can then be referenced from `IOS_PREFETCH_TESTING.md` as shortcuts for specific test scenarios.
|
||||
|
||||
### Persistent Schedule Snapshot
|
||||
|
||||
**Phase 2 Enhancement:** Store a simple JSON of the last prefetch state for post-run verification:
|
||||
|
||||
```json
|
||||
{
|
||||
"last_schedule": "2025-11-15T05:48:00Z",
|
||||
"last_prefetch": "2025-11-15T05:50:00Z",
|
||||
"last_notification": "2025-11-15T05:53:00Z",
|
||||
"prefetch_success": true,
|
||||
"cached_content_used": true
|
||||
}
|
||||
```
|
||||
|
||||
This can be used for post-run verification and telemetry aggregation. Access via test app UI button "Show Schedule Snapshot" or via UserDefaults key `DNP_ScheduleSnapshot`.
|
||||
|
||||
## Risks & Gotchas
|
||||
|
||||
**Common pitfalls when working with the test app:**
|
||||
@@ -543,6 +652,21 @@ These features can then be referenced from `IOS_PREFETCH_TESTING.md` as shortcut
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 Forward Plan
|
||||
|
||||
**Planned enhancements for Phase 2:**
|
||||
|
||||
- Add quick scenario buttons (Simulate BGTask Now, Schedule 1-min Notification, Simulate DST Shift, Show Cached Payload)
|
||||
- Implement persistent schedule snapshot (JSON of last prefetch state)
|
||||
- Add color-coded UI feedback (🟢 OK, 🟡 Pending, 🔴 Error)
|
||||
- Refactor build script into modular subcommands (`setup`, `run-sim`, `device`)
|
||||
- Integrate CI pipeline with `xcodebuild` target for "Prefetch Integration Test"
|
||||
- Add log validation script (`validate-ios-logs.sh`) for automated sequence checking
|
||||
|
||||
**See also:** `doc/directives/0003-iOS-Android-Parity-Directive.md` for Phase 2 implementation details.
|
||||
|
||||
---
|
||||
|
||||
## Changelog (high-level)
|
||||
|
||||
- 2025-11-15 — Initial Phase 1 version (prefetch MVP, Android parity)
|
||||
|
||||
Reference in New Issue
Block a user