[Mobile] Add BrowserStack Android MAUI Test

csharp/test/Microsoft.ML.OnnxRuntime.Tests.BrowserStack.Android/.config/dotnet-tools.json

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "browserstack-sdk": {
+      "version": "1.16.13",
+      "commands": [
+        "browserstack-sdk"
+      ],
+      "rollForward": false
+    }
+  }
+}

csharp/test/Microsoft.ML.OnnxRuntime.Tests.BrowserStack.Android/BrowserStackTest.cs

@@ -0,0 +1,82 @@
+using Newtonsoft.Json;
+using NUnit.Framework.Interfaces;
+using NUnit.Framework;
+using OpenQA.Selenium;
+using OpenQA.Selenium.Appium;
+using OpenQA.Selenium.Appium.Android;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace Microsoft.ML.OnnxRuntime.Tests.BrowserStack.Android
+{
+    public class BrowserStackTest
+    {
+        public AndroidDriver driver;
+        public BrowserStackTest()
+        {}
+
+        [SetUp]
+        public void Init()
+        {
+            var androidOptions = new AppiumOptions {
+                AutomationName = "UIAutomator2",
+                PlatformName = "Android",
+            };
+
+            driver = new AndroidDriver(new Uri("http://127.0.0.1:4723/wd/hub"), androidOptions);
+        }
+
+        /// <summary>
+        /// Sends a log to BrowserStack that is visible in the text logs and labeled as ANNOTATION.
+        /// </summary>
+        /// <param name="text">Log text to send.</param>
+        /// <param name="logLevel">Log level -- choose between info, debug, warning, and error</param>
+        public void browserStackLog(String text, String logLevel = "info")
+        {
+            String jsonToSend = String.Format(
+                "browserstack_executor: {\"action\": \"annotate\", \"arguments\": {\"data\": {0}, \"level\": {1}}}",
+                JsonConvert.ToString(text), JsonConvert.ToString(logLevel));
+
+            ((IJavaScriptExecutor)driver).ExecuteScript(jsonToSend);
+        }
+
+        /// <summary>
+        /// Passes the correct test status to BrowserStack and ensures the driver quits.
+        /// </summary>
+        [TearDown]
+        public void Dispose()
+        {
+            try
+            {
+                // According to
+                // https://www.browserstack.com/docs/app-automate/appium/set-up-tests/mark-tests-as-pass-fail
+                // BrowserStack doesn't know whether test assertions have passed or failed. Below handles
+                // passing the test status to BrowserStack along with any relevant information.
+                if (TestContext.CurrentContext.Result.Outcome.Status == TestStatus.Failed)
+                {
+                    String failureMessage = TestContext.CurrentContext.Result.Message;
+                    String jsonToSendFailure =
+                        String.Format("browserstack_executor: {\"action\": \"setSessionStatus\", \"arguments\": " +
+                                      "{\"status\":\"failed\", \"reason\": {0}}}",
+                                      JsonConvert.ToString(failureMessage));
+
+                    ((IJavaScriptExecutor)driver).ExecuteScript(jsonToSendFailure);
+                }
+                else
+                {
+                    ((IJavaScriptExecutor)driver)
+                        .ExecuteScript("browserstack_executor: {\"action\": \"setSessionStatus\", \"arguments\": " +
+                                       "{\"status\":\"passed\", \"reason\": \"\"}}");
+                }
+            }
+            finally
+            {
+                // will run even if exception is thrown by previous block
+                ((AndroidDriver)driver).Quit();
+            }
+        }
+    }
+}

csharp/test/Microsoft.ML.OnnxRuntime.Tests.BrowserStack.Android/Microsoft.ML.OnnxRuntime.Tests.BrowserStack.Android.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+	<PropertyGroup>
+		<TargetFramework>net8.0</TargetFramework>
+		<ImplicitUsings>enable</ImplicitUsings>
+		<Nullable>enable</Nullable>
+
+		<IsPackable>false</IsPackable>
+		<IsTestProject>true</IsTestProject>
+	</PropertyGroup>
+
+	<ItemGroup>
+		<PackageReference Include="Appium.WebDriver" Version="5.0.0-rc.5" />
+		<PackageReference Include="BrowserStack.TestAdapter" Version="0.13.13" />
+		<PackageReference Include="Microsoft.Extensions.Logging.Debug" Version="8.0.0" />
+		<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />
+		<PackageReference Include="NUnit" Version="3.13.0" />
+		<PackageReference Include="NUnit.Analyzers" Version="3.3.0" />
+		<PackageReference Include="NUnit3TestAdapter" Version="4.3.0" />
+	</ItemGroup>
+
+</Project>

csharp/test/Microsoft.ML.OnnxRuntime.Tests.BrowserStack.Android/README.md

@@ -0,0 +1,48 @@
+# BrowserStack Android test
+This project will run the Android MAUI tests on BrowserStack, which allows you to run automated tests on a variety of mobile devices.
+
+## Context
+Microsoft.ML.OnnxRuntime.Tests.MAUI uses DeviceRunners.VisualRunners to allow running the unit tests (found in Microsoft.ML.OnnxRuntime.Tests.Common) across multiple devices. DeviceRunners.VisualRunners provides a simple UI with a button that will run the unit tests and a panel with the unit test results. 
+
+In order to automate the process of running the unit tests across mobile devices, Appium is used for UI testing orchestration (it provides a way to interact with the UI), and BrowserStack automatically runs these Appium tests across different mobile devices.
+
+This project does not include the capability to start an Appium server locally or attach to a local emulator or device. 
+
+## Build & run instructions
+### Requirements
+* A BrowserStack account with access to App Automate
+    * You can set BrowserStack credentials as environment variables as shown [here](https://www.browserstack.com/docs/app-automate/appium/getting-started/c-sharp/nunit/integrate-your-tests#CLI)
+* ONNXRuntime NuGet package
+    1. You can either download the [stable NuGet package](https://www.nuget.org/packages/Microsoft.ML.OnnxRuntime) then follow the instructions from [NativeLibraryInclude.props file](../Microsoft.ML.OnnxRuntime.Tests.Common/NativeLibraryInclude.props) to use the downloaded .nupkg file
+    2. Or follow the [build instructions](https://onnxruntime.ai/docs/build/android.html) to build the Android package locally
+* The dotnet workloads for maui and maui-android, which will not always automatically install correctly
+    1. `dotnet workload install maui`
+    2. `dotnet workload install maui-android`
+* [Appium](https://appium.io/docs/en/latest/quickstart/) and the [UiAutomator2 driver](https://appium.io/docs/en/latest/quickstart/uiauto2-driver/)
+
+### Run instructions
+1. Build the Microsoft.ML.OnnxRuntime.Tests.MAUI project into a signed APK.
+    1. Run the following: `dotnet publish -c Release -f net8.0-android` in the Microsoft.ML.OnnxRuntime.Tests.MAUI directory.
+    2. Search for the APK files generated. They should be located in `bin\Release\net8.0-android\publish`. 
+    3. If they're in a different location, edit the `browserstack.yml` file to target the path to the signed APK.
+2. Ensure you've set the BrowserStack credentials as environment variables.
+3. Run the following in the Microsoft.ML.OnnxRuntime.Tests.Android.BrowserStack directory: `dotnet test`
+4. Navigate to the [BrowserStack App Automate dashboard](https://app-automate.browserstack.com/dashboard/v2/builds) to see your test running!
+
+## Troubleshooting & Resources
+### BrowserStack Resources
+- [Configuration docs](https://www.browserstack.com/docs/app-automate/appium/sdk-params#test-context) for browserstack.yml
+- [Configuration generator](https://www.browserstack.com/docs/app-automate/capabilities) for browserstack.yml
+- [Integration guide](https://www.browserstack.com/docs/app-automate/appium/getting-started/c-sharp/nunit/integrate-your-tests#CLI)
+
+### Troubleshooting
+- Issues building the MAUI app: 
+    - Make sure that the maui and maui-android workloads are installed correctly by running `dotnet workload list`
+    - If you believe the issues are workload related, you can also try running `dotnet workload repair` (this has personally never worked for me)
+    - Try running `dotnet clean`. However, this does not fully remove all the previous intermediaries. If you're still running into the errors, manually deleting the bin and obj folders can sometimes resolve them. 
+- After building the MAUI app, try installing on an emulator and clicking the "Run All" button to ensure that everything is working. (If you are missing the ONNXRuntime package, it will not show up as an error until you click "Run All".)
+    - Running the MAUI app from Visual Studio will not replicate running it through BrowserStack. Instead, use `adb install [path to signed apk]` to install the app then use the emulator to launch the app.
+- Issues with the Android.BrowserStack test app: there is an Appium Doctor package on npm -- run `npm install @appium/doctor --location=global` then `appium-doctor --android` and follow the directed instructions. Some errors with Appium on Android will not appear until runtime.
+- Connection refused by Appium server: this can happen if you already have an Appium server running locally. If you do, stop the Appium server then try `dotnet test` again.
+- App is crashing on BrowserStack or it emits an error that it cannot run this APK file: make sure that you are passing in the correct signed APK from the publish folder. 
+- It appears that a test runs on CLI but a build is not launched on BrowserStack: this happens when the BrowserStack Test Adapter cannot find the browserstack.yml file (which has to be named "browserstack.yml" -- do not be tricked by BrowserStack's article on custom-named configuration files)

csharp/test/Microsoft.ML.OnnxRuntime.Tests.BrowserStack.Android/RunAllTest.cs

@@ -0,0 +1,124 @@
+using OpenQA.Selenium.Appium;
+using OpenQA.Selenium;
+using NUnit.Framework;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace Microsoft.ML.OnnxRuntime.Tests.BrowserStack.Android
+{
+    /// <summary>
+    /// This class contains a single test: RunAll, which interacts with the UI from
+    /// https://github.com/mattleibow/DeviceRunners/tree/main by clicking the "Run All" button and checking the number
+    /// of passed and failed tests.
+    ///
+    /// It searches for elements on the page using Appium's WebDriver. These searches use the XPath attributes.
+    ///
+    /// Launching the MAUI test app in Appium Inspector will allow you to see the exact XPath attributes for each
+    /// element.
+    /// </summary>
+    [TestFixture]
+    public class RunAllTest : BrowserStackTest
+    {
+        public AppiumElement FindAppiumElement(String xpathQuery, String text)
+        {
+            IReadOnlyCollection<AppiumElement> appiumElements = driver.FindElements(By.XPath(xpathQuery));
+
+            foreach (var element in appiumElements)
+            {
+                if (element.Text.Contains(text))
+                {
+                    return element;
+                }
+            }
+            // was unable to find given element
+            throw new Exception(String.Format("Could not find {0}: {1} on the page.", xpathQuery, text));
+        }
+
+        public AppiumElement FindAppiumElementThenClick(String xpathQuery, String text)
+        {
+            AppiumElement appiumElement = FindAppiumElement(xpathQuery, text);
+            appiumElement.Click();
+            return appiumElement;
+        }
+
+        public (int, int) GetPassFailCount()
+        {
+            int numPassed = -1;
+            int numFailed = -1;
+
+            IReadOnlyCollection<AppiumElement> labelElements =
+                driver.FindElements(By.XPath("//android.widget.TextView"));
+
+            for (int i = 0; i < labelElements.Count; i++)
+            {
+                AppiumElement element = labelElements.ElementAt(i);
+
+                if (element.Text.Equals("✔"))
+                {
+                    i++;
+                    numPassed = int.Parse(labelElements.ElementAt(i).Text);
+                }
+
+                if (element.Text.Equals("⛔"))
+                {
+                    i++;
+                    numFailed = int.Parse(labelElements.ElementAt(i).Text);
+                    break;
+                }
+            }
+
+            Assert.That(numPassed, Is.GreaterThanOrEqualTo(0), "Could not find number passed label.");
+            Assert.That(numFailed, Is.GreaterThanOrEqualTo(0), "Could not find number failed label.");
+
+            return (numPassed, numFailed);
+        }
+
+        [Test]
+        public async Task ClickRunAllTest()
+        {
+            // XAML for the main page:
+            // https://github.com/mattleibow/DeviceRunners/blob/main/src/DeviceRunners.VisualRunners.Maui/App/Pages/HomePage.xaml
+            AppiumElement runAllButton = FindAppiumElementThenClick("//android.widget.Button", "Run All");
+
+            while (!runAllButton.Enabled)
+            {
+                // waiting for unit tests to execute
+                await Task.Delay(500);
+            }
+
+            var (numPassed, numFailed) = GetPassFailCount();
+
+            if (numFailed == 0)
+            {
+                Assert.Pass();
+                return;
+            }
+
+            // click into test results if tests have failed
+            FindAppiumElementThenClick("//android.widget.TextView", "⛔");
+            await Task.Delay(500);
+
+            // Brings you to the test assembly page
+            // XAML for test assembly page:
+            // https://github.com/mattleibow/DeviceRunners/blob/cba7644e07b305ba64dc930b01c3eee55ef2b93d/src/DeviceRunners.VisualRunners.Maui/App/Pages/TestAssemblyPage.xaml
+            FindAppiumElementThenClick("//android.widget.EditText", "All");
+            await Task.Delay(100);
+            FindAppiumElementThenClick("//android.widget.TextView", "Failed");
+            await Task.Delay(500);
+
+            StringBuilder sb = new StringBuilder();
+            sb.AppendLine("PASSED TESTS: " + numPassed + " | FAILED TESTS: " + numFailed);
+
+            IReadOnlyCollection<AppiumElement> textResults = driver.FindElements(By.XPath("//android.widget.TextView"));
+            foreach (var element in textResults)
+            {
+                sb.AppendLine(element.Text);
+            }
+
+            Assert.That(numFailed, Is.EqualTo(0), sb.ToString());
+        }
+    }
+}

csharp/test/Microsoft.ML.OnnxRuntime.Tests.BrowserStack.Android/browserstack.yml

@@ -0,0 +1,13 @@
+app: ..\Microsoft.ML.OnnxRuntime.Tests.MAUI\bin\Release\net8.0-android\publish\ORT.CSharp.Tests.MAUI-Signed.apk
+platforms:
+  - platformName: android
+    deviceName: Samsung Galaxy S22 Ultra
+    platformVersion: 12.0
+browserstackLocal: true
+buildName: ORT android test
+buildIdentifier: ${BUILD_NUMBER}
+projectName: ORT-UITests
+debug: true
+networkLogs: false
+testContextOptions:
+    skipSessionStatus: true