Running Xamarin UITests Locally

UITests are similar to Unit Tests, but instead of testing code, they are testing the UI. They load up the Mobile application, and then perform actions like a user, and can read the status of UI elements. Xamarin.UITest, along with NUnit, allow you to write these tests in C#.

You can run these tests locally on a simulator, or local device, or, you can run them on Xamarin Test Cloud. Xamarin Test Cloud, can be thought of, as a cloud of physical mobile devices. You upload your native mobile package and your UITests. These will then run on how ever many devices you select, and run the results. Currently, this only supports Android and iOS. For this post, I will just be focusing on how to run them locally.

Setup Your Project

In your Xamarin Forms application, you only need to do one thing to get ready for UI Tests, and that is to set the AutomationId on all elements that will require some kind of interaction. e.g.

<StackLayout Padding="20">
    <Label Text="Hello, this the main page" AutomationId="HelloLabel" />
    <Button Text="About Page" Command="{Binding AboutCommand}" AutomationId="AboutButton" />
    <Button Text="Logout" Command="{Binding LogoutCommand}" AutomationId="LogoutButton" />

This will allow you to find the element and read, or interact with it, in the UITest.

Build Native Binary

If you want to test this on any device or emulator, you will need to package this first. In this post, I will be using an Android app as an example.

First make sure you have the INTERNET (android.permission.INTERNET) permission set, and you are building in Release mode, for Any CPU, or your specific CPU Architecture you will be testing on. Then Archive the project. (Right Click Project > Archive). Then Open Folder and record the location of the APK, we need this later.

Create UITest Project

First, create a new UITest Project.

It’s also worth noting, that you must run the iOS UITest on a Mac, but you can run the Android UITests on either.

Setup UITest

The project will automatically create an AppInitializer.cs and Tests.cs. The AppInitializer, sets up the App, depending upon what type is running. If you are running it locally on your emulator, this is where you place the location of your APK.

public class AppInitializer
    public static IApp StartApp(Platform platform)
        if (platform == Platform.Android)
            return ConfigureApp
                   .ApkFile(@"C:\Users\Adam\AppData\Local\Xamarin\Mono for Android\Archives\2017-05-21\Sample.Droid 5-21-17 5.34 PM.apkarchive\com.Sample.apk")

       return ConfigureApp

The Tests.cs file, will contain basic setup and a simple test that ensures the app launches, and it will take a screenshot.

In the Test Explorer, press Run All. Or Test > Run > All Tests. This will launch the simulator, install the APK, then start running through the tests.

If you are on Windows, you might want to comment out [TestFixture(Platform.iOS)] to ensure it doesn’t try to run for iOS, which will just fail.

Basic Tests

To showcase some basic functionality, I will go with reading a Label, and tapping on a button. To read the text of a Label, you first have to find the element, with Query, then read the Text property. Query returns a list of elements that match the string.

public void LabelText()
    Assert.AreEqual("Hello, this the main page", app.Query("HelloLabel")[0].Text);

Now, we can use the Tap function to press a Button, and move it to the next page. To test we have moved to another page, we can either test for a new element only on the new page, or that a previous element, no longer exists.

public void MoveToAboutPage()

    // Check label not longer on screen
    Assert.AreEqual(0, app.Query("HelloLabel").Length);


  1. Prabakaran R

    Is there any built-in support to compare the current image with expected (base) image when I run the tests each time? Or do we need to write the code to compare the image with base image after taking the screenshot?

    1. Adam Pedley

      You will need to take a screenshot, then compare this image yourself to any future screenshot. You can just Google about how to compare images in C#.

      Please be careful with this though, as mobile device times, screen resolutions and other factors could lead to the images not matching.