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:
- Open your project in Xcode.
- In the macOS menu bar, select File > Project Settings...
- Change the Derived Data drop-down from Default Location to Custom Location.
- In the field below the drop-down, select a location for Xcode to output your tests to. (This is your FOLDER_WITH_TEST_OUTPUT)
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:
- From the device drop-down at the top of your Xcode workspace window, select Generic iOS Device.
- In the macOS menu bar, select Product > Build For > Testing.
As an alternative, you can build your XCTest from the command line. Use the following command in a terminal:
xcodebuild -project PATH/TO/YOUR_WORKSPACE/YOUR_PROJECT.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
Step 3: Sign your test and verify
Make sure all artifacts in the app and test are signed. For example, you can do this through Xcode by specifying signing settings like provisioning profile and identity. For more information, see Apple Code Signing.
Verify app signature by running
codesign --verify --deep --verbose /path/to/MyApp.appwhere "MyApp" is the name of the app inside the unzipped folder. This varies for each project. Expected output is
MyApp.app: valid on disk.
If you are running an XCUITest, then you need to verify the test and runner by running
codesign --verify --deep --verbose /path/to/MyTest-Runner.appwhere "MyTest" is the name of the runner inside the unzipped folder. This varies for each project. Expected output is
MyTest-Runner.app: valid on disk.
Step 4: Package your app and test for uploading
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:
Open Finder and navigate to
Open the folder that has your project name as a prefix, then navigate to
Select the folders
YOUR_SCHEME_iphoneosDEPLOYMENT_TARGET-arm64.xctestrunand then compress them.
Step 5: (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/YOUR_SCHEME.xctestrun" \ -destination id=your-phone-id
Upload and run your test in the Firebase console or the gcloud CLI.