Preparing XCUITest Tests for Upload
AppCenter XCUITest Extensions is an iOS Framework for taking screenshots and labeling test steps when running XCUITest test in App Center or Xamarin Test Cloud. At the conclusion of each test method, a label and screenshot are automatically generated for the test report. You can create additional labels and screenshots to track your app's progress during a test method.
This framework is required for running XCUITests in App Center and Xamarin Test Cloud.
If you encounter a problem, please file a GitHub issue.
- XCode >= 9.0
- Sierra or High Sierra
- iOS >= 9.0
You must launch your application using the
//Insert before @interface #import <AppCenterXCUITestExtensions/AppCenterXCUITestExtensions.h> XCUIApplication *app = act_launch XCUIApplication *app = act_launch_app([[XCUIApplication alloc] init]); XCUIApplication *app = [ACTLaunch launch]; XCUIApplication *app = [ACTLaunch launchApplication:[[XCUIApplication alloc] init]];
//insert before class import AppCenterXCUITestExtensions let app = ACTLaunch.launch() let app = ACTLaunch.launch(XCUIApplication())
Be sure that you launch your app with the
ACTLaunch API. See the
examples in the Requirements section.
Adding the AppCenterXCUITestExtensions to an Xcode Project
The AppCenterXCUITestExtensions.framework needs to be linked with the project's XCUITest target. The framework should not be linked with the project's iOS application.
- Carthage – Preferred. This is a dependency manager for iOS and macOS.
- Building from Source – Build the extension from source and manually add it to the Xcode project.
- CocoaPods – For those who are already using CocoaPods.
Install carthage with homebrew:
$ brew install carthage
Cartfile with the following contents:
Follow the Carthage Instructions for installing frameworks from a Cartfile.
Remember that the AppCenterXUITestExtensions.framework needs to be linked with the XCUITest target and not the iOS application.
You can check this test code as an example for setting up App Center XCUITest Example code
1. Make the AppCenterXCUITestExtensions.framework
$ git clone email@example.com:Microsoft/AppCenter-Test-XCUITest-Extensions.git $ cd AppCenter-Test-XCUITest-Extensions $ make ... INFO: Installed Products/framework/AppCenterXCUITestExtensions.framework INFO: Done!
AppCenterXCUITestExtensions.framework into your application's project folder.
Use the Finder to drag-and-drop or use
ditto to perserve symbolic
links and file attributes.
$ ditto Products/framework/AppCenterXCUITestExtensions.framework \ path/to/MyApp/AppCenterXCUITestExtensions.framework
3. Link AppCenterXCUITestExtensions.framework with the XCUITest target
In Xcode, in the 'Build Phases' tab of the XCUITest target (not the
main application target), add the
AppCenterXCUITestExtensions.framework in the 'Link Binary With
In the same tab, add a 'Copy Files' phase with Destination: Frameworks
and add the
Note that your project may already have a 'Copy Files' phase.
When you are finished, your Build Phases pane should resemble the following:
Here is a Swift example Code example
If you are not already using CocoaPods, we recommend you use Carthage or manually linking the framework.
Podfile in your Xcode project folder with the following:
use_frameworks! # required for projects with Swift sources target 'MyAppUITests' do pod 'AppCenterXCUITestExtensions' end
'MyAppUITests' should be the name of the target for your XCUITests.
$ pod install
Code example for CocoaPods Code example
Build For Testing
In order to run a test in App Center or Xamarin Test Cloud, you will need to build your application and an XCUITest bundle. To do this, run the following command from the root of your application project directory:
$ rm -rf DerivedData $ xcrun xcodebuild build-for-testing \ -configuration Debug \ -workspace YOUR_WORKSPACE \ -sdk iphoneos \ -scheme YOUR_APP_SCHEME \ -derivedDataPath DerivedData
This will build your app and an XCUITest bundle into the
DerivedData/Build directory. Your app and XCUITest bundle will be
located in the
YOUR_WORKSPACE should point to a
.xcworkspace file, likely titled
YOUR_APP_SCHEME should be the scheme you
use to build your application. By default it is usually the name of your
application. To see the list of schemes defined in your Xcode project,
$ xcrun xcodebuild -list
For a concrete example of generating an app and an XCUITest bundle, see bin/make/build-for-testing.sh.
Uploading Tests to App Center
Tests are uploaded to App Center using the
appcenter command line tool.
To install, follow the instructions in the README of the AppCenter-CLI GitHub repository.
Use the App Center Test page to generate a device selection and an example command-line invocation. For more information, see Starting a Test run.
# Follow the instructions to generate a resuable API token. # Save this token, you will use it later, but keep it private. $ appcenter login # Generate an XCUITest bundle and your iOS application as describe above. $ rm -rf DerivedData $ xcrun xcodebuild build-for-testing [args] -derivedDataPath DerivedData -scheme YOUR_APP_SCHEME # Upload your test to App Center $ appcenter test run xcuitest \ --app "<app center username/<app name>" \ --devices DEVICE_SET \ --test-series "master" \ --locale "en_US" \ --build-dir DerivedData/Build/Products/Debug-iphoneos \ --token APP_CENTER_API_TOKEN
For a concrete example of submitting tests to App Center, see bin/make/appcenter.sh.