Preparing XCUITest Tests for Upload

Important

Visual Studio App Center is scheduled for retirement on March 31, 2025. While you can continue to use Visual Studio App Center until it is fully retired, there are several recommended alternatives that you may consider migrating to.

Learn more about support timelines and alternatives.

This guide provides instructions for preparing XCUITest tests for upload to App Center Test.

Test service Requirements

• Xcode >= 9.4.1
• iOS >= 9.0

Note

Xcode 12 and iOS 14 are available now!

Test service limitations

• Only the uploaded app can be tested, not interactions via apps or the rest of the system.

Build For Testing

To run a test in App Center, you need to build your application and an XCUITest bundle. Run one of the two following commands from the root of your application project directory:

# How to build a xcodeproj
rm -rf DerivedData
xcrun xcodebuild build-for-testing \
  -configuration Debug \
  -project YOUR_XCODEPROJ \
  -sdk iphoneos \
  -scheme YOUR_APP_SCHEME \
  -derivedDataPath DerivedData

YOUR_XCODEPROJ should point to a .xcodeproj file, likely titled PROJECT_NAME.xcodeproj. If you use a .xcworkspace, use -workspace instead of -project. YOUR_APP_SCHEME should be the scheme you use to build your application. By default, it's usually the name of your application.

The xcrun will build your app and an XCUITest bundle into the DerivedData/Build directory. Your app and XCUITest bundle will be located in the DerivedData/Build/Products/Debug-iphoneos/ directory.

xcrun xcodebuild -list

Uploading Tests to App Center

Once a test suite is prepared, next setup a test run to upload and run your tests.

Here's an example of how you might upload your XCUITest suite to App Center Test.

# Upload your test to App Center
appcenter test run xcuitest \
  --app "APP_ID" \
  --devices "DEVICE_SET_ID" \
  --test-series "main" \
  --locale "en_US" \
  --build-dir DerivedData/Build/Products/Debug-iphoneos

For a concrete example of submitting tests to App Center, see this shell script that submits tests to App Center.

Additional Screenshots and Test Steps

At the end of each test method, a screenshot is automatically taken for the test report. Each screenshot is displayed in the App Center Test Report as a separate Test Step.

Activities

You can generate additional labels and screenshots for a test method by grouping your test code using Apple's Activities. For more information, see Grouping Tests into Substeps with Activities.

Code snippet to wrap test code in an Activity

    [XCTContext
     runActivityNamed:title
     block:^(id<XCTActivity>  _Nonnull activity) {
         // test code
     }];

        XCTContext.runActivity(named: title) { (activity) in
            // test code
        }

Manual Screenshots

A screenshot is automatically generated for the test report at the end of each Activity. You can record a screenshot at a different point within an Activity by taking a screenshot using XCUIScreen, then creating an attachment with XCTAttachment, and adding it to the current Activity. This screenshot will be displayed in App Center Test Reports instead of the default screenshot from the end of the Activity.

Code snippet to generate and attach a screenshot in an Activity

         XCUIScreenshot *screenshot = [[XCUIScreen mainScreen] screenshot];
         XCTAttachment *attachment;
         attachment = [XCTAttachment attachmentWithScreenshot:screenshot];
         [attachment setLifetime:XCTAttachmentLifetimeKeepAlways];
         [activity addAttachment:attachment];

            let screenshot = XCUIScreen.main.screenshot()
            let attachment = XCTAttachment(screenshot: screenshot)
            attachment.lifetime = .keepAlways
            activity.add(attachment)