Skip to content

This is our first blog of the Xamarin.UITest 101 blog series. Xamarin.UITest is a de facto automated app testing framework for Xamarin.Forms mobile projects. It tightly integrates with and shares the same test code with Xamarin.Forms. In this blog, we’ll walk you through the following steps.

  • Setting up a Xamarin environment
  • Creating a Xamarin.Forms mobile project
  • Creating and launching an emulator
  • Creating a Xamarin.UITest project
  • Writing and running a sample Xamarin.UITest test

Setting Up Xamarin Environment for UITest App Testing

As it’s suggested and documented, it’s best to get started with Xamarin.UITest when you are developing a Xamarin.Forms mobile app. So let’s start with the Xamarin.Forms development framework to create a cross-platform Xamarin app.

Since we are using a Windows machine, we would need to download and install Visual Studio 2019 in the first place. (If you have demanding needs in app quality and scale, you’re suggested to download the Enterprise version as in our case.)

While installing the Visual Studio Enterprise 2019, don’t forget to choose the Mobile development with .NET item.

mobile development with .NET using Xamarin

Next, select all the following necessary individual components, including

  • Xamarin
  • Xamarin Inspector
  • Xamarin Profiler
  • Xamarin Remoted Simulator
  • and Xamarin Workbooks.

Also if you want to run apps on emulators, you should also install Google Android Emulator (API Level 25) and Intel Hardware Accelerated Execution Manager (HAXM).

installing visual studio

Creating a simple Xamarin.Forms app

When you create a cross-platform app with Xamarin.Forms in Visual Studio 2019, you may use a project template that is called Mobile App (Xamarin.Forms).

  • Open VS 2019 and click File -> New -> Project to create the first Xamarin project. (To find the project template quickly, filter all the templates by the “Mobile App” word.
  • Next, we select the Mobile App (Xamarin.Forms) type.
  • Give it a name – ATXamarin.

configure a new xamarin project

Once this is done, let’s choose a project template and configure it. Here we have 4 templates in our sample Xamarin.Forms project:

  • Blank App: a blank template that creates a project with minimum functionality;
  • Tabbed App: an app project that uses tabs for navigation over the website;
  • Shell: a template of a single-page app;
  • Master Detail: a project specifically for the cases involving the availability of both functionalities: one for providing the list of objects, and another one for data output upon each item from the list.

selecting a template to create a xamarin.forms app

In this case, we will choose Master Detail as a project template for the quick creation of the cross-platform Xamarin.Forms app.

Now, Visual Studio 2019 will generate a new solution. If you choose all the platforms, then the newly created solution will have three projects:

  • ATXamarin: the main project of the library that will contain all the main app logic;
  • ATXamarin.Android: a project for Android;
  • ATXamarin.iOS: a project for iOS.

three projects created for different platform

Here, we’ll take ATXamarin.Android as an example. To launch this new app, you have to set up the Android SDK.

  • Select ATXamarin.Android -> the Android SDK icon.
  • Confirm to install the Android SDK Platform.
  • Install the Android SDK Tool.

downloading and installing android sdk

Once the Android SDK tool is installed, you have to set the paths in the Environment Variables section.

  • From your Windows Control Panel, click on the Advanced system settings -> Environment Variables… -> Variable name
  • When the installation is completed, Android SDK will be available on this path – C:\Program Files (x86)\Android\android-sdk\

set paths for environment variables-3

Creating and Launching an Emulator

So far we’ve finished setting up the Xamarin environment and creating a simple Xamarin.Forms app for Xamarin.UITest testing. After the SDK setup is completed, let’s create a device where the test app will be launched.

  • In the Android Device Manager, click on the + New to create a new emulator
  • Select a target emulator, for example, Pixel 2 Pie 9.0 – API 28
  • Check the attributes upon selecting the target emulator
  • Accept the license agreement
  • Lastly, launch the new emulator by clicking on the Start button.

launch and start a device session

Now let’s check our test app installation on the created emulator.

app launched on the emulator

Creating a Xamarin.UITest project for app testing

Now that we’ve finished checking the performance of the emulator and test app, we will make one more project.

  • In Solution Explorer, right-click the project -> Add -> New Project
  • Select the Xamarin.UITest Cross-Platform Test Project

create a xamarin.uitest project for mobile app testing

This will add a new project for the Xamarin.UITest project for automated app testing and we will get the following structure:

structure of the xamarin.uitest project

Configuring the Xamarin.UITest Test Code

The new project has two classes in it. AppInitializer contains code to help in test running, platform, and what the app exactly needs to be used. By default, it looks like below

using System;
using Xamarin.UITest;
using Xamarin.UITest.Queries;

namespace FirstUITest
  public class AppInitializer
    public static IApp StartApp(Platform platform)
      if (platform == Platform.Android)
        return ConfigureApp.Android.StartApp();

      return ConfigureApp.iOS.StartApp();

To ensure our Xamarin.Forms app is installed on the emulator when we automate the Xamarin.UITest tests, we have to change the line:

return ConfigureApp.Android.StartApp();


return ConfigureApp.Android.InstalledApp("com.companyname.atxamarin").StartApp();

The “com.companyname.atxamarin”  is the package name which we can get from Android manifest.

  • Right-click on the Project -> Properties -> Android manifest at the left column

checking android project properties

Writing Xamarin.UITest Tests for Mobile App Testing

Tests are a test class where the app is installed.

public void BeforeEachTest()
  app = AppInitializer.StartApp(platform);

As well as a test scenario.

public void WelcomeTextIsDisplayed()


Now let’s add some actions to get started with Xamarin.Forms app testing using the Xamarin.UITest project.

public void WelcomeTextIsDisplayed()
  app.WaitForElement(c => c.Marked("Add"));
  app.Tap(c => c.Marked("Add"));
  app.WaitForElement(c => c.Marked("Cancel"));
  app.Tap(c => c.Marked("Cancel"));

Since we will run the test on Android, we need to comment out the following line:


Now, let’s look at our project one more time:

rebuild solution

We can see our created test in Test Explorer.

  • Move the mouse to the top menu and click on the Test -> Test Explorer

first xamarin.uitest test created in test explorer for app testing

Let’s run the test (during the test execution, the emulator should be running too).

run xamarin.uitest test on an emulator

During the running, we see that the test does the following:

  1. Clicks on the Add button and goes to the Add item page.
  2. Clicks on the Cancel button and goes to the main page.

xamarin.uitest sample app testing scenario


We have seen how to set up a Xamarin environment and create a Xamarin.Forms mobile project and emulator for execution. Also, we created a sample Xamarin.UITest project for mobile app testing and wrote a simple test scenario for running on the emulator.

In the next article, we will use different tools to accelerate the search for the locators for elements. And thus, we will complicate the scenario of our test. Stay tuned!

Petro Kiryshikin

Tech Writer