Firebase is back at Google I/O on May 10! Register now

Run an XCTest

Stay organized with collections Save and categorize content based on your preferences.

This guide describes how to prepare an XCTest for testing in Firebase Test Lab.

Step 1: Configure your project's Derived Data location

Xcode places compiled iOS artifacts, including any tests you build, in a Derived Data directory. It is possible to keep the default location for that directory, if you'd like, but it's often helpful to choose a more easily-accessible place for the files, especially if you're going to be running tests with Test Lab often:

  1. Open your project in Xcode.
  2. In the macOS menu bar, select File > Project Settings...
  3. Change the Derived Data dropdown from Default Location to Custom Location.
  4. In the field below the dropdown, select a location for Xcode to output your tests to.

Step 2: Build a generic test file

Test Lab runs unit tests and UI tests using the XCTest framework. To run your app's XCTests on Test Lab devices, build it for testing on a Generic iOS Device:

  1. From the device dropdown at the top of your Xcode workspace window, select Generic iOS Device.
  2. In the macOS menu bar, select Product > Build For > Testing.

Step 3: Package your app for uploading

Finally, build and package your test for upload to Test Lab by compressing the test files you built into a .zip file.

  1. To build your XCTest, use the following command in a terminal:


    xcodebuild -project PATH/TO/YOUR_WORKSPACE.xcodeproj \
    -scheme YOUR_SCHEME \
    -derivedDataPath FOLDER_WITH_TEST_OUTPUT \
    -sdk iphoneos build-for-testing


    xcodebuild -workspace PATH/TO/YOUR_WORKSPACE.xcworkspace \
    -scheme YOUR_SCHEME \
    -derivedDataPath FOLDER_WITH_TEST_OUTPUT \
    -sdk iphoneos build-for-testing
  2. After your test successfully builds, zip it for upload to Test Lab:

    cd FOLDER_WITH_TEST_OUTPUT/Build/Products : \
    zip -r Debug-iphoneos   YOUR_SCHEME_iphoneosDEPLOYMENT_TARGET-arm64.xctestrun

You can also package up your test by compressing the test files manually:

  1. Open Finder and navigate to the directory you designated for Derived Data output.

  2. Open the folder you selected for your project, then open the Build/Products folder inside.

  3. Select the folders Debug-iphoneos and PROJECT_NAME_iphoneosDEVELOPMENT_TARGET-arm64.xctestrun and then compress them.

Step 4. (Optional) Run your test locally

Before running your test with Test Lab, you can run it locally with a USB-connected device to quality check its behavior:

xcodebuild test-without-building \
    -xctestrun "Derived Data/Build/Products/YourApp.xctestrun" \
    -destination id=your-phone-id

Next steps

Upload and run your test in the Firebase console or the gcloud CLI.