CLI Device Runner for Android using XHarness

Prerequisites

Before running any tests on the CLI, you will need the XHarness .NET tool. For more information as to what that is and what it does, see the Using XXarness wiki.

Running Tests

1. Build the app package for testing:

   dotnet publish <path/to/app.csproj> -r <runtime-identifier> -f net7.0-android -c Release
   

2. Run the tests:

   xharness android test --app <path/to/app.apk> --package-name <package-name> --instrumentation devicerunners.xharness.maui.XHarnessInstrumentation --output-directory <path/to/output>
   

3. View test results in the output path:

   <path/to/output>/TestResults.xml
   

To build and test the app at the path sample/SampleMauiApp/SampleMauiApp.csproj and get the test output at the path artifacts on my ARM64 Apple Silicon laptop:

dotnet publish sample/SampleMauiApp/SampleMauiApp.csproj \
  -r android-arm64 \
  -f net7.0-android \
  -c Release

xharness android test \
  --app sample/SampleMauiApp/bin/Release/net7.0-android/android-arm64/publish/com.companyname.samplemauiapp-Signed.apk \
  --package-name com.companyname.samplemauiapp \
  --instrumentation devicerunners.xharness.maui.XHarnessInstrumentation \
  --output-directory artifacts

# test result file will be artifacts/TestResults.xml

Managing Android Emulators

Because XHarness does not yet boot or create Android emulators, we will need to make use of another tool: AndroidSDK.Tool - a global dotnet tool for various android adb, avd, and emulator needs. See https://github.com/redth/AndroidSdk.Tools

dotnet tool install --global AndroidSDK.Tool

Once the tool is installed, you can create and boot an emulator:

1. Install the emulator image using the Android SDK:

   android sdk install --package "system-images;android-<android-api-level>;google_apis;<cpu-architecture>"
   

2. Create the emulator instance:

   android avd create --name <emulator-name> --sdk "system-images;android-<android-api-level>;google_apis;<cpu-architecture>" --device <device-type>
   

3. Boot the emulator:

   android avd start --name <emulator-name> --wait-boot
   

4. Run tests using Xharness. (See steps above)
5. Shutdown the emulator using XHarness:

   xharness android adb -- emu kill
   

To download, install, create and boot a Pixel 5 emulator running Android 14 (API Level 34) on my ARM64 Apple Silicon laptop:

android sdk install \
  --package "system-images;android-34;google_apis;arm64-v8a"

android avd create \
  --name TestRunnerEmulator \
  --sdk "system-images;android-34;google_apis;arm64-v8a" \
  --device pixel_5

android avd start \
  --name TestRunnerEmulator \
  --wait-boot

# run things on the emulator

xharness android adb -- emu kill

NOTES

• If you want to build a debug app and test that, you will also need to set EmbedAssembliesIntoApk to True:

  dotnet publish ... -p:EmbedAssembliesIntoApk=true