daily-notification-plugin/test-apps/README.md

TimeSafari Test Apps Setup Guide

Overview

This guide creates minimal Capacitor test apps for validating the TimeSafari Daily Notification Plugin integration across all target platforms. The test apps demonstrate TimeSafari's community-building features, Endorser.ch API integration, and notification patterns.

Directory Structure

test-apps/
├── android-test/          # Android test app
├── ios-test/              # iOS test app  
├── electron-test/         # Electron test app
├── test-api/              # TimeSafari Test API server
├── shared/                # Shared configuration and utilities
│   └── config-loader.ts   # Configuration loader and mock services
├── config/                # Configuration files
│   └── timesafari-config.json
├── setup-android.sh       # Android setup script
├── setup-ios.sh           # iOS setup script
├── setup-electron.sh      # Electron setup script
├── check-environment.sh   # Environment verification
├── SETUP_GUIDE.md         # Enhanced setup guide
└── README.md              # This guide

Prerequisites

• Node.js 18+
• Capacitor CLI: npm install -g @capacitor/cli
• Android Studio (for Android)
• Xcode (for iOS)
• Platform-specific SDKs
• Understanding of TimeSafari's community-building purpose
• Familiarity with Endorser.ch API patterns

Quick Start

Option 1: Automated Setup (Recommended)

# Navigate to test-apps directory first
cd test-apps

# Setup all platforms (run from test-apps directory)
./setup-android.sh
./setup-ios.sh  
./setup-electron.sh

⚠️ Important: Run setup scripts from the test-apps directory, not from individual platform directories.

Option 2: Manual Setup

See Enhanced Setup Guide for detailed manual setup instructions and troubleshooting.

Prerequisites Check

# Check your environment before setup
./check-environment.sh

Required Software:

• Node.js 18+: Required for all platforms
• Android Studio: Required for Android testing
• Xcode: Required for iOS testing (macOS only)
• No additional requirements: For Electron testing

Test App Features

Each test app includes comprehensive UI patterns and testing capabilities:

Core Testing Features

• TimeSafari Configuration: Test community-focused notification settings
• Endorser.ch API Integration: Test real API patterns with pagination
• Community Notification Scheduling: Test offers, projects, people, and items notifications
• Performance Monitoring: Metrics collection and display
• Error Handling: Comprehensive error testing
• Debug Information: Platform-specific debug data

Enhanced UI Components

• Permission Management: Request dialogs, status displays, settings integration
• Configuration Panels: Settings toggles, time pickers, content type selection
• Status Dashboards: Real-time monitoring with performance metrics
• Platform-Specific Features:
  • Android: Battery optimization, exact alarm permissions, reboot recovery
  • iOS: Background app refresh, rolling window management, BGTaskScheduler
  • Electron: Service worker status, push notifications, IPC communication
• Error Handling UI: User-friendly error displays with retry mechanisms
• Testing Tools: Test notification panels, debug info, log export

UI Design Features

• Responsive Design: Mobile-first approach with touch-friendly interfaces
• Accessibility: WCAG 2.1 AA compliance with keyboard navigation
• Platform Native: Material Design (Android), Human Interface Guidelines (iOS)
• Progressive Disclosure: Essential features first, advanced options on demand
• Real-time Updates: Live status monitoring and performance metrics

TimeSafari Test API Server

A comprehensive REST API server (test-api/) simulates Endorser.ch API endpoints for testing the plugin's TimeSafari-specific functionality:

Quick Start

# Start the TimeSafari Test API server
cd test-apps/test-api
npm install
npm start

# Test the API
npm run demo

Key Features

• Endorser.ch API Simulation: Mock endpoints for offers, projects, and pagination
• TimeSafari Notification Bundle: Single route for bundled notifications
• Community Analytics: Analytics endpoint for community events
• Pagination Support: Full afterId/beforeId pagination testing
• ETag Support: HTTP caching with conditional requests
• Error Simulation: Test various error scenarios
• Metrics: Monitor API usage and performance
• CORS Enabled: Cross-origin requests supported

API Endpoints

Endorser.ch API Endpoints

• GET /api/v2/report/offers - Get offers to person
• GET /api/v2/report/offersToPlansOwnedByMe - Get offers to user's projects
• POST /api/v2/report/plansLastUpdatedBetween - Get changes to starred projects

TimeSafari API Endpoints

• GET /api/v2/report/notifications/bundle - Get bundled notifications
• POST /api/analytics/community-events - Send community analytics

Legacy Endpoints

• GET /health - Health check
• GET /api/content/:slotId - Get notification content
• GET /api/metrics - API metrics

Platform-Specific URLs

• Web/Electron: http://localhost:3001
• Android Emulator: http://10.0.2.2:3001
• iOS Simulator: http://localhost:3001
• Physical Devices: http://[YOUR_IP]:3001

Platform-Specific Testing

Android Test App

• TimeSafari Configuration: Test community notification settings
• Endorser.ch API Integration: Test parallel API requests
• Exact Alarm Status: Check permission and capability
• Permission Requests: Test exact alarm permission flow
• Performance Metrics: Monitor Android-specific optimizations
• Reboot Recovery: Validate system restart handling
• Enhanced UI: Permission dialogs, battery optimization, exact alarm management
• Status Dashboard: Real-time monitoring with Android-specific metrics
• Error Handling: User-friendly error displays with retry mechanisms

iOS Test App

• TimeSafari Configuration: Test iOS community features
• Rolling Window: Test notification limit management
• Endorser.ch API Integration: Test pagination patterns
• Background Tasks: Validate BGTaskScheduler integration
• Performance Metrics: Monitor iOS-specific optimizations
• Memory Management: Test object pooling and cleanup
• Enhanced UI: Background refresh dialogs, rolling window controls, BGTaskScheduler status
• Status Dashboard: Real-time monitoring with iOS-specific metrics
• Error Handling: User-friendly error displays with retry mechanisms

Electron Test App

• TimeSafari Configuration: Test Electron community features
• Mock Implementations: Test web platform compatibility
• Endorser.ch API Integration: Test API patterns
• IPC Communication: Validate Electron-specific APIs
• Development Workflow: Test plugin integration
• Debug Information: Platform-specific status display
• Enhanced UI: Service worker status, push notification setup, debug information
• Status Dashboard: Real-time monitoring with Electron-specific metrics
• Error Handling: User-friendly error displays with retry mechanisms

Running the Test Apps

Android

cd android-test
npm run dev          # Web development server
npx cap open android # Open in Android Studio
npx cap run android  # Run on device/emulator

iOS

cd ios-test
npm run dev         # Web development server
npx cap open ios    # Open in Xcode
npx cap run ios     # Run on device/simulator

Electron

cd electron-test
npm start           # Run Electron app
npm run dev         # Run in development mode

Testing Checklist

Core Functionality

• TimeSafari configuration works
• Community notification scheduling succeeds
• Endorser.ch API integration functions properly
• Error handling functions properly
• Performance metrics are accurate

Enhanced UI Testing

• Permission management dialogs display correctly
• Settings panels save and load configuration
• Status dashboards show real-time data
• Error handling UI displays user-friendly messages
• Platform-specific features work as expected
• Responsive design works on different screen sizes
• Accessibility features function properly

Platform-Specific

• Android exact alarm permissions, battery optimization, reboot recovery
• iOS rolling window management, background refresh, BGTaskScheduler
• Electron mock implementations, service worker, push notifications
• Cross-platform API consistency

TimeSafari Integration

• Plugin loads without errors
• Configuration persists across sessions
• Endorser.ch API pagination works
• Community notification types process correctly
• Performance optimizations active
• Debug information accessible

Troubleshooting

Common Issues

1. "Unknown command: cap" → Install Capacitor CLI: npm install -g @capacitor/cli
2. "android platform has not been added yet" → Run npx cap add android first
3. Build failures → Check Node.js version (18+) and clear cache: npm cache clean --force
4. Platform errors → Verify platform-specific SDKs are installed
5. API connection errors → Ensure test API server is running on port 3001

Quick Fixes

# Check environment
./check-environment.sh

# Reinstall dependencies
rm -rf node_modules && npm install

# Clear Capacitor cache
npx cap clean

# Re-sync platforms
npx cap sync

# Restart test API server
cd test-api && npm start

Detailed Help

See Enhanced Setup Guide for comprehensive troubleshooting and platform-specific solutions.

Next Steps

1. Run Setup Scripts: Execute platform-specific setup
2. Start Test API Server: Run the TimeSafari Test API server
3. Test Core Features: Validate basic TimeSafari functionality
4. Test Platform Features: Verify platform-specific capabilities
5. Test Endorser.ch Integration: Validate API patterns and pagination
6. Integration Testing: Test with actual plugin implementation
7. Performance Validation: Monitor metrics and optimizations