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,13 +2,17 @@
|
||||
|
||||
**Purpose:** How to test background prefetch for DailyNotificationPlugin on iOS (simulator + device)
|
||||
|
||||
**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
|
||||
**Last Updated:** 2025-11-15
|
||||
**Status:** 🎯 **ACTIVE** - Testing guide for Phase 1+ implementation
|
||||
|
||||
**Note:** This guide assumes the iOS test app is implemented as described in `doc/test-app-ios/IOS_TEST_APP_REQUIREMENTS.md`.
|
||||
|
||||
**Glossary:** See `doc/test-app-ios/IOS_PREFETCH_GLOSSARY.md` for terminology definitions.
|
||||
|
||||
**Android parity:** Behavior is aligned with `test-apps/android-test-app` where platform constraints allow. Timing and BGTask heuristics **will differ** from Android's exact alarms:
|
||||
- **Android:** Exact alarms via AlarmManager / WorkManager
|
||||
- **iOS:** Heuristic BGTaskScheduler; no hard guarantee of 5-min prefetch
|
||||
@@ -167,6 +171,8 @@ JS/HTML Test App → Capacitor Bridge → DailyNotificationPlugin (iOS)
|
||||
|
||||
**Objective:** Confirm that when a background task fires, your prefetch code runs end-to-end.
|
||||
|
||||
**Cross-Reference:** Corresponds to `IOS_TEST_APP_REQUIREMENTS.md – Testing Scenarios → Basic Functionality [SIM+DEV]`
|
||||
|
||||
### 1. Harden Logging (One-Time Prep)
|
||||
|
||||
Add structured logs at key points:
|
||||
@@ -237,6 +243,15 @@ With app running:
|
||||
|
||||
**See Sample Prefetch Response & Mapping below for expected API response structure.**
|
||||
|
||||
**Copy-Paste Commands:**
|
||||
|
||||
```bash
|
||||
# In Xcode LLDB console (simulator only):
|
||||
e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.timesafari.dailynotification.fetch"]
|
||||
|
||||
# Or use test app UI button: "Simulate BGTask Now"
|
||||
```
|
||||
|
||||
### 5. Trigger or Wait for Notification
|
||||
|
||||
**Option A: Wait for scheduled time**
|
||||
@@ -277,6 +292,21 @@ When prefetch succeeds, the API returns JSON like:
|
||||
|
||||
When you see `[DNP-FETCH] Fetch success (status=200, bytes=1234, ttl=86400)`, the `ttl=86400` should match the `ttl` field in the JSON response. The `scheduled_for` timestamp should match the `notificationTime` used in scheduling.
|
||||
|
||||
**Copy-Paste Commands:**
|
||||
|
||||
```swift
|
||||
// In test app or test harness:
|
||||
// View cached payload
|
||||
let cachedContent = UserDefaults.standard.data(forKey: "DNP_CachedContent_\(scheduleId)")
|
||||
let json = try? JSONSerialization.jsonObject(with: cachedContent ?? Data())
|
||||
|
||||
// Simulate time warp (testing only)
|
||||
DailyNotificationBackgroundTaskTestHarness.simulateTimeWarp(minutesForward: 60)
|
||||
|
||||
// Force reschedule all tasks
|
||||
DailyNotificationBackgroundTaskTestHarness.forceRescheduleAll()
|
||||
```
|
||||
|
||||
### 7. Negative-Path Tests
|
||||
|
||||
**Network failure:**
|
||||
@@ -334,6 +364,8 @@ When you see `[DNP-FETCH] Fetch success (status=200, bytes=1234, ttl=86400)`, th
|
||||
|
||||
**Objective:** Confirm that **prefetch happens near the intended time** (e.g., 5 minutes before) in realistic conditions.
|
||||
|
||||
**Cross-Reference:** Corresponds to `IOS_TEST_APP_REQUIREMENTS.md – Testing Scenarios → Background Tasks [DEV-ONLY]`
|
||||
|
||||
### 1. Install Dev Build on iPhone
|
||||
|
||||
- Same BGTask + background modes config as simulator
|
||||
@@ -605,6 +637,38 @@ Define counters you expect the runtime to emit:
|
||||
|
||||
These counters MUST be emitted via the same pipeline as Android (e.g., structlog → rsyslog → Prometheus/Influx/Loki). If telemetry is not yet wired on iOS, mark tests that rely on counters as **P2** and fall back to log inspection for Phase 1.
|
||||
|
||||
**Telemetry JSON Schema (Phase 2 Ready):**
|
||||
|
||||
Reserve placeholder JSON fields for telemetry events in the log schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "prefetch_success",
|
||||
"scheduleId": "notif-2025-11-15",
|
||||
"duration_ms": 2432,
|
||||
"ttl": 86400,
|
||||
"timestamp": "2025-11-15T05:48:32Z",
|
||||
"telemetry": {
|
||||
"dnp_prefetch_scheduled_total": 1,
|
||||
"dnp_prefetch_executed_total": 1,
|
||||
"dnp_prefetch_success_total": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Even if not wired yet, this ensures Phase 2 code can emit compatible structured logs.
|
||||
|
||||
**Telemetry Validation:**
|
||||
|
||||
Use optional console log validation:
|
||||
|
||||
```swift
|
||||
// In test harness or plugin
|
||||
logTelemetrySnapshot(prefix: "DNP-")
|
||||
```
|
||||
|
||||
This captures telemetry counters from structured logs for Phase 2 validation. Verify increment patterns (`scheduled → executed → success → used`).
|
||||
|
||||
**Success Criteria:**
|
||||
- For at least one full test cycle, logs and telemetry counts confirm that the sequence: scheduled → executed → success → used is coherent
|
||||
- Counters increment as expected through the prefetch lifecycle
|
||||
@@ -630,20 +694,13 @@ These counters MUST be emitted via the same pipeline as Android (e.g., structlog
|
||||
|
||||
## Glossary
|
||||
|
||||
**BGTaskScheduler** – iOS framework for scheduling background tasks (BGAppRefreshTask / BGProcessingTask). Provides heuristic-based background execution, not exact timing guarantees.
|
||||
**See:** `doc/test-app-ios/IOS_PREFETCH_GLOSSARY.md` for complete terminology definitions.
|
||||
|
||||
**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`.
|
||||
|
||||
**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
|
||||
|
||||
**UTC** – Coordinated Universal Time. All internal timestamps are stored in UTC to avoid DST and timezone issues.
|
||||
|
||||
**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.
|
||||
**Quick Reference:**
|
||||
- **BGTaskScheduler** – iOS framework for background task scheduling (see glossary)
|
||||
- **T-Lead** – Lead time between prefetch and notification (see glossary)
|
||||
- **Bucket A/B/C** – Deterministic vs heuristic classification (see glossary)
|
||||
- **UTC** – Coordinated Universal Time for timestamp storage (see glossary)
|
||||
|
||||
---
|
||||
|
||||
@@ -652,6 +709,22 @@ These counters MUST be emitted via the same pipeline as Android (e.g., structlog
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 Forward Plan
|
||||
|
||||
**Planned enhancements for Phase 2:**
|
||||
|
||||
- Implement rolling window validation
|
||||
- Integrate Prometheus metrics collector
|
||||
- Add automated CI pipeline for simulator validation
|
||||
- Verify TTL and cache invalidation logic
|
||||
- Wire telemetry counters to production pipeline
|
||||
- Add automated log sequence validation
|
||||
- Implement persistent schedule snapshot for post-run verification
|
||||
|
||||
**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