XCUITest Tutorial: A Detailed Guide To XCUITest Framework

How do I get started with XCUITest?

The XCUITest framework is an excellent choice for test automation. It is therefore essential to carry out XCUITest automation efficiently. Scaling up Apple device labs is tedious and expensive. Therefore, it is important to use a real device cloud platform such as LambdaTest that eliminates the hassle of setting up an in-house device lab. Leveraging LambdaTest’s online device farm, developers and testers can perform XCUI testing on real iOS devices anywhere at any time.

Prerequisites

Ensure you have installed the npm dependencies & should have a LambdaTest username and access key. You can obtain these by registering on LambdaTest and accessing the automation dashboard. You'll also need an iOS app (.ipa) and an XCUI Test app (.ipa file). If you don't have these, you can run your sample tests on LambdaTest using our sample iOS app and a sample XCUI Test.

Getting Started with XCUITest Automation on LambdaTest

Want to know a fun fact? Your first 100 XCUITest automation minutes are on us with just a free sign-up. In addition, you can also avail benefits of cross browser testing, manual app testing, Visual UI testing, responsive testing, and more.

Running Your Initial Test

Step 1: Application Upload

The first step is to upload your iOS application (.ipa file) to LambdaTest servers. This is done using the REST API. The cURL command should include your Username and AccessKey, in the form Username:AccessKey. Also, ensure to add the path of the appFile in the cURL request. The example below demonstrates how to upload your app using the REST API:

For Linux / MacOS:

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

For Windows:

curl -u "YOUR_LAMBDATEST_USERNAME:YOUR_LAMBDATEST_ACCESS_KEY" -X POST "https://manual-api.lambdatest.com/app/uploadFramework" -F "appFile=@"/Users/macuser/Downloads/proverbial.ipa"" -F "type="xcuit-ios""

The response will be a JSON object carrying the App URL in the following format: lt://APP123456789123456789. You'll use this in the final step.

Step 2: Test Suite Upload

Next, upload your test suite (.ipa file) to the LambdaTest servers using our REST API. As before, you need to provide your Username and AccessKey in the format Username:AccessKey in the cURL command. Remember to include the path of the appFile in the cURL request. See the example below:

For Linux / MacOS:

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

For Windows:

curl -u "YOUR_LAMBDATEST_USERNAME:YOUR_LAMBDATEST_ACCESS_KEY" --location --request POST "https://manual-api.lambdatest.com/app/uploadFramework" --form "appFile=@"C:/Users/varunkumarb/Downloads/proverbial_ios_xcuitest.ipa"" --form "type="xcuit-ios""

The response will be a JSON object carrying the App URL in the following format: lt://APP123456789123456789. Keep it for the subsequent step.

Step 3: Test Execution

For Basic Authentication, you will need base64 encoded authentication to carry out your XCUI automation test suite. Input your username:accesskey as instructed, then encode to generate the base64 authentication. Record the base64 encoded authentication for the following step.

YOUR_LAMBDATEST_USERNAME:YOUR_LAMBDATEST_ACCESS_KEY

Once you've uploaded both your app and test suite, you can execute your test. Fill in your basic authentication, app URL (from step 1), and testSuite URL (from step 2) in the command below:

curl --location --request POST 'https://mobile-api.lambdatest.com/framework/v1/xcui/build' \
--header 'Authorization: Basic <Enter_Basic_Auth>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "app" : "lt://APP_ID",
    "testSuite": "lt://TestSuite_ID",
    "device" :  ["iPhone 11-14"],
    "video" : true,
    "queueTimeout": 10800,
    "idleTimeout": 150,
    "devicelog": true,
    "network": false,
    "build" : "Proverbial-XCUITest"
}'

Step 4: Examination of Test Execution

After executing your tests, you can review the test execution along with logs. You can check the success or failure of test cases on LambdaTest Automation.

You can head over to our XCUI testing guide for a step-by-step procedure for running your first XCUITest automation script on a cloud XCUITest Grid. So you don’t have to worry about the challenges with XCUITest infrastructure as we will provide you with a cloud XCUITest Grid with highly scalable infrastructure.

About LambdaTest

LambdaTest is the world’s leading test orchestration and execution platform. It allows users to run manual and automated web and mobile app testing across 3000+ browsers, operating systems, and real device combinations. Using LambdaTest, organizations can ensure faster developer feedback on code changes and achieve faster go-to-market delivery. Over 500 enterprises and 2 Million + users across 130+ countries rely on LambdaTest for their testing needs.

An Overview of the XCUITest API

This section of XCUITest tutorial provides an introduction to the XCUITest API.

In XCTest, all classes are conveniently packaged into a single file - XCTest. Following are the different classes testers can use to automate iOS apps.

• XCUIElementQuery: The XCUIElementQuery methods can be used to find an element in the user interface and perform some action on it.

Declaration: class XCUIElementQuery : NSObject

• XCUIElement: The XCUIElement method represents a UI element in an iOS app. It allows you to test the app with gestures like touching, swiping, dragging and rotating.

Declaration: class XCUIElement : NSObject

• XCUIApplication: A proxy representing an iOS application to launch, monitor, and terminate it.

Declaration: class XCUIApplication : XCUIElement

• XCUIElement.ElementType: A user interface test involves locating, inspecting, and interacting with UI elements. For example - .button, .image etc.

Declaration: enum ElementType : UInt, @unchecked Sendable

• XCUIScreen: It represents the physical screen of the device (iOS/macOS//tvOS) that is used to grab screenshots during test execution.

Declaration: class XCUIScreen : NSObject

• XCUIScreenshot: It represents screenshots of a screen, app, or UI element.

Declaration: class XCUIScreenshot : NSObject

• XCUIDevice: It represents a proxy that can simulate physical buttons, device orientation, and interact with Siri

Declaration: class XCUIDevice : NSObject

• XCUIRemote: This class represents simulating interactions with physical remote controls.

Declaration: class XCUIRemote : NSObject

Differences between XCUITest and Appium

In this section of XCUITest tutorial, we will look at how XCUITest framework differs from Appium.

Both Appium and XCUITest are used for mobile automation testing. Appium is used to perform app automation testing of Android and iOS applications. It supports different programming languages like Java, JavaScript, Python, PHP, and more.

On the other hand, XCUITest is a native framework for testing iOS applications. Since it comes pre-built with Xcode IDE, it provides the fastest test speed to perform automated device testing for iOS applications.

Below are some differences between XCUITest and Appium framework.

Limitations of XCUITest framework

Here are the limitations of using XCUITest for automated app testing.

• Testing on iOS Simulators or running unit tests with XCUITest avoids flaky tests, but performing XCUI testing on real devices does not ensure anti-flakiness.
• It is not ideal for smoke or regression testing on real devices.
• It does not support a wide range of languages. XCUITest currently only supports Objective C and Swift.
• It doesn't offer Android automation testing.

Best Practices of XCUITest

The effectiveness of your XCUITest automation script will depend entirely on test design, implementation, and analysis. This section of XCUITest guide discusses some of the best practices to follow to make your XCUITest automation suites more efficient and stable.

• The UI test recorder captures information about UI interactions, including application internals. You can use the built-in UI recording features of XCUITest to record a test interaction with your app's UI and save that interaction as a source code.
• When you convert any test case to a test script, ensure that what you are testing is to avoid test code fixing every time.
• It may take some time before the view is fully displayed. Therefore, you should always wait for the view's presence before asserting anything.
• In XCUITest, you can specify user interactions such as tap(), doubleTap(), and twoFingerTap(). With press(), you can specify a duration, or both a duration and a dragging target. There are four directional swipes (left, right, up, and down), a pinch() with scale and velocity, and a rotate() with velocity.
• Besides UI testing, you can run web accessibility tests using the UIAccessibility protocol for people with impairments. This will help you maximize your potential customer base.
• It’s good practice to create a framework and a guideline to help your team add more tests.