Connect & Get help from fellow developers on our Discord community.

Integrate XCUI tests with App Accessibility testing

Learn how to add accessibility checks to your existing functional tests and generate comprehensive reports of accessibility issues.

XCUITest is a mobile automation framework provided by Apple that helps you write UI tests for your iOS applications. BrowserStack supports out of the box integration with XCUITest. You can integrate your existing functional test suites with App Accessibility testing to run accessibility checks on your mobile apps. You can access the generated accessibility violation reports on the App Accessibility dashboard.

Automated App Accessibility testing using XCUITest is supported on iOS 14+ and Swift 5.4+.

Prerequisites

Ensure you have a BrowserStack Username and Access Key. Obtain your userName and accessKey from the Account & Profile section on the dashboard.
If you have not yet created an account, sign up for a free trial.
Xcode is installed on your local machine. For more information, see the official Xcode documentation.
XCUI tests are built into a separate zip file. Ensure you have access to both the app (.ipa file) as well as an XCUI test-suite (as a separate .zip file).

Procedure:

To execute XCUI Tests using the BrowserStack Swift SDK:

Add the BrowserStack Swift SDK as a dependency

Open your project in Xcode.
Go to File > Add Package Dependencies.
Search for BrowserStack Swift SDK.
Click Add Package.
Assign the SDK to the test target that will run UI tests.

Initialize the BrowserStack Swift SDK

You can initialize the BrowserStack Swift SDK either by configuring the Info.plist file or by adding initialization code in your test implementation.

Property List
Test Code

        
        In your test target, open the Info.plist file.
Add the following key to ensure the SDK is invoked when the test bundle loads.
         ...
     <key>NSPrincipalClass</key>
     <string>BrowserstackSwiftSDK.BrowserstackSwiftSDK</string>
     ...

        
        

        Open your test target in Xcode.
Import the BrowserStack Swift SDK at the top of your test file:
     import BrowserstackSwiftSDK
In your test class, initialize the SDK in the init() method:
     ...

 class MyUITestClass: XCTestCase {
     override init() {
         super.init()
         let _ = BrowserstackSwiftSDK.init()
         // ...other initialization code...
     }

     // ...test methods...
 }



      

Build your project

Build both the main app and the test app (test bundle) in Xcode.
Ensure the minimum supported Swift version is 5.4 and the minimum iOS version is 14.0.

Upload the app

Upload the sample app (.ipa) to the BrowserStack servers using a REST API request.

The following sample cURL command demonstrates how to upload an app:

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST "https://api-cloud.browserstack.com/app-automate/xcuitest/v2/app" \
-F "file=@/path/to/app/file/App.ipa"

A sample response for the request is shown below:

{
    "app_name":"Application-debug.ipa",
    "app_url":"bs://j3c874f852ea50957a3fdc33f47514288c4ba4",
    "app_version":"1.0",
    "app_id":"j3c874f852ea50957a3fdc33f47514288c4ba4",
    "uploaded_at":"2022-05-12 07:27:54 UTC",
    "expiry":"2022-06-11 07:27:54 UTC"
}

Use the app_id parameter to identify the application when you run XCUI tests.

App upload may take a few seconds to a minute, depending on the size of your app. Do not interrupt the cURL command until you get the response.

Upload the test suite

Upload the sample test suite (.zip file) to the BrowserStack servers using a REST API request.

The following sample cURL command demonstrates how to upload a test suite:

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST "https://api-cloud.browserstack.com/app-automate/xcuitest/v2/test-suite" \
-F "file=@/path/to/app/file/Application-debug-test.zip"

A sample response for the request is shown below:

{
    "test_suite_name":"Application-debug-test.zip",
    "test_suite_url":"bs://f7c874f21852ba57957a3e31f47514288c4ba4",
    "test_suite_id":"f7c874f21852ba57957a3e31f47514288c4ba4",
    "uploaded_at":"2022-05-12 07:32:41 UTC",
    "expiry":"2022-06-11 07:32:41 UTC",
    "framework":"xcuit"
}

Use the test_suite_id parameter to identify the test suite when you run XCUI tests.

Run XCUI tests

In a cURL command, include the following parameters and send the API request to run the test.

app: specify the app_id, which is the unique identifier of the application that you want to test. The app_id is generated when you upload the app to BrowserStack, see Upload the app.
testSuite: specify the test_suite_id, which is the unique identifier of the test suite you want to run. The test_suite_id is generated when you upload your test suite to BrowserStack, see Upload the test suite.
devices: specify a list of iOS devices on which you want to test your app. For more information, see Specify devices.
accessibility: enable accessibility checks.
accessibilityOptions: Configure the accessibilityOptions parameter to set various accessibility testing options. For a list of available accessibility options that you can use to configure your tests, see Configuration options.

In the API request, app, testSuite, and devices are mandatory parameters to start the test execution.
For a complete list of parameters that you can use in your XCUITest test execution, see XCUITest Build API reference.

curl -u "USERNAME:ACCESS_KEY" \
-X POST "https://api-cloud.browserstack.com/app-automate/xcuitest/v2/build" \
-d "{
    \"app\": \"bs://$app_id\",
    \"testSuite\": \"bs://$test_suite_id\",
    \"devices\": ["iPhone 15 Pro Max-26"]
    \"deviceLogs\": true,
    \"project\": \"$PROJECT_NAME\",
    \"accessibility\": true,
    }
}" \
-H "Content-Type: application/json"

Response

A sample response for the request is shown below:

{
    "message" : "Success",
    "build_id" : "4d2b4deb810af077dd98f479bfdd2e64f36c3"
}

The build_id uniquely identifies your build in App Automate. Each test build is an execution of the XCUI test suite on all selected devices.

View test results

After you run the test using the REST API, visit the App Accessibility dashboard to view your test results, debugging logs, and overall test details.

Visit App Accessibility dashboard

You can also use API requests to view the test results.

Did this page help you?

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Is this page helping you?

Yes

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback!