browserstack-sdk.yml

name: BrowserStack SDK Tests

# ============================================================================
# WORKFLOW TRIGGERS
# ============================================================================
# This workflow is triggered by:
# 1. Push events to main/develop/appiumMobile branches
# 2. Pull requests to main/develop
# 3. Manual dispatch (workflow_dispatch) with custom platform/tag selections
on:
  push:
    branches:
      - main
      - develop
      - appiumMobile
  pull_request:
    branches:
      - main
      - develop
  # schedule:
    # Runs daily at 3:00 AM UTC
    # Use https://crontab.guru to adjust timing
    # 0 3 * * * = Every day at 3:00 AM
    # - cron: '0 3 * * *'
  workflow_dispatch:
    # Allows manual triggering from GitHub UI with custom inputs
    # Usage: Actions tab → Run Workflow → Select platform and tags
    inputs:
      platform:
        description: 'Platform to test'
        required: true
        default: 'android'
        type: choice
        options:
          - android
          - ios
          - both
      tags:
        description: 'Cucumber tags filter'
        required: false
        default: 'platform-default'
        type: choice
        options:
          - platform-default
          - '@androidOnly'
          - '@iosOnly'
          - '@smoke'
          - '@regression'
          - 'custom'

env:
  # Global environment variables for all jobs
  JAVA_VERSION: '21'  # Java version for compilation and test execution
  MAVEN_OPTS: '-Xmx1024m'  # Maven heap memory (for iOS stability)

jobs:
  # ============================================================================
  # Build & Validate
  # ============================================================================
  # Purpose: Compile and validate the project before running tests
  # This job runs first and other jobs depend on it (needs: build)
  build:
    name: Build & Validate
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Setup Java ${{ env.JAVA_VERSION }}
        uses: actions/setup-java@v4
        with:
          java-version: ${{ env.JAVA_VERSION }}
          distribution: 'temurin'
          cache: maven
      
      - name: Validate & Compile
        run: mvn clean compile test-compile --no-transfer-progress
      
      - name: Cache Maven packages
        uses: actions/cache@v4
        with:
          # Caches ~/.m2/repository to speed up subsequent builds
          path: ~/.m2/repository
          key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
          restore-keys: |
            ${{ runner.os }}-maven-

  # ============================================================================
  # Android SDK Tests
  # ============================================================================
  # Purpose: Run Android tests on BrowserStack cloud
  # Trigger Condition: Runs if platform is 'android' or 'both'
  # Dependency: Waits for 'build' job to complete (needs: build)
  test-android-sdk:
    name: Android SDK Tests (BrowserStack)
    runs-on: ubuntu-latest
    needs: build
    if: |
      github.event.inputs.platform == 'android' || 
      github.event.inputs.platform == 'both' || 
      github.event.inputs.platform == '' ||
      github.event_name != 'workflow_dispatch'
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Setup Java ${{ env.JAVA_VERSION }}
        uses: actions/setup-java@v4
        with:
          java-version: ${{ env.JAVA_VERSION }}
          distribution: 'temurin'
          cache: maven
      
      - name: Verify BrowserStack credentials
        run: |
          if [ -z "${{ secrets.BROWSERSTACK_USERNAME }}" ] || [ -z "${{ secrets.BROWSERSTACK_ACCESS_KEY }}" ]; then
            echo "::error::BrowserStack credentials not configured. Add BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY to repository secrets."
            exit 1
          fi
      
      - name: Determine Cucumber tags
        id: tags
        run: |
          TAG_INPUT="${{ github.event.inputs.tags }}"
          if [ "$TAG_INPUT" = "platform-default" ] || [ -z "$TAG_INPUT" ]; then
            echo "filter=@androidOnly" >> $GITHUB_OUTPUT
          elif [ "$TAG_INPUT" = "custom" ]; then
            echo "filter=" >> $GITHUB_OUTPUT
          else
            echo "filter=$TAG_INPUT" >> $GITHUB_OUTPUT
          fi
      
      - name: Run Android SDK Tests
        env:
          BROWSERSTACK_USERNAME: ${{ secrets.BROWSERSTACK_USERNAME }}
          BROWSERSTACK_ACCESS_KEY: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
        run: |
          # Maven command structure:
          # -DsuiteXmlFile: TestNG suite file
          # -Dbrowserstack.config: YAML config file with app ID and device list
          # -Dplatform=android: Sets platform for DriverFactory
          # -Dcucumber.filter.tags: Applies tag filters (@androidOnly, @smoke, etc.)
          mvn clean test \
            -DsuiteXmlFile=testngSuite.xml \
            -Dbrowserstack.config=browserstack-android-ci.yml \
            -Dplatform=android \
            -Dcucumber.filter.tags="${{ steps.tags.outputs.filter }}" \
            --no-transfer-progress \
            -q
      
      - name: Upload Test Reports
        # Uploads test artifacts (Extent Reports, SureFire reports, Cucumber HTML)
        # Runs even if tests fail (if: always())
        # Retention: 30 days
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: android-sdk-reports
          path: |
            target/extent-reports/
            target/surefire-reports/
            target/reports/cucumber-report/
          retention-days: 30
      
      - name: Upload Logs
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: android-sdk-logs
          path: target/logs/
          retention-days: 7
      
      - name: Publish Test Results
        if: always()
        uses: EnricoMi/publish-unit-test-result-action@v2
        with:
          files: target/surefire-reports/TEST-*.xml
          check_name: Android SDK Test Results

  # ============================================================================
  # iOS SDK Tests
  # ============================================================================
  # Purpose: Run iOS tests on BrowserStack cloud
  # Trigger Condition: Runs if platform is 'ios' or 'both' OR automatic push triggers
  # Dependency: Waits for 'build' job to complete (needs: build)
  # Note: if condition includes automatic triggers for push events
  test-ios-sdk:
    name: iOS SDK Tests (BrowserStack)
    runs-on: ubuntu-latest
    needs: build
    if: |
      github.event.inputs.platform == 'ios' || 
      github.event.inputs.platform == 'both' ||
      github.event_name != 'workflow_dispatch'
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Setup Java ${{ env.JAVA_VERSION }}
        uses: actions/setup-java@v4
        with:
          java-version: ${{ env.JAVA_VERSION }}
          distribution: 'temurin'
          cache: maven
      
      - name: Verify BrowserStack credentials
        run: |
          if [ -z "${{ secrets.BROWSERSTACK_USERNAME }}" ] || [ -z "${{ secrets.BROWSERSTACK_ACCESS_KEY }}" ]; then
            echo "::error::BrowserStack credentials not configured. Add BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY to repository secrets."
            exit 1
          fi
      
      - name: Determine Cucumber tags
        id: tags
        run: |
          TAG_INPUT="${{ github.event.inputs.tags }}"
          if [ "$TAG_INPUT" = "platform-default" ] || [ -z "$TAG_INPUT" ]; then
            echo "filter=@iosOnly" >> $GITHUB_OUTPUT
          elif [ "$TAG_INPUT" = "custom" ]; then
            echo "filter=" >> $GITHUB_OUTPUT
          else
            echo "filter=$TAG_INPUT" >> $GITHUB_OUTPUT
          fi
      
      - name: Run iOS SDK Tests
        env:
          BROWSERSTACK_USERNAME: ${{ secrets.BROWSERSTACK_USERNAME }}
          BROWSERSTACK_ACCESS_KEY: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
        run: |
          # Same Maven structure as Android, but with iOS-specific config
          # browserstack-ios-ci.yml contains: iOS devices, automationName: XCUITest, app ID
          mvn clean test \
            -DsuiteXmlFile=testngSuite.xml \
            -Dbrowserstack.config=browserstack-ios-ci.yml \
            -Dplatform=ios \
            -Dcucumber.filter.tags="${{ steps.tags.outputs.filter }}" \
            --no-transfer-progress \
            -q
      
      - name: Upload Test Reports
        # Same as Android: uploads all test artifacts
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: ios-sdk-reports
          path: |
            target/extent-reports/
            target/surefire-reports/
            target/reports/cucumber-report/
          retention-days: 30
      
      - name: Upload Logs
        # Uploads logs only if tests failed (if: failure())
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: ios-sdk-logs
          path: target/logs/
          retention-days: 7
      
      - name: Publish Test Results
        # Parses TestNG XML reports and publishes results to GitHub
        # Creates a check run in the workflow summary
        if: always()
        uses: EnricoMi/publish-unit-test-result-action@v2
        with:
          files: target/surefire-reports/TEST-*.xml
          check_name: iOS SDK Test Results

  # ============================================================================
  # Summary Report
  # ============================================================================
  # Purpose: Display final test summary in workflow UI
  # Runs after all test jobs (both Android and iOS) complete
  summary:
    name: Test Summary
    runs-on: ubuntu-latest
    needs: [test-android-sdk, test-ios-sdk]
    if: always()  # Runs regardless of test results to always show summary
    
    steps:
      - name: Download all artifacts
        # Collects all uploaded artifacts (reports, logs) from previous jobs
        uses: actions/download-artifact@v4
        with:
          path: reports
      
      - name: Generate Summary
        # Creates a summary markdown output visible in workflow UI
        # Shows test results, branch info, and links to artifacts
        run: |
          echo "## 📊 Test Execution Summary" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "**Workflow:** ${{ github.workflow }}" >> $GITHUB_STEP_SUMMARY
          echo "**Trigger:** ${{ github.event_name }}" >> $GITHUB_STEP_SUMMARY
          echo "**Branch:** ${{ github.ref_name }}" >> $GITHUB_STEP_SUMMARY
          echo "**Commit:** ${{ github.sha }}" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "### Test Results" >> $GITHUB_STEP_SUMMARY
          echo "- 🤖 Android SDK: ${{ needs.test-android-sdk.result }}" >> $GITHUB_STEP_SUMMARY
          echo "- 🍎 iOS SDK: ${{ needs.test-ios-sdk.result }}" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "View detailed reports in artifacts section." >> $GITHUB_STEP_SUMMARY
      
      - name: Check overall status
        # Fails the workflow if any test job failed
        run: |
          if [ "${{ needs.test-android-sdk.result }}" == "failure" ] || [ "${{ needs.test-ios-sdk.result }}" == "failure" ]; then
            echo "::error::One or more test jobs failed"
            exit 1
          fi