Preparing XCUITest Tests for Upload

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

Requirements

Note

Xcode 12 / iOS 14 support is being worked on but not yet available.

  • Xcode >= 9.4.1
  • iOS >= 9.0

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 label and screenshot are automatically generated for the test report. Labels and screenshots are displayed in the App Center Test Report as separate Test Steps.

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)