Skip to main content

Sharding for XCUI

Generally the XCUI tests are run in sequence which is a time taking process. This document explains how you can speed up this process by splitting the tests into shards. We can divide the various tests into shards which can run parallelly and save time while running various XCUI tests.

This document will cover how to execute XCUI Tests on real devices with HyperExecute. HyperExecute is a smart test orchestration platform to run end-to-end tests at the fastest speed possible. HyperExecute is configured using a YAML file.

Note

You can learn more about the HyperExecute portal and UI by going through our Guided Walkthrough page. It contains all the relevant information that you need to optimise your testing process with HyperExecute.

Objectives


By the end of this topic, you will be able to:

  1. Speed up your XCUI tests with sharding
  2. Learn more about HyperExecute
  3. Explore advanced features of LambdaTest

Pre-requisites


Before you start performing your App automation testing with XCUI, please make sure:

  • You have access to LambdaTest username and accessKey. If you have not registered yet, you can do the same by visiting our website. You will be able to access the credentials at the LambdaTest Profile
  • Make sure you have App Automation and HyperExecute Cloud plans on your account.

Uploading your App & Test suite

Step 1: Upload Your Application

Upload your iOS application (.ipa file) to the LambdaTest servers using our REST API. You need to provide your Username and AccessKey in the format Username:AccessKey in the cURL command for authentication. Make sure to add the path of the appFile in the cURL request.

Here is an example cURL request to upload your app using our REST API:

Using App File:

curl -u "undefined:undefined" \
--location --request POST 'https://manual-api.lambdatest.com/app/uploadFramework' \
--form 'appFile=@"/Users/macuser/Downloads/proverbial.ipa"' \
--form 'type="xcuit-ios"'
note

Response of above cURL will be a JSON object containing the App URL of the format - APP123456789123456789 and will be used in the last step as appId.

Step 2: Uploading Test Suite

Upload your test suite (.ipa file) to the LambdaTest servers using our REST API. You need to provide your Username and AccessKey in the format Username:AccessKey in the cURL command for authentication. Make sure to add the path of the appFile in the cURL request. Here is an example cURL request to upload your app using our REST API:

Using App File:

curl -u "undefined:undefined" \
--location --request POST 'https://manual-api.lambdatest.com/app/uploadFramework' --form 'appFile=@"/Users/macuser/Downloads/proverbial_ios_xcuitest.ipa"' --form 'type="xcuit-ios"'
note

Response of above cURL will be a JSON object containing the App URL of the format - APP123456789123456789 and will be used in the next step as testSuiteAppId

How to use Sharding


  1. Firstly, create a folder on your local.
  2. Download the HyperExecute CLI file and put it under this folder. You may download HyperExecute CLI from either of the following ways:
  • Download it from our HyperExecute documentation page here, or
  • "Get Started" through HyperExecute onboarding and download the CLI.
  1. Refer to the sample .ipa files and .yaml file given below. Put all of them under this folder.

Refer to the sample .yaml file here

SampleYamlFile.yaml
version: "0.2"
concurrency: 2
runson: ios
autosplit: true
maxRetries: 2
retryOnFailure: true
globalTimeout: 180 #MAXQUEUETIMEOUT

framework:
name: "ios/xcui"
args:
buildName: "XCUIT"
video: true
networkLog: true
deviceLog: true

# You can use either the appId (APP1234567) or provide the path of the application using appPath.

appPath: LambdaUiKitIOS.ipa
# We have used the appPath here instead of appId

# You can use either the APP ID (APP1234567) or provide the path of the application.

testSuiteAppId: lt://APP10160202521675167637685231
# We have used the testSuiteAppID here instead of testSuitePath

deviceSelectionStrategy: all
devices: ["iPhone 12 Pro-14", "iPad Air (2019)-16", "Galaxy Note10+-11", "Galaxy Note20 Ultra 5G-11"]

shards:
mappings:
- name: shard1
strategy: "only-testing/skip-testing"
values: ["<className>/<className/testName>"]
- name: shard2
strategy: "only-testing/skip-testing"
values: [""<className>/<className/testName>"", ""<className>/<className/testName>""]
When shards are added

If you are using the deviceSelectorStrategy: all, then in that case all the mentioned shards will be executed on all the devices.
For example: There are 2 shards and 2 devices mentioned, then the 2 shards will be executed on 2 devices (2 Shards * 2 Devices).

If you are using the deviceSelectorStrategy: any, then in that case all the mentioned shards will be executed on any one device from the list provided.
For example: There are 2 shards and 2 devices mentioned, then the 2 shards will be executed on any device (2 shards * any device mentioned).

When shards aren't added

If you are using the deviceSelectorStrategy: all, then in that case all the tests will be executed on all the devices based on the concurrency.
For example: There are 6 tests and 10 devices mentioned, then the 6 tests will be auto distributed on the devices based on the max concurrency.

If you are using the deviceSelectorStrategy: any, then in that case all the mentioned tests will be executed on any one device from the list provided.
For example: There are 6 tests and 10 devices mentioned, then the 6 tests will be executed on any one device.

  1. Go to the location of the folder on the terminal and run the below commands. After the second command, you may need to give permission on System Settings/Privacy & Security.
chmod u+x <cliFileNAme>
./<cliFileNAme> --u <userName> --k <accessKey> --verbose -i <yamlFileName>.yaml

You can refer to this example and screenshot below:

./hyperexecute --u my_user_name --k xyx123abc --verbose -i hyperexecute.yaml
cmd
  1. After the test is started you can follow the test on the below links.
note

globalTimeout ​ The globalTimeout value determines the maximum duration (in minutes) of a Job . It can be set between 5 and 180 minutes, and has a default value of 10 minutes.

Filters in Sharding

You can filter the Classes / Tests that you'd like to execute using filters. Here's an example of the same.

filters:
attributes:
- type: className
values: ["LambdaUiKitIOSUITests","LambdaUiKitIOSUITestsLaunchTests"]
- type: testName
values: ["LambdaUiKitIOSUITests/testverifyAppLaunch"]

This example will run only the 2 classes & one test as mentioned from the TestSuite.