Xamarin Test Recorder

A tool for recording automated user interface tests.

PDF for offline use:
Related Articles:
Related Links:

Let us know how you feel about this.


0/250
Thanks for the feedback!

last updated: 2016-11

The Xamarin Test Recorder reduces the effort and the time it takes to create automated UI tests that can be submitted to Xamarin Test Cloud.

Overview

ℹ️

The Xamarin Test Recorder for Visual Studio is currently in a preview release state.

Mobile quality is important, but testing is expensive and time consuming. Creating automated UI tests is a laborious endeavour that requires manual interaction with a mobile application in order to capture and identify the user interactions for an app. The Xamarin Test Recorder is a stand alone application that will watch how a user interacts with an application, and create automated tests in C# based on those interactions.

To get started, download and run the installer on macOS. The application will be installed in the Applications folder.

The following screenshot shows the Xamarin Test Recorder and the four main areas of interest:

  1. The top tool has buttons to start test recording, stop recording, replay a recorded test, and export the recorded test so that it may be reused.
  2. Below the top toolbar, on the left hand side of the application, are the drop down lists to select the mobile application to test and the target device (or emulator/simulator) that the application will be run on.
  3. The left hand side of the screen will display the actions that have been captured by the Test Recorder. Depending on the action, each step may provide the ability to change the input for a given test.
  4. The right hand side of the application holds the C# code of the generated test method.

When recording tests for an iOS application, the Test Recorder will automatically inject a special library called the Test Recorder Plugin into the app bundle (Android apps do not need this library). The Test Recorder Plugin is extra code that allows the Test Recorder to observe the application that is being tested and generated the C# code for the various events.

⚠️

The presence of the Test Recorder Plugin in an IPA is grounds for the Apple App Store to reject the app bundle; do not submit any IPAs that were used by the Test Recorder to the App Store for distribution.

This guide will discuss how to use the Xamarin Test Recorder to create automated UI tests for Android and iOS applications, and how to submit those tests to Xamarin Test Cloud or include them in an existing UITest project.

The workflow for recording a test is the same for both Android and iOS applications:

  • If necessary, connect a device to the computer with the appropriate cable.
  • Start Test Recorder, specify the application to be tested, and select the device to run application on.
  • Interact with the application and the Test Recorder will create a C# test method.
  • Have the Test Recorder submit the test script to Xamarin Test Cloud, or incorporate the test into a Xamarin UITest project.
Xamarin Test Recorder for Visual Studio can be downloaded and installed from the Visual Studio Gallery - download the extension for either Visual Studio 2015 or Visual Studio 2013.

This is the workflow for recording a UITest for Android:

  • If necessary, connect a device to the computer with the appropriate cable.
  • Start Test Recorder, specify the application to be tested, and select the device to run application on.
  • Interact with the application and the Test Recorder will create a C# test method.
  • Incorporate the test into a Xamarin UITest project.
This screenshot and code snippet is an example of a test that was recorded using the Test Recorder:

[Test]
public void NewTest ()
{
    app.Tap(x => x.Class("EditText").Id("creditCardNumberText"));
    app.Screenshot("Tapped on view EditText with ID: 'creditCardNumberText'");
    app.EnterText(x => x.Class("EditText").Id("creditCardNumberText"), "123456789012345");
    app.Screenshot("Entered '123456789012345' into view EditText with ID: 'creditCardNumberText' with Text: '123456789012345'");
    app.Tap(x => x.Class("Button").Id("validateButton").Text("Validate Credit Card"));
    app.Screenshot("Tapped on view Button with ID: 'validateButton' with Text: 'Validate Credit Card'");
    app.Tap(x => x.Class("TextView").Id("errorMessagesText").Text("Credit card number is too short."));
    app.Screenshot("Tapped on view TextView with ID: 'errorMessagesText' with Text: 'Credit card number is too short.'");
}

Requirements

You must be familiar with Xamarin Test Cloud and Xamarin.UITest.

Xamarin Test Recorder will not work with an uncompiled solution or project. The Android APK or iOS App Bundle must already be packaged. Test Recorder can install the APK/App Bundle on the device if necessary.

You will need a Visual Studio Enterprise subscription to use Test Recorder for Visual Studio.

Android

For Android, the Xamarin Test Recorder supports recording on physical devices connected via a USB cable, or on Android emulators. Recording tests for an Android application requires:

  • Recording a test is only possible on Android 4.3 (API level 19) or higher. The tests may be played back on devices running older versions of Android.
  • Android SDK Build-tools
  • Android SDK Platform-tools
  • The APK has been granted the INTERNET permissions in the Android manifest.
  • The build does not use the Shared Mono Runtime setting in the Android project options.

iOS

Recording a test is only possible on devices running iOS 8 or higher.

An iOS device must be provisioned for application development and testing, as described in the iOS Device Provisioning guide.

Xamarin Test Recorder is unable to record iOS tests on Windows.

Recording a Test

To get started with recording connect a device or start the iOS simulator/Android emulator:

  1. If testing on a physical device, make sure that it is connected and unlocked.
  2. Select the device or emulator/simulator from the Device dropdown menu:

    The Test Recorder will start any selected Android Emulator or iOS simulator if necessary.

  3. Select the application to test from the App dropdown, as shown in this screenshot:

    The Test Recorder will connect to the device, install the application, and start it.

  4. Once the mobile app is installed and started, click on the Record button in the Test Recorder.

  5. Use the application and perform the specific steps you want to record. Test Recorder will capture the interactions and create a test. The individual interactions will be displayed in the left hand pane of the Test Recorder, and the corresponding C# code in the right hand pane.
  6. When you finish finish your testing interaction, press the Stop button to stop recording.

Stopping a Recording

To stop recording, click the Recorder Settings Icon in the margin to the left of your current recording, and click Stop Recording. This will end your recording session.

If you wish to start a new recording, you can do so by clicking the New Test icon at the top of your Test Fixture.

Adding Screenshots

To add Screenshots, click the blue Camera icon to the right of the step in the left pane of the recording.

Playback

Once the test has been recorded, it is possible to play the test back to verify that it has functioned correctly. Click on the Run button and the Test Recorder will start the application and run the test, highlighting each step as it is executed. It will notify you of which steps pass or fail:

Exporting the Recorded Test

Once you have finished recording your test, it can be exported to Test Cloud or added to an existing test suite. The Export button is available in the upper right hand corner of the Test Recorder user interface:

There are three possible actions for exporting a recorded test:

  • Copy Output – This action will copy your current test to the clipboard so that it may be added to an existing test fixture.
  • Export UITest – This will export the test to a .CS file which can then be added to an existing UITest project. An explaination of how to do this will be covered in the following section.
  • Send to Test Cloud – This packages your app and test together and uploads them to Test Cloud, and queues them for a run on the devices that you select. You must have a Xamarin Test Cloud account before you can upload the test. Once an upload is complete, Test Cloud will display the test results in your browser. Note that this option will not save the recorded test for you.

Exporting the Test to a C# File

After recording a UITest, it can be exported to a C# file and incorporated into an existing Xamarin.UITest project.

  1. After recording the test, click on the Export button in the upper right hand corner of Xamarin Test Recorder, and select Export UITest. Select the directory and the name of the file for the saved test:

  2. Next, open a Xamarin.UITest project in Xamarin Studio. Right click on the project, and select Add > New File... and add the file from the previous step.

  3. Open up the file new file in Xamarin Studio and examine the Setup method in the new test. Notice that Xamarin Test Recorder hard-coded the path to the AppBundle. it may look something like this:
[SetUp]
public void Setup()
{
    app = ConfigureApp.iOS
    .AppBundle("/var/folders/61/bhbtr4_51tx9bl3l5lqzl87m0000gn/T/test-recorder/ios-injection/linked-03-24-16-15-40-51-app.app")
    .StartApp();
}
The `.AppBundle` is not necessary for Xamarin Test Recorder, strictly speaking. It is recommended to remove this method call:
[SetUp]
public void Setup()
{
    app = ConfigureApp.iOS.StartApp();
}

Finally, rename the class and the test method so that the provide a better description of what is being tested.

Recording a Test

To get started with recording, connect an Android device or launch your Android Emulator, and open a UITest project in Visual Studio. If you do not have a UITest project set up for your app, read the introduction to UITest.

  1. Open one of your test files, and you should see the New Test Recording (a small lightning bolt) icon appear in your editor next to the [Test Fixture] attribute:

    Test Fixture with Recording Icon

  2. Clicking the icon will give you the option to Record New Test:

    Screenshot of New Test Menu

  3. Clicking Record a New Test will prompt you to choose the app for which you want to record tests. Navigate to the app in your project's bin folder, and select it.

    Screenshot of Choose App Window

    This will create an empty Test method in your editor, and launch your app in the connected emulator or device. Please wait until your app has fully launched, and Visual Studio has confirmed your connection before beginning to record.

  4. Once your app is fully connected, any interactions with your app will be recorded, converted to UITest, and added to your test method.

    Screenshot of code being added to a Test Method

Stopping a Recording

To stop recording, click the Recorder Settings Icon in the margin to the left of your current recording, and click Stop Recording. This will end your recording session.

Screenshot of App Settings Menu

If you wish to start a new recording, you can do so by clicking the New Test icon at the top of your Test Fixture.

Adding Screenshots

To add Screenshots, click the Recorder Settings Icon in the margin to the left of your current recording, and click Take Screenshot. This will insert a blank Screenshot step in the next line of your test method.

Adding Assertions/WaitFor Steps

To add a WaitForElement step, click the Recorder Settings icon in the margin to the left of your current recording and click Start Assertion Mode. This will activate Assertion Mode, and temporarily lock your app's UI until you select an element.

The next element you tap or click will be added to your test method as a WaitForElement step and unlock your UI so that you can resume testing.

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.