Run Xcode Unit Tests From The Command Line

In this tutorial, you will learn how to build and run Xcode Unit Tests from the command line.

Command Line Tools Package for Xcode

To be able to build and test your project using the terminal window you will need to have the Command Line Tools package installed on your machine. If the machine you want to build and run Xcode tests does already have Xcode 11 installed, then most likely you do already have the command-line tools installed. If you do not have a command-line tools package installed then you can download it from Apple Downloads Page.

The -destination Option

When building or running Xcode tests you will use the -destination option to specify which iOS device and iOS version should be used. To learn about the available destinations, open the terminal window on your Mac machine and use the below command:

instruments -s devices

The above command will print a list of available destinations you can use to build and run Xcode unit tests.

Build Unit Tests Without Running

To build Unit Tests from the command line you will need to use the xcodebuild command.

xcodebuild build-for-testing [-workspace <your_workspace_name>]
                             [-project <your_project_name>]
                             -scheme <your_scheme_name>
                             -destination <destination-specifier>

To run this command, you will need to:

• Open the Terminal window on your Mac,
• Change directory to a root folder of your Xcode project.

Once you are in the root folder of your Xcode project, execute the above command with the details of your project. Like so:

  xcodebuild build-for-testing \
  -project PhotoApp.xcodeproj \
  -scheme PhotoApp \
  -destination 'platform=iOS Simulator,name=iPhone 8,OS=13.3'

Where:

• PhotoApp.xcodeproj is the name of the Xcode project,
• PhotoApp is the name of a Scheme

For the -destination option provide iOS Simulator if you are running Xcode tests on Simulator rather than on an actual iPhone device and OS is the version of iOS installed on iOS Simulator. If you are not sure what Simulator name and OS version are available to use, then run the following command to get a list of destinations: instruments -s devices.

The successful execution of the above command will build but not run Xcode Unit Tests.

Build and Run Unit Tests

To build and run unit tests from the command line, execute the following command in the Terminal window on your Mac machine.

xcodebuild test \
-project PhotoApp.xcodeproj \
-scheme PhotoApp \
-destination 'platform=iOS Simulator,name=iPhone 8,OS=13.3'

The above command will build all unit tests available in Xcode project PhotoApp.xcodeproj and will also run them. I get the following result when I run the above command for my project.

Run Unit Tests Without Building Them

To run unit tests without building them from the command line, execute the following command in the Terminal window.

xcodebuild test-without-building [-workspace <your_workspace_name>]
                                 [-project <your_project_name>]
                                 -scheme <your_scheme_name>
                                 -destination <destination-specifier>

Run a Single Unit Test

You can use the xcodebuild command to execute only a selected unit test. To execute a single unit test with xcodebuild use the -only-testing option and provide the unit test identifier.

xcodebuild test -xctestrun <your_xctestrun_name>.xctestrun
                                 -destination <destination-specifier>
                                 [-only-testing:<test-identifier>]

where <test-identifier> should be provided in the following form: TestTarget[/TestClass[/TestMethod]]

For example,

xcodebuild test \
-scheme PhotoApp \
-project PhotoApp.xcodeproj \
-destination 'platform=iOS Simulator,name=iPhone 8,OS=13.3' \
-only-testing PhotoAppTests/FormModelTests/testInvalidFirstName

where:

• PhotoAppTests – is a Test Target,
• FormModelTests – is a Test Class,
• testInvalidFirstName – is a test method name to be executed.

Skip Selected Unit Test

You can also skip the selected unit test and not execute it. To skip the selected unit test use the -skip-testing option with the xcodebuild command.

xcodebuild test -xctestrun <your_xctestrun_name>.xctestrun -destination <destination-specifier> [-skip-testing:<test-identifier>]

For example,

 xcodebuild test \
-scheme PhotoApp \
-project PhotoApp.xcodeproj \
-destination 'platform=iOS Simulator,name=iPhone 8,OS=13.3' \
-skip-testing PhotoAppTests/FormModelTests/testInvalidFirstName

I hope the following tutorial was of some help to you.

To read other tutorials on how to test iOS applications with Xcode, have a look at the Unit Testing category.

Happy Unit Testing 🙋🏻‍♂️