/**
 * @fileoverview Android test runner for Capacitor-based mobile app
 * 
 * This script handles the build, installation, and testing of the Android app.
 * It ensures the app is properly synced, built, installed on a device/emulator,
 * and runs the test suite.
 * 
 * Process flow:
 * 1. Sync Capacitor project with latest web build
 * 2. Build debug APK
 * 3. Install APK on connected device/emulator
 * 4. Run instrumented tests
 * 
 * Prerequisites:
 * - Android SDK installed and ANDROID_HOME set
 * - Gradle installed and in PATH
 * - Connected Android device or running emulator
 * - Capacitor Android platform added to project
 * 
 * Exit codes:
 * - 0: Tests completed successfully
 * - 1: Build, installation, or test failure
 * 
 * @example
 * // Run directly
 * node scripts/test-android.js
 * 
 * // Run via npm script
 * npm run test:android
 * 
 * @requires child_process
 * @requires path
 * 
 * @author TimeSafari Team
 * @license MIT
 */

const { execSync } = require('child_process');
const { join } = require('path');

/**
 * Runs the complete Android test suite including build, installation, and testing
 * 
 * The function performs the following steps:
 * 1. Syncs the Capacitor project with latest web build
 * 2. Builds and installs debug version of the app
 * 3. Runs instrumented Android tests
 * 
 * @async
 * @throws {Error} If any step in the build or test process fails
 * 
 * @example
 * runAndroidTests().catch(error => {
 *     console.error('Test execution failed:', error);
 *     process.exit(1);
 * });
 */
async function runAndroidTests() {
    try {
        // Sync Capacitor project with latest web build
        // This ensures the Android project has the latest web assets
        execSync('npx cap sync android', { 
            stdio: 'inherit',
            // Inherit stdio to show real-time output
        });

        // Build and install debug version of the app
        // Uses Gradle wrapper to ensure consistent build environment
        execSync('cd android && ./gradlew assembleDebug installDebug', { 
            stdio: 'inherit',
            // assembleDebug: Creates debug APK
            // installDebug: Installs APK on connected device
        });

        // Run the instrumented Android tests
        // These are the tests defined in android/app/src/androidTest
        execSync('cd android && ./gradlew connectedAndroidTest', { 
            stdio: 'inherit',
            // connectedAndroidTest: Runs tests on connected device
        });

        console.log('✅ Android tests completed successfully');
    } catch (error) {
        // Log the error and exit with failure code
        console.error('❌ Android tests failed:', error);
        process.exit(1);
    }
}

// Execute the test suite
runAndroidTests();