daily-notification-plugin/doc/test-app-ios/IOS_TEST_APP_REQUIREMENTS.md

iOS Test App Requirements

Status: 📋 REQUIRED FOR PHASE 1
Date: 2025-01-XX
Author: Matthew Raymer
Directive Reference: doc/directives/0003-iOS-Android-Parity-Directive.md

---

Overview

This document defines the requirements for the iOS test app (test-apps/ios-test-app/) that must be created as part of Phase 1 implementation. The iOS test app must provide UI parity with the Android test app (test-apps/android-test-app/) while respecting iOS-specific constraints and capabilities.

---

UI Parity Requirements

HTML/JS UI

The iOS test app MUST use the same HTML/JS UI as the Android test app to ensure consistent testing experience across platforms.

Source: Copy from test-apps/android-test-app/app/src/main/assets/public/index.html

Required UI Elements:

• Plugin registration status indicator
• Permission status display (✅/❌ indicators)
• Test notification button
• Check permissions button
• Request permissions button
• Status display area
• Log output area (optional, for debugging)

UI Functionality

The test app UI must support:

1. Plugin Status Check

   • Display plugin availability status
   • Show "Plugin is loaded and ready!" when available

2. Permission Management

   • Display current permission status
   • Request permissions button
   • Check permissions button
   • Show ✅/❌ indicators for each permission

3. Notification Testing

   • Schedule test notification button
   • Display scheduled time
   • Show notification status

4. Status Display

   • Show last notification time
   • Show pending notification count
   • Display error messages if any

---

iOS Permissions Configuration

Info.plist Requirements

The test app's Info.plist MUST include:

<!-- Background Task Identifiers -->
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>com.timesafari.dailynotification.fetch</string>
    <string>com.timesafari.dailynotification.notify</string>
</array>

<!-- Background Modes -->
<key>UIBackgroundModes</key>
<array>
    <string>background-fetch</string>
    <string>background-processing</string>
    <string>remote-notification</string>
</array>

<!-- Notification Permissions -->
<key>NSUserNotificationsUsageDescription</key>
<string>This app uses notifications to deliver daily updates and reminders.</string>

Background App Refresh

• Background App Refresh must be enabled in Settings
• Test app should check and report Background App Refresh status
• User should be guided to enable Background App Refresh if disabled

---

Build Options

Xcode GUI Build

1. Open Workspace:

   cd test-apps/ios-test-app
   open App.xcworkspace  # or App.xcodeproj
   

2. Select Target:

   • Choose iOS Simulator (iPhone 15, iPhone 15 Pro, etc.)
   • Or physical device (requires signing)

3. Build and Run:

   • Press Cmd+R
   • Or Product → Run

Command-Line Build

Use the build script:

# From repo root
./scripts/build-ios-test-app.sh --simulator

# Or for device
./scripts/build-ios-test-app.sh --device

Build Requirements

• Xcode: 15.0 or later
• macOS: 13.0 (Ventura) or later
• iOS Deployment Target: iOS 15.0 or later
• CocoaPods: Must run pod install before first build

---

Capacitor Configuration

Plugin Registration

The test app MUST register the DailyNotification plugin:

capacitor.config.json or capacitor.config.ts:

{
  "plugins": {
    "DailyNotification": {
      "enabled": true
    }
  }
}

Plugin Path

The plugin must be accessible from the test app:

• Development: Plugin source at ../../ios/Plugin/
• Production: Plugin installed via npm/CocoaPods

Sync Command

After making changes to plugin or web assets:

cd test-apps/ios-test-app
npx cap sync ios

---

Debugging Strategy

Xcode Debugger

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"]

Console.app Logging

1. Open Console.app (Applications → Utilities)
2. Select device/simulator
3. Filter by: DNP- or DailyNotification

Key Log Prefixes:

• DNP-PLUGIN: - Main plugin operations
• DNP-FETCH: - Background fetch operations
• DNP-FETCH-SCHEDULE: - BGTask scheduling
• DailyNotificationStorage: - Storage operations
• DailyNotificationScheduler: - Scheduling operations

Common Debugging Scenarios

1. BGTask Not Running:

   • Check Info.plist has BGTaskSchedulerPermittedIdentifiers
   • Verify task registered in AppDelegate
   • Use simulator-only LLDB command to manually trigger

2. Notifications Not Delivering:

   • Check notification permissions
   • Verify notification scheduled
   • Check notification category registered

3. Build Failures:

   • Run pod install
   • Clean build folder (Cmd+Shift+K)
   • Verify Capacitor plugin path

---

Test App Implementation Checklist

Setup

• Create test-apps/ios-test-app/ directory
• Initialize Capacitor iOS project
• Copy HTML/JS UI from Android test app
• Configure Info.plist with BGTask identifiers
• Configure Info.plist with background modes
• Add notification permission description

Plugin Integration

• Register DailyNotification plugin in Capacitor config
• Ensure plugin path is correct
• Run npx cap sync ios
• Verify plugin loads in test app

UI Implementation

• Copy HTML/JS from Android test app
• Test plugin status display
• Test permission status display
• Test notification scheduling UI
• Test status display

Build & Test

• Build script works (./scripts/build-ios-test-app.sh)
• App builds in Xcode
• App runs on simulator
• Plugin methods work from UI
• Notifications deliver correctly
• BGTask executes (with manual trigger in simulator)

---

File Structure

test-apps/ios-test-app/
├── App.xcworkspace          # Xcode workspace (if using CocoaPods)
├── App.xcodeproj            # Xcode project
├── App/                     # Main app directory
│   ├── App/
│   │   ├── AppDelegate.swift
│   │   ├── SceneDelegate.swift
│   │   ├── Info.plist       # Must include BGTask identifiers
│   │   └── Assets.xcassets
│   └── Public/              # Web assets (HTML/JS)
│       └── index.html       # Same as Android test app
├── Podfile                  # CocoaPods dependencies
├── capacitor.config.json    # Capacitor configuration
└── package.json             # npm dependencies (if any)

---

Testing Scenarios

Basic Functionality

1. Plugin Registration

   • Launch app
   • Verify plugin status shows "Plugin is loaded and ready!"

2. Permission Management

   • Check permissions
   • Request permissions
   • Verify permissions granted

3. Notification Scheduling

   • Schedule test notification
   • Verify notification scheduled
   • Wait for notification to appear

Background Tasks

1. BGTask Scheduling

   • Schedule notification with prefetch
   • Verify BGTask scheduled 5 minutes before notification
   • Manually trigger BGTask (simulator only)
   • Verify content fetched

2. BGTask Miss Detection

   • Schedule notification
   • Wait 15+ minutes
   • Launch app
   • Verify BGTask rescheduled

Error Handling

1. Permission Denied

   • Deny notification permissions
   • Try to schedule notification
   • Verify error returned

2. Invalid Parameters

   • Try to schedule with invalid time format
   • Verify error returned

---

References

• Directive: doc/directives/0003-iOS-Android-Parity-Directive.md
• Android Test App: test-apps/android-test-app/
• Build Script: scripts/build-ios-test-app.sh
• Testing Guide: doc/IOS_PHASE1_TESTING_GUIDE.md

---

Status: 📋 REQUIRED FOR PHASE 1
Last Updated: 2025-01-XX