Using Uno.UITest

Uno.UITest is a framework to enable unified UI Testing of Uno Platform apps, using NUnit 3.x.

This library provides a set of APIs to interact with an app, and assess its behavior using device simulators and browsers. The API set is based on Xamarin.UITest, which makes the migration and patterns very familiar.

The testing is available through :

The following target platforms are not yet supported:

  • SkiaSharp backends (GTK, WPF and Tizen )
  • Xamarin.macOS
  • Windows

How to use Uno.UITest with an Uno Platform app

Tip

UI Testing setup is already integrate in Uno Platform 4.8 and later, see our getting started to create your Uno Platform app.

  • Make sure Chrome is installed

  • In Visual Studio for Windows, create an application using the Uno Platform templates

  • Add the following code to each .csproj files (iOS, Android and WebAssembly), at the end before the closing </project> tag:

      <PropertyGroup Condition="'$(Configuration)'=='Debug' or '$(IsUiAutomationMappingEnabled)'=='True'">
  	<IsUiAutomationMappingEnabled>True</IsUiAutomationMappingEnabled>
  	<DefineConstants>$(DefineConstants);USE_UITESTS</DefineConstants>
  </PropertyGroup>

  • In the iOS project, add a reference to the Xamarin.TestCloud.Agent nuget package (0.21.8 or later)

  • In the OnLaunched method of App.xaml.cs, add the following at the beginning:

      #if __IOS__ && USE_UITESTS
  	// Launches Xamarin Test Cloud Agent
  	Xamarin.Calabash.Start();
  #endif

  • Install the Uno Platform dotnet new templates:

      dotnet new -i Uno.ProjectTemplates.Dotnet

  • Navigate to your .sln folder using a command line:

    • Create a folder named YourAppName\YourAppName.UITests
    • Then run :
    cd YourAppName.UITests
  dotnet new unoapp-uitest

    The new project will be added automatically to your solution. If you get "No templates found matching: 'unoapp-uitest'." error, please see dotnet new templates for Uno Platform article.

  • In the new UI Tests project, edit the Constants.cs file with values that match your project

  • In your application, add the following XAML:

      <StackPanel>
  	<CheckBox AutomationProperties.AutomationId="cb1" AutomationProperties.AccessibilityView="Raw" Content="Test 1"/>
  </StackPanel>

    Note that AutomationProperties.AccessibilityView="Raw" is only required for ContentControl based controls to allow for cb1 to be selectable instead of the text Test 1.

  • Then following test can be written:

      using NUnit.Framework;
  using Uno.UITest.Helpers.Queries;
  using System.Linq;
  // Alias to simplify the creation of element queries
  using Query = System.Func<Uno.UITest.IAppQuery, Uno.UITest.IAppQuery>;

  public class CheckBox_Tests : TestBase
  {
  	[Test]
  	public void CheckBox01()
  	{
  		Query checkBoxSelector = q => q.Marked("cb1");
  		App.WaitForElement(checkBoxSelector);

  		Query cb1 = q => q.Marked("cb1");
  		App.WaitForElement(cb1);

  		var value1 = App.Query(q => cb1(q).GetDependencyPropertyValue("IsChecked").Value<bool>()).First();
  		Assert.IsFalse(value1);

  		App.Tap(cb1);

  		var value2 = App.Query(q => cb1(q).GetDependencyPropertyValue("IsChecked").Value<bool>()).First();
  		Assert.IsTrue(value2);
  	}
  }

This sample is provided through the Sample.UITests project in this repository.

Running the tests for WebAssembly

  • To test in Chrome, first deploy the WebAssemly app using Ctrl+F5, take note of the Url of the app
  • Update the Constants.WebAssemblyDefaultUri property in Constants.cs
  • Change the Constants.CurrentPlatform to Platform.Browser
  • Launch a test by right clicking on the test in the Test Explorer, or in the test code itself.
  • A Chrome browser window will open in automated mode, and the test will execute.

Running the tests for Android

  • Build and deploy the app on a simulator
  • Update the Constants.AndroidAppName property in Constants.cs to the value set in your app manifest
  • Change the Constants.CurrentPlatform to Platform.Android
  • Launch a test by right clicking on the test in the Test Explorer, or in the test code itself.
  • The application will start on the emulator, and the test will execute

Running the tests for iOS

testing for iOS is only available through Visual Studio for Mac, where the simulators can run.

  • Open your solution in Visual Studio for mac
  • Build and deploy the app on an iOS simulator
  • Update the Constants.iOSAppName property in Constants.cs to the value specified in your info.plist file
  • Change the Constants.CurrentPlatform to Platform.iOS
  • Launch a test
  • The application will start on the emulator, and the test will execute

This sample is provided through the Sample.UITests project in this repository.

Validating the currently running environment

if(AppInitializer.GetLocalPlatform() == Platform.Android)
{
    Assert.Ignore();
}

UI Testing in a CI environment

One of the design goal of the Uno.UITest library is to enable UI Testing in Pull Request builds, so that the UI testing is not an afterthought, and is part of the development flow.

You can find some scripts examples to enable such testing, using Azure Devops hosted agents: