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:

```xml
<!-- 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:**
   ```bash
   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:

```bash
# 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`:**
```json
{
  "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:

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

---

## Debugging Strategy

### Xcode Debugger

**Check Pending Notifications:**
```swift
po UNUserNotificationCenter.current().pendingNotificationRequests()
```

**Check Permission Status:**
```swift
po await UNUserNotificationCenter.current().notificationSettings()
```

**Manually Trigger BGTask (Simulator Only):**
```swift
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