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 steps

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