VISUAL STUDIO   Windows Mac

Xamarin.UITest and Xamarin.iOS Quickstart

PDF for offline use
Related APIs:
Related Links:

Let us know how you feel about this

Translation Quality


0/250

last updated: 2016-10

Overview

In this quick start we'll write a UITest for an iOS application then run the test locally and in Xamarin Test Cloud. The test will confirm that the application will display the correct error message when the user enters a credit card number that is too short. Conceptually, the test will be compromised of the following steps:

  1. Wait for the view controller to load – Typically a view controller is quick to load, but to be safe the test verify that the correct view controller has loaded.
  2. Enter 15 digits for the credit card number – The test must simulate data entry.
  3. Tap the Validate Credit Card button – Simulate what a user would do to call the validation logic.
  4. Confirm the Error Message – Finally, the test should assert the application has displayed the correct error message.

To save time, download the ZIP file that contains the sample application. This sample application does not contain any tests - these are added in the steps below. The sample already has a UITest project in the solution - the steps to do this manually are explained in the Adding Xamarin.UITest to a Solution guide.

You will not be able to run your UITests using Visual Studio. This guide will focus only on Xamarin Studio. View the Xamarin Studio guide.

Open the solution in Xamarin Studio. Notice that this solution contains the Xamarin.iOS project and the default UITest project from the Xamarin template for UITest projects. There are no tests in the UITest project, one will be added as we go through this Quickstart. If necessary, go ahead and update the Xamarin Test Cloud Agent NuGet and the Xamarin.UITest packages to the most recent versions.

Xamarin.UITest requires NUnit 2.6.x, so do not update NUnit to NUnit 3.0 or higher. Xamarin.UITest and Xamarin Studio are not compatible with NUnit 3.x.

Finally, run the Xamarin.iOS app to confirm that the application builds and runs in your development environment.

Creating the First Test

Edit the file Test.cs and add a stub for the first test, as shown in the following code snippet:

[Test]
public void CreditCardNumber_TooShort_DisplayErrorMessage()
{

}

Waiting for the Screen to Load

The view controller has a UINavigationBar with the ID Simple Credit Card Validator. We want to create a query that locate this UINavigationBar based on the text it is displaying. For this, we will use the following API's:

  1. IApp.WaitForElement – This will cause a test to pause until the specified query is satisified, i.e. returns some results. If the query is not satisified within the time limit, then an exception will be thrown.
  2. AppQuery.Class – This method will find any view whose class (or superclass) matches the provide string.
  3. AppQuery.Marked – On iOS, this method will find any view that matches the provide text by examining the accessibilityLabel, or accessibilityId property of the view.
  4. AppQuery.Text – The AppQuery.Text method can be used as filter to check a string displayed by a particular view.

Edit our test method so that it resembles the following snippet:

[Test]
public void CreditCardNumber_TooShort_DisplayErrorMessage()
{
    // Pause until the view controller has loaded
    app.WaitForElement(c=>c.Class("UINavigationBar").Marked("Simple Credit Card Validator"));
}

Enter the Credit Card Number

The IApp.EnterText method will simulate text entry into a given view. We will use this API along with a new UITest query to reference the Credit Card Number field.

Update the test method so that it resembles this snippet of code:

[Test]
public void CreditCardNumber_TooShort_DisplayErrorMessage()
{
    app.WaitForElement(c=>c.Class("UINavigationBar").Marked("Simple Credit Card Validator"));

    app.EnterText(c=>c.Class("UITextField"), new string('9', 15));

}

Our test will now wait for the view controller to load, and then enter a credit card number, just like a human user would do.

Tap the Button

Next we need to simulate the user tapping the Validate Credit Card button using IApp.Tap. Update the test method so that it resembles the following:

[Test]
public void CreditCardNumber_TooShort_DisplayErrorMessage()
{
    app.WaitForElement(c => c.Marked("action_bar_title").Text("Enter Credit Card Number"));
    app.EnterText(c => c.Marked("creditCardNumberText"), new string('9', 15));

    // Tap the button
    app.Tap(c=>c.Marked("Validate Credit Card").Class("UIButton"));
}

Verify the Error Message

The final step of the test is to verify that the correct error message is displayed to the user. We will use the IApp.WaitForElement method for this:

app.WaitForElement(c => c.Marked("Credit card number is too short.").Class("UILabel"));

Add this line to the test. The completed test should resemble the following:

[Test]
public void CreditCardNumber_TooShort_DisplayErrorMessage()
{
    app.WaitForElement(c=>c.Class("UINavigationBar").Marked("Simple Credit Card Validator"));
    app.EnterText(c=>c.Class("UITextField"), new string('9', 15));
    app.Tap(c=>c.Marked("Validate Credit Card").Class("UIButton"));

    app.WaitForElement(c => c.Marked("Credit card number is too short.").Class("UILabel"));
}

Run the Test

Now that the code for the test is complete, lets run the test in Xamarin Studio. You should the see the test automating the user interface and run to successful completion. Lets run the test in Xamarin Test Cloud:

  1. Make sure that the build configuration is set to Debug > iOS Device.

    Choose iOS device from the configuration list

  2. If necessary, display the Unit Tests pad by selecting View > Pads > Unit Tests.

  3. Right click on the CreditCardValidator.iOS.UITests project in the Unit Tests pad and selecting Run in Test Cloud.

    Choose Run in Test Cloud from the popup menu

Xamarin Studio will build your IPA, upload it and the tests to Xamarin Test Cloud. Use the web interface to specify the team, select the devices, and provide some meta-data on how the test will run. Please see the guide Submitting UITests to Xamarin Test Cloud for more details.

Summary

At this point you have finished this quick start. For practice, try to write a UITest for when a user enters a valid credit card number.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.