XCTestPlan

XCTestPlan is a feature within Xcode used for building iOS, iPadOS, macOS, watchOS, tvOS, and audioOS applications. XCTestPlan helps manage how you run automated tests written with the XCTest framework.

XCTestPlan improves the organization and efficiency of running automated tests within Xcode. It allows you to create targeted test runs and manage various testing scenarios effectively.

Prerequisites

• Your LambdaTest Username and Access key.
• Access to an iOS app (.ipa) and an XCUI Test app (.ipa file).

tip

If you do not have any iOS app (.ipa) and an XCUI Test app (.ipa) file, you can run your sample tests on LambdaTest by using our sample 🔗 iOS app and a sample 🔗 XCUI Test.

Step 1: Upload Your Application

To begin testing, upload your iOS application (.ipa file) to LambdaTest's servers. You'll use our REST API for this process.

• Authentication : You'll need your LambdaTest Username and AccessKey. Combine them in the format Username:AccessKey.
• Uploading the App : Use cURL command to send a request to our API. The request should include the path to your application file (appFile).

Linux / MacOS

curl -u "undefined:undefined" --location --request POST 'https://manual-api.lambdatest.com/app/uploadFramework' --form 'appFile=@"<PATH_OF_YOUR_iOS_APP>"' --form 'type="xcuit-ios"'

Windows

curl -u "undefined:undefined" -X POST "https://manual-api.lambdatest.com/app/uploadFramework" -F "appFile=@"<PATH_OF_YOUR_iOS_APP>"" -F "type="xcuit-ios""

info

• Provide the path of your android application in the above URL in place of <PATH_OF_YOUR_iOS_APP>
• Response of above cURL will be a JSON object containing the App URL of the format - lt://APP123456789123456789 and will be used in the last step.

Step 2: Upload Your Test Suite and XCTestRun File

Upload your iOS test suite (.ipa) file to LambdaTest servers using our REST API. The following sample cURL command shows how to upload a test suite:

Linux / MacOS

curl -u "undefined:undefined" --location --request POST 'https://manual-api.lambdatest.com/app/uploadFramework' --form 'appFile=@"<PATH_OF_YOUR_TEST_SUITE_APP>"' --form 'type="xcuit-ios"'

Windows

curl -u "undefined:undefined" --location --request POST "https://manual-api.lambdatest.com/app/uploadFramework" --form "appFile=@"<PATH_OF_YOUR_TEST_SUITE_APP>"" --form "type="xcuit-ios""

info

• Provide the path of your android application in the above URL in place of <PATH_OF_YOUR_TEST_SUITE_APP>
• Response of above cURL will be a JSON object containing the App URL of the format - lt://APP123456789123456789 and will be used in the last step.

This is a sample xctestplan file which is compatible with our sample application provided above.

testLaunch.xctestplan

{
  "configurations" : [
    {
      "id" : "1D354D3E-7B86-4201-A441-6D23AF535802",
      "name" : "Configuration 1",
      "options" : {
      }
    }
  ],
  "defaultOptions" : {
  },
  "testTargets" : [
    {
      "skippedTests" : [
        "LambdaUiKitIOSUITests\/testverifyAppLaunch()"
      ],
      "target" : {
        "containerPath" : "container:LambdaUiKitIOS.xcodeproj",
        "identifier" : "84946A3027745AFD000E2562",
        "name" : "LambdaUiKitIOSUITests"
      }
    }
  ],
  "version" : 1
}

This will only be used for filtering tests using xctestplan. You can use the following capability in xcui/build api: "xctestplan" : "lt://APP1234567891234567890" and use the following curl to upload xctestplan file.

curl --location --request POST 'https://manual-api.lambdatest.com/app/xctestplan' \
--header 'Cookie: cf_use_ob=0' \
--header 'Authorization: Basic <Enter_Basic_Auth>' \
--form 'appFile=@"/path/to/file"' \
--form 'type="xctestplan"'

Step 3: Executing The Test

• You will need base64 encoded authentication in order to execute your Espresso automation test suite. Enter your username:accesskey in Basic Authentication Header Generator to generate your auth token.

Take note of the base64 encoded authentication which needs to be added in the next step.

undefined:undefined

• Once you have uploaded your app and test suite, you can execute your test by running the following command:

Enter your BASIC_AUTH_TOKEN, APP_ID (generated in the first step) and TEST_SUITE_ID (generated in the second step) in the below command.

Linux / MacOS

curl --location --request POST 'https://mobile-api.lambdatest.com/framework/v1/xcui/build' \
--header 'Authorization: Basic BASIC_AUTH_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "app" : "lt://APP_ID",
  "testSuite": "lt://TEST_SUITE_ID",
  "xctestplan" : "lt://YOUR_XC_TEST_PLAN_ID" #only when you want to use XCTestPlan
  "device" :  ["iPhone 11-14"],
  "video" : true,
  "queueTimeout": 10800,
  "idleTimeout": 150,
  "devicelog": true,
  "network": false,
  "build" : "Proverbial-XCUITest"
}'

Windows

curl --location --request POST "https://mobile-api.lambdatest.com/framework/v1/xcui/build" \
--header "Authorization: Basic BASIC_AUTH_TOKEN" \
--header "Content-Type: application/json" \
--data-raw "{
  "app" : "lt://APP_ID",
  "testSuite": "lt://TEST_SUITE_ID",
  "xctestplan" : "lt://YOUR_XC_TEST_PLAN_ID" #only when you want to use XCTestPlan
  "device" :  ["iPhone 11-14"],
  "video" : true,
  "queueTimeout": 10800,
  "idleTimeout": 150,
  "devicelog": true,
  "network": false,
  "build" : "Proverbial-XCUITest"
}"

Step 4: View Test Execution

Once you have run your tests, you can view the test execution along with logs. You will be able to see the test cases passing or failing. You can view the same at LambdaTest Automation.

NOTE: You cannot use XCTestPlan and Filters simultaneously

tip

To learn how to use XCTestPlan with sharding in XCUI, refer to the detailed guide in Sharding for XCUI.