crowd-funder-for-time-pwa/docs/auto-run-guide.md

Auto-Run Guide

Author: Matthew Raymer
Date: 2025-07-12
Status: 🎯 ACTIVE - In Use

Overview

The TimeSafari auto-run system intelligently detects available devices and automatically builds and launches the app on the best available target. It supports Android devices/emulators, iOS devices/simulators, and Electron desktop apps.

Features

Smart Device Detection

• Android: Detects real devices vs emulators using ADB
• iOS: Detects real devices vs simulators using xcrun
• Electron: Checks for Electron availability
• Priority: Real devices preferred over simulators/emulators

Build Mode Support

• Development: Default mode for daily development
• Test: Optimized for testing with test data
• Production: Production-ready builds

Platform Targeting

• All platforms: Automatically detects and runs on all available
• Specific platform: Target only iOS, Android, or Electron
• Cross-platform: Works on macOS, Linux, and Windows

Auto-Run Options

• Build + Auto-Run: Single command to build and launch
• Smart Detection: Automatically chooses best available target
• Error Handling: Graceful fallbacks when devices unavailable

Usage

Auto-Run Script (Recommended)

# Auto-detect and run on all available platforms (development mode)
npm run auto-run

# Run in test mode
npm run auto-run:test

# Run in production mode
npm run auto-run:prod

# Target specific platforms
npm run auto-run:ios
npm run auto-run:android
npm run auto-run:electron

Build Script Auto-Run

iOS Auto-Run Commands

# Test build + auto-run
npm run build:ios:test:run

# Production build + auto-run
npm run build:ios:prod:run

# Debug build + auto-run
npm run build:ios:debug:run

# Release build + auto-run
npm run build:ios:release:run

Android Auto-Run Commands

# Test build + auto-run
npm run build:android:test:run

# Production build + auto-run
npm run build:android:prod:run

# Debug build + auto-run
npm run build:android:debug:run

# Release build + auto-run
npm run build:android:release:run

Electron Auto-Run Commands

# Development build + auto-run
npm run build:electron:dev:run

# Test build + auto-run
npm run build:electron:test:run

# Production build + auto-run
npm run build:electron:prod:run

Advanced Usage

# Direct script usage with options
./scripts/auto-run.sh --test --platform=ios
./scripts/auto-run.sh --prod --platform=android
./scripts/auto-run.sh --auto  # Skip confirmation prompts

# Build script with auto-run flag
./scripts/build-ios.sh --test --auto-run
./scripts/build-android.sh --prod --auto-run
./scripts/build-electron.sh --test --auto-run

# Combine options
./scripts/auto-run.sh --test --platform=all --auto

Command Line Options

Option	Description	Example
--test	Build and run in test mode	--test
--prod	Build and run in production mode	--prod
--platform=PLATFORM	Target specific platform	--platform=ios
--auto	Skip confirmation prompts	--auto
--auto-run	Auto-run after build	--auto-run
--help	Show help message	--help

Platform Options:

• ios - iOS devices/simulators only
• android - Android devices/emulators only
• electron - Electron desktop app only
• all - All available platforms (default)

How It Works

1. Device Detection

Android Detection:

# Uses ADB to list devices
adb devices

# Parses output to distinguish:
# - Real devices: Physical Android phones/tablets
# - Emulators: Android emulator instances

iOS Detection:

# Uses xcrun to list devices
xcrun xctrace list devices

# Parses output to distinguish:
# - Real devices: Physical iPhones/iPads
# - Simulators: iOS Simulator instances

2. Build Process

The script automatically calls the appropriate build commands:

# Development mode
npm run build:ios:dev
npm run build:android:dev
npm run build:electron:dev

# Test mode
npm run build:ios:test
npm run build:android:test
npm run build:electron:test

# Production mode
npm run build:ios:prod
npm run build:android:prod
npm run build:electron:prod

3. Launch Process

Android:

• Real devices: Install APK and launch via ADB
• Emulators: Use npx cap run android

iOS:

• Real devices: Build release version (requires Xcode setup)
• Simulators: Use npx cap run ios

Electron:

• Launch via npm run electron:start

Examples

Development Workflow

# Quick development run
npm run auto-run

# Output:
# ✅ Found 1 real Android device: ABC123DEF456
# ✅ Found 1 iOS simulator: iPhone 15 Pro
# ✅ Electron: available
# 
# Available targets:
#   Android: real:ABC123DEF456
#   iOS: simulator:iPhone 15 Pro
#   Electron: available
# 
# Continue with auto-run? (y/N): y
# 
# 🔄 Building and running Android (real: ABC123DEF456)...
# 🔄 Building and running iOS (simulator: iPhone 15 Pro)...
# 🔄 Building and running Electron...
# 
# ✅ Auto-run completed successfully! 3 platform(s) launched.

Test Mode with Build Scripts

# iOS test build + auto-run
npm run build:ios:test:run

# Android test build + auto-run
npm run build:android:test:run

# Electron test build + auto-run
npm run build:electron:test:run

# Output:
# === TimeSafari iOS Build Process ===
# 🔄 Building Capacitor version (test)...
# 🔄 Syncing with Capacitor...
# 🔄 Building iOS app...
# 🔄 Auto-running iOS app...
# ✅ iOS app launched successfully!
# ✅ iOS build completed successfully!

Production Mode

# Production build and run
npm run auto-run:prod

# Output:
# 🔄 Building Android (production)...
# 🔄 Building iOS (production)...
# 🔄 Building Electron (production)...
# 
# ✅ Auto-run completed successfully! 3 platform(s) launched.

Comparison: Auto-Run Script vs Build Scripts

Auto-Run Script (auto-run.sh)

Best for:

• Multi-platform development
• Quick testing across devices
• Automated workflows
• CI/CD integration

Features:

• Smart device detection
• Multi-platform support
• Interactive confirmation
• Error recovery

Build Scripts with --auto-run

Best for:

• Single platform development
• Specific build configurations
• Non-interactive workflows
• Build customization

Features:

• Platform-specific optimization
• Build customization options
• Direct control over build process
• Integration with existing workflows

Troubleshooting

Common Issues

No devices detected:

# Check Android devices
adb devices

# Check iOS devices (macOS only)
xcrun xctrace list devices

# Check Electron availability
which electron

Build failures:

# Clean and rebuild
npm run clean:android
npm run clean:ios
npm run clean:electron

# Then retry auto-run
npm run auto-run

Permission issues:

# Make script executable
chmod +x scripts/auto-run.sh

# Check ADB permissions (Android)
adb kill-server
adb start-server

Platform-Specific Issues

Android:

• Ensure ADB is in PATH
• Enable USB debugging on device
• Accept device authorization prompt
• Check device is in "device" state (not "unauthorized")

iOS:

• Requires macOS with Xcode
• Ensure Xcode command line tools installed
• Check iOS Simulator is available
• For real devices: Requires proper certificates

Electron:

• Ensure Electron is installed globally or locally
• Check Node.js version compatibility
• Verify build dependencies are installed

Debug Mode

Enable verbose logging by modifying the script:

# Add debug logging to auto-run.sh
set -x  # Enable debug mode

Integration with CI/CD

The auto-run script can be integrated into CI/CD pipelines:

# Example GitHub Actions workflow
- name: Auto-run tests
  run: |
        npm run auto-run:test --auto
  env:
    # Set environment variables for CI
    CI: true

Best Practices

Development Workflow

1. Daily development: Use npm run auto-run for quick testing
2. Testing: Use npm run auto-run:test before commits
3. Production: Use npm run auto-run:prod for final testing
4. Single platform: Use npm run build:ios:test:run for focused work

Device Management

1. Keep devices connected: Reduces detection time
2. Use consistent device names: Helps with identification
3. Regular cleanup: Clear old builds and caches

Performance Tips

1. Use --auto flag: Skip prompts in automated workflows
2. Target specific platforms: Use --platform=ios for faster runs
3. Parallel execution: Script runs platforms in sequence (can be optimized)

Future Enhancements

Planned Features

• Parallel execution: Run multiple platforms simultaneously
• Device selection: Choose specific devices when multiple available
• Custom build configurations: Support for custom build modes
• Integration with IDEs: VS Code and other IDE integration
• Performance monitoring: Track build and launch times

Contributing

To add new features or fix issues:

1. Modify scripts/auto-run.sh
2. Update this documentation
3. Test on multiple platforms
4. Submit pull request

Related Documentation

• iOS Simulator Build and Icons
• Android Build Guide
• Electron Build Guide
• Testing Guide