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
2025-11-17 06:09:38 +00:00
parent d7a2dbb9fd
commit f6875beae5
4 changed files with 339 additions and 19 deletions

View File

@@ -11,6 +11,7 @@
import Foundation
import BackgroundTasks
import UIKit
import os.log
/// Minimal BGTaskScheduler test harness for DailyNotificationPlugin prefetch testing
///
@@ -43,6 +44,20 @@ class DailyNotificationBackgroundTaskTestHarness {
static let prefetchTaskIdentifier = "com.timesafari.dailynotification.fetch"
// MARK: - Structured Logging
/// Swift Logger categories for structured logging
static let pluginLogger = Logger(subsystem: "com.timesafari.dailynotification", category: "plugin")
static let fetchLogger = Logger(subsystem: "com.timesafari.dailynotification", category: "fetch")
static let schedulerLogger = Logger(subsystem: "com.timesafari.dailynotification", category: "scheduler")
static let storageLogger = Logger(subsystem: "com.timesafari.dailynotification", category: "storage")
/// Log telemetry snapshot for validation
static func logTelemetrySnapshot(prefix: String = "DNP-") {
// Phase 2: Capture telemetry counters from structured logs
fetchLogger.info("Telemetry snapshot: \(prefix)prefetch_scheduled_total, \(prefix)prefetch_executed_total, \(prefix)prefetch_success_total")
}
// MARK: - Registration
/// Register BGTaskScheduler task handler
@@ -82,6 +97,40 @@ class DailyNotificationBackgroundTaskTestHarness {
}
}
// MARK: - Time Warp Simulation (Testing)
/// Simulate time warp for accelerated testing
///
/// Useful to accelerate DST, T-Lead, and cache TTL tests without waiting in real time.
/// - Parameter minutesForward: Number of minutes to advance simulated time
static func simulateTimeWarp(minutesForward: Int) {
let timeWarpOffset = TimeInterval(minutesForward * 60)
// Store time warp offset in UserDefaults for test harness use
UserDefaults.standard.set(timeWarpOffset, forKey: "DNP_TimeWarpOffset")
print("[DNP-FETCH] Time warp simulated: +\(minutesForward) minutes")
}
/// Get current time with time warp applied (testing only)
static func getWarpedTime() -> Date {
let offset = UserDefaults.standard.double(forKey: "DNP_TimeWarpOffset")
return Date().addingTimeInterval(offset)
}
// MARK: - Force Reschedule
/// Force reschedule all BGTasks and notifications
///
/// Forces re-registration of BGTasks and notifications.
/// Useful when testing repeated failures or BGTask recovery behavior.
static func forceRescheduleAll() {
print("[DNP-FETCH] Force rescheduling all tasks and notifications")
// Cancel existing tasks
BGTaskScheduler.shared.cancelAllTaskRequests()
// Re-register and reschedule
registerBackgroundTasks()
// Trigger reschedule logic (implementation-specific)
}
// MARK: - Handler
/// Handle BGAppRefreshTask execution