feat: add Android support (adb, SauceLabs)

.github/workflows/app-runner.yml

@@ -1,4 +1,5 @@
 name: AppRunner
+permissions: read-all
 
 on:
   push:
@@ -13,8 +14,15 @@ on:
 jobs:
   test:
     uses: ./.github/workflows/test-powershell-module.yml
+    secrets: inherit
     with:
       module-name: SentryAppRunner
       module-path: app-runner
       test-path: Tests
+      exclude-path: Adb.Tests.ps1
       settings-path: PSScriptAnalyzerSettings.psd1
+
+  test-adb:
+    uses: ./.github/workflows/test-adb-provider.yml
+    with:
+      module-path: app-runner

.github/workflows/test-adb-provider.yml

@@ -0,0 +1,64 @@
+name: Test ADB Provider
+permissions:
+  contents: read
+
+on:
+  workflow_call:
+    inputs:
+      module-path:
+        description: 'Path to the module directory'
+        required: true
+        type: string
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ${{ inputs.module-path }}
+        shell: pwsh
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Enable KVM group permissions
+        run: |
+          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
+          sudo udevadm control --reload-rules
+          sudo udevadm trigger --name-match=kvm
+
+      - name: Setup Android directories
+        run: |
+          mkdir -p $HOME/.android/avd
+          touch $HOME/.android/repositories.cfg
+
+      - name: Install Android SDK Build Tools
+        shell: bash
+        run: |
+          ${ANDROID_HOME}/cmdline-tools/latest/bin/sdkmanager --install "build-tools;35.0.0"
+          echo "${ANDROID_HOME}/build-tools/35.0.0" >> $GITHUB_PATH
+
+      - name: Run ADB Provider Integration Tests
+        uses: reactivecircus/android-emulator-runner@d94c3fbe4fe6a29e4a5ba47c12fb47677c73656b
+        timeout-minutes: 45
+        with:
+          api-level: 35
+          target: 'google_apis'
+          arch: x86_64
+          force-avd-creation: true
+          disable-animations: true
+          disable-spellchecker: true
+          emulator-options: >
+            -no-window
+            -no-snapshot-save
+            -gpu swiftshader_indirect
+            -noaudio
+            -no-boot-anim
+            -camera-back none
+            -camera-front none
+          script: |
+            adb wait-for-device
+            echo "Android emulator is ready"
+            adb devices
+            cd ${{ inputs.module-path }} && pwsh -Command "Invoke-Pester Tests/Adb.Tests.ps1 -CI"

.github/workflows/test-powershell-module.yml

@@ -23,6 +23,11 @@ on:
         required: false
         type: string
         default: ''
+      exclude-path:
+        description: 'Comma-separated list of test file paths to exclude (relative to test-path)'
+        required: false
+        type: string
+        default: ''
       settings-path:
         description: 'Path to PSScriptAnalyzer settings file (relative to repo root)'
         required: false
@@ -74,6 +79,10 @@ jobs:
       run:
         working-directory: ${{ inputs.module-path }}
         shell: pwsh
+    env:
+      SAUCE_USERNAME: ${{ secrets.SAUCE_USERNAME }}
+      SAUCE_ACCESS_KEY: ${{ secrets.SAUCE_ACCESS_KEY }}
+      SAUCE_REGION: us-west-1
 
     steps:
       - name: Checkout repository
@@ -94,6 +103,16 @@ jobs:
             $config.Filter.ExcludeTag = $excludeTags.Split(',').Trim()
           }
 
+          $excludePath = "${{ inputs.exclude-path }}"
+          if ($excludePath) {
+            $testPath = "${{ inputs.test-path }}"
+            $config.Run.ExcludePath = $excludePath.Split(',').Trim() | ForEach-Object {
+                $relativePath = Join-Path $testPath $_
+                # ExcludePath requires absolute paths
+                Join-Path (Get-Location) $relativePath
+            }
+          }
+
           $testResults = Invoke-Pester -Configuration $config
 
           Write-Host "Test Summary:" -ForegroundColor Cyan

README.md

@@ -21,10 +21,9 @@ Currently supported:
   - Windows
   - macOS
   - Linux
-
-Future support planned:
-
-- Mobile platforms (iOS, Android)
+- **Mobile Platforms:**
+  - Android (via ADB or SauceLabs Real Device Cloud)
+  - iOS (via SauceLabs - coming soon)
 
 ## Requirements
 

app-runner/Private/AndroidHelpers.ps1

@@ -0,0 +1,188 @@
+# Android Helper Functions
+# Shared utilities for Android device providers (ADB and SauceLabs)
+
+<#
+.SYNOPSIS
+Converts an Android activity path into package name and activity name components.
+
+.DESCRIPTION
+Converts the ExecutablePath format used by Android apps: "package.name/activity.name"
+Returns a hashtable with PackageName and ActivityName properties.
+
+.PARAMETER ExecutablePath
+The full activity path in format "package.name/activity.name"
+
+.EXAMPLE
+ConvertFrom-AndroidActivityPath "io.sentry.unreal.sample/com.epicgames.unreal.GameActivity"
+Returns: @{ PackageName = "io.sentry.unreal.sample"; ActivityName = "com.epicgames.unreal.GameActivity" }
+
+.EXAMPLE
+ConvertFrom-AndroidActivityPath "com.example.app/.MainActivity"
+Returns: @{ PackageName = "com.example.app"; ActivityName = ".MainActivity" }
+#>
+function ConvertFrom-AndroidActivityPath {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string]$ExecutablePath
+    )
+
+    if ($ExecutablePath -notmatch '^([^/]+)/(.+)$') {
+        throw "ExecutablePath must be in format 'package.name/activity.name'. Got: $ExecutablePath"
+    }
+
+    return @{
+        PackageName  = $matches[1]
+        ActivityName = $matches[2]
+    }
+}
+
+<#
+.SYNOPSIS
+Validates that Android Intent extras are in the correct format.
+
+.DESCRIPTION
+Android Intent extras should be passed in the format understood by `am start`.
+This function validates and optionally formats the arguments string.
+
+Common Intent extra formats:
+  -e key value          String extra
+  -es key value         String extra (explicit)
+  -ez key true|false    Boolean extra
+  -ei key value         Integer extra
+  -el key value         Long extra
+
+.PARAMETER Arguments
+The arguments string to validate/format
+
+.EXAMPLE
+Test-IntentExtrasFormat "-e cmdline -crash-capture"
+Returns: $true
+
+.EXAMPLE
+Test-IntentExtrasFormat "-e test true -ez debug false"
+Returns: $true
+#>
+function Test-IntentExtrasFormat {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory = $false)]
+        [string]$Arguments
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Arguments)) {
+        return $true
+    }
+
+    # Intent extras must start with flags: -e, -es, -ez, -ei, -el, -ef, -eu, etc.
+    # Followed by at least one whitespace and additional content
+    if ($Arguments -notmatch '^--?[a-z]{1,2}\s+') {
+        throw "Invalid Intent extras format: '$Arguments'. Must start with flags like -e, -es, -ez, -ei, -el, etc. followed by key-value pairs."
+    }
+
+    return $true
+}
+
+<#
+.SYNOPSIS
+Extracts the package name from an APK file using aapt.
+
+.DESCRIPTION
+Extracts the real package name from an APK file using aapt (Android Asset Packaging Tool).
+Requires aapt or aapt2 to be available in PATH.
+
+.PARAMETER ApkPath
+Path to the APK file
+
+.EXAMPLE
+Get-ApkPackageName "MyApp.apk"
+Returns: "com.example.myapp" (actual package name from AndroidManifest.xml)
+
+.EXAMPLE
+Get-ApkPackageName "SentryPlayground.apk"
+Returns: "io.sentry.sample"
+
+.NOTES
+Requires aapt or aapt2 to be in PATH or Android SDK to be installed.
+Throws an error if aapt is not available or if the package name cannot be extracted.
+#>
+function Get-ApkPackageName {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string]$ApkPath
+    )
+
+    if (-not (Test-Path $ApkPath)) {
+        throw "APK file not found: $ApkPath"
+    }
+
+    if ($ApkPath -notlike '*.apk') {
+        throw "File must be an .apk file. Got: $ApkPath"
+    }
+
+    # Find aapt or aapt2
+    $aaptCmd = Get-Command aapt -ErrorAction SilentlyContinue
+    if (-not $aaptCmd) {
+        $aaptCmd = Get-Command aapt2 -ErrorAction SilentlyContinue
+    }
+
+    if (-not $aaptCmd) {
+        throw "aapt or aapt2 not found in PATH. Please install Android SDK Build Tools and ensure aapt is available in PATH."
+    }
+
+    Write-Debug "Using $($aaptCmd.Name) to extract package name from APK"
+
+    try {
+        $PSNativeCommandUseErrorActionPreference = $false
+        $output = & $aaptCmd.Name dump badging $ApkPath 2>&1
+
+        # Parse output for package name: package: name='com.example.app'
+        foreach ($line in $output) {
+            if ($line -match "package:\s+name='([^']+)'") {
+                $packageName = $matches[1]
+                Write-Debug "Extracted package name: $packageName"
+                return $packageName
+            }
+        }
+
+        throw "Failed to extract package name from APK using aapt. APK may be corrupted or invalid."
+    }
+    finally {
+        $PSNativeCommandUseErrorActionPreference = $true
+    }
+}
+
+<#
+.SYNOPSIS
+Parses logcat output into structured format.
+
+.DESCRIPTION
+Converts raw logcat output (array of strings) into a consistent format
+that can be used by test utilities like Get-EventIds.
+
+.PARAMETER LogcatOutput
+Array of logcat log lines (raw output from adb or SauceLabs)
+
+.EXAMPLE
+$logs = adb -s emulator-5554 logcat -d
+Format-LogcatOutput $logs
+#>
+function Format-LogcatOutput {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory = $false)]
+        [object[]]$LogcatOutput
+    )
+
+    if ($null -eq $LogcatOutput -or $LogcatOutput.Count -eq 0) {
+        return @()
+    }
+
+    # Ensure output is an array of strings
+    return @($LogcatOutput | ForEach-Object {
+        if ($null -ne $_) {
+            $_.ToString()
+        }
+    } | Where-Object { -not [string]::IsNullOrWhiteSpace($_) })
+}