Preparing Xamarin.iOS Apps

Important

Visual Studio App Center is scheduled for retirement on March 31, 2025. While you can continue to use Visual Studio App Center until it is fully retired, there are several recommended alternatives that you may consider migrating to.

Learn more about support timelines and alternatives.

This guide provides instructions for preparing Xamarin.UITests for upload to App Center Test. Select your platform to begin.

Xamarin.iOS apps must have the Xamarin Test Cloud Agent linked into the app's .ipa file. The Xamarin Test Cloud Agent is a special, embedded HTTP server that allows Xamarin.UITests to interact with the iOS user interface. The Test Cloud Agent is added to the iOS project via NuGet.

Tip

Non-Xamarin iOS apps are also supported by Xamarin.UITest, but instead of the Xamarin Test Cloud Agent require linking Calabash.

Visual Studio for Mac

For an iOS project in Visual Studio for Mac, right-click on the Packages folder, select Add Package. Search for Xamarin Test Cloud Agent, and click Add Package:

Visual Studio (Windows)

Important

Xamarin.UITests for iOS apps can't be executed locally on Windows. You can still create, compile and upload to App Center Test from Windows.

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

Initialize the Xamarin Test Cloud Agent

After adding the Xamarin Test Cloud Agent to the iOS project, you must initialize the Xamarin Test Cloud Agent when the iOS app starts. Edit the AppDelegate class and add the following snippet to the FinishedLaunching method:

#if ENABLE_TEST_CLOUD
Xamarin.Calabash.Start();
#endif

Warning

Apple will reject your app if you submit an app that includes the Xamarin Test Cloud Agent. The Xamarin Test Cloud Agent is only supported for apps signed with Development Provisioning Profiles. When submitted to App Center Test, IPAs are automatically re-signed with one of our Development Provisioning Profiles if possible.

When you surround the initialization code in the ENABLE_TEST_CLOUD conditional compile statement, the Xamarin linker will leave the Xamarin Test Cloud Agent in builds that use the ENABLE_TEST_CLOUD flag. Normally Debug builds but not Release builds. New Xamarin.iOS apps created in Visual Studio use this approach.

Generating an upload command

Once a test suite is prepared, you can setup a test run to upload and run your tests. That process will generate a prototype command line like this:

appcenter test run uitest --app "MyOrg/MyApp" --devices "MyOrg/MyDeviceSet" --app-path pathToFile.ipa --test-series "main" --locale "en_US" --build-dir pathToUITestBuildDir

The command line requires some modifications:

1. You must provide paths for the arguments --app-path & --build-dir.
2. You may need to specify the UITest package you're using, if the CLI can't automatically find it: --uitest-tools-dir /Users/{your username}/.nuget/packages/xamarin.uitest/{UITest version}/tools