This guide will discuss how to setup a solution with Xamarin.UITests.

Overview

Visual Studio for Mac and Visual Studio both have templates for creating a new solution that includes a UITest project. However, it may be desirable to add a Xamarin.UITest project to an existing solution. This guide will discuss how to add Xamarin.UITest to an existing solution.

If you are using Xamarin.Forms, please see the guide Automate Xamarin.Forms testing with Xamarin.UITest and Test Cloud for more details on how to add a UITest project to your solution file.

Adding a UITest project to an existing solution is very similar to adding a C# class library project. The Xamarin templates for a UITest project will ensure that you get the necessary packages from NuGet (NUnit and the Xamarin Test Cloud Agent). However there are some manual steps that must be performed:

• Associate the Mobile Projects with the UITest Project – This will allow the IDE to run the tests and report the results to the developer.

• Initialize the Test Cloud Agent – An iOS application must bootstrap the Xamarin Test Cloud Agent (this is only necessary for iOS projects) so that it is running in Debug builds of the application but not present in Release builds submitted to the App Store.

Requirements

Xamarin Test Cloud and Xamarin.UITest only support Android and iOS applications. The Windows Phone and Windows versions of Xamarin.Forms apps cannot be tested in Test Cloud.

It is important to understand the concepts described in the Introduction to Xamarin Test Cloud guide.

It is assumed that the most recent stable version of the Xamarin.UITest NuGet Package is installed in the UITest project. It is assume that iOS projects have the most recent version of the Xamarin Test Cloud Agent installed.

iOS devices must be configured with a valid development provisioning profile.

In order to run Xamarin.UITests with Visual Studio for Mac, the following dependencies must be met:

• NUnit 2.6.x – Xamarin.UITest is not compatible with NUnit 3.x.
• Android SDK – Only if testing Android apps.
• Java Developers Kit – Only if testing Android apps.
• Xcode Command Line Tools – Only for testing iOS apps.

In order to run Xamarin.UITests with Visual Studio, the following dependencies must be met:

• NUnit 2.6.x – Xamarin.UITest is not compatible with NUnit 3.x.
• A Test Runner for Visual Studio – A 3rd party test runner, such as the NUnit Test Adapter for NUnit 2 or Resharper from Jetbrains, is required for Visual Studio to be able to run the NUnit tests. The NUnit3TestAdapter is not compatible with Xamarin.UITest.
• Android SDK – Only if testing Android apps. Windows requires that the ANDROID_HOME environment variable is set with the path to the Android SDK.
• Java Developers Kit – Only if testing Android apps.

⚠️

It is not possible to run UITests for iOS apps on Windows.

Adding a UITest Project to a Solution

The first step is to add a new project to the solution. Open up the solution in Visual Studio for Mac, right click on the solution in the solution pad, and select Add > New Project. From the left hand menu in the New Project dialog, select the Tests template that corresponds to your project type (Cross-platform, iOS, or Android):

Click Next and give the new project a name. The template will create a new project that includes the NUnit and Xamarin.UITest libraries from NuGet:

The first step is to add a new project to the solution. Start Visual Studio and open the solution. Right click on the solution in Solution Explorer and select Add > New Project. From the New Project dialog that appears, select Visual C# > Test in the left hand tree view. This will display the all of the testing templates in the middle panel. Select the UI Test App that is appropriate for your solution:

Give the project a name and click the OK button. The template will create a new project that includes the NUnit, NUnit Visual Studio Test Adapter, and Xamarin.UITest libraries from NuGet:

⚠️

If necessary, update the packages from NuGet. However, be careful not to update NUnit to 3.0. Xamarin.UITest is not compatible with NUnit 3.0.

Associate the Mobile App Projects with the UITest Project

The next step is to establish the association between the UITest project and the mobile apps. This will allow Visual Studio for Mac to run the UITests locally and and display the test results in the Unit Tests pad. First select View > Pads > Unit Tests and expand the Unit Tests pad until Test Apps is visible:

Right click on Test Apps and then select Add App Project from the menu. Then choose the mobile projects that the UITests will run against:

Click Ok, and you will see that the Test Apps have been added to the Unit Tests pad. If the solution contains a Xamarin.iOS project, the final step is to initialize the Xamarin Test Cloud Agent, described below.

The next step is to establish the association between the UITest project and the mobile apps. Right click on the References folder in the UITest project and select Add References... from the context menu. Select the mobile app projects from the Reference Manager dialog that appears:

Click Ok and observe that the UITest project now has references to the mobile app projects.

Adding the Xamarin Test Cloud Agent to the iOS Project

The Xamarin Test Cloud Agent is an special embedded HTTP server that allows UITests to interact with the iOS user interface. The Test Cloud Agent is added to the iOS project via NuGet.

In Visual Studio for Mac, right click on the Packages folder of the iOS project, select Add Package, search for Xamarin Test Cloud Agent and select the package, and click Add Package:

ℹ While it is not possible to run UITests for iOS projects on Windows, it is possible to configure the UITest project.

In Visual Studio, right click on the iOS project, and select Manage NuGet Packages from the context menu. Search for Xamarin Test Cloud Agent in the NuGet Package Manager and click OK to install that package:

Initialize the Xamarin Test Cloud Agent

After adding the Xamarin Test Cloud Agent to the iOS project, it is necessary to initialize the Xamarin Test Cloud Agent when the iOS project starts up. Edit the AppDelegate class and add the following snippet to the FinishedLaunching method:

// Newer version of Visual Studio for Mac and Visual Studio provide the
// ENABLE_TEST_CLOUD compiler directive in the Debug configuration,
// but not the Release configuration.
#if ENABLE_TEST_CLOUD
Xamarin.Calabash.Start();
#endif

The Xamarin Test Cloud Agent must not be present in a release build of a Xamarin.iOS application; its presence is grounds for the app to be rejected by Apple. By surrounding the initialization code in a conditional compile statement, the Xamarin linker will strip the Xamarin Test Cloud Agent from Release builds, but not Debug builds.

Summary

This guide covered how to add a Xamarin.UITest project to an existing solution. It discussed how to use the project template to create the UITest project, how to add an association from the UITest project to the mobile apps that are to be tested, and how to add the Xamarin Test Cloud Agent to iOS projects.