Google is committed to advancing racial equity for Black communities. See how.

Run an XCTest

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:

    project

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

    workspace

    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 MyTests.zip 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 step

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