# Running unit and UI tests for iOS apps

You can run both unit and UI tests for iOS apps on Bitrise with our dedicated Step. The Step runs the [test targets you defined](https://developer.apple.com/documentation/xctest/defining_test_cases_and_test_methods/) in your Xcode project and [exports the results for you to view it in detail](/bitrise-ci/testing/test-reports/viewing-test-results).

To run Xcode tests on Bitrise, you need two Steps to run Xcode tests and view their results:

[**Xcode Test for iOS**](https://github.com/bitrise-steplib/steps-xcode-test).

**Deploy to**[**Bitrise.io**](http://Bitrise.io).

:::note[Code signing files]

Running Xcode tests and deploying their results to Bitrise do not require any [code signing](/bitrise-ci/code-signing/ios-code-signing/creating-a-signed-ipa-for-xcode-projects) files. So don’t worry about them just yet!

:::

The [**Xcode Test for iOS**](https://github.com/bitrise-steplib/steps-xcode-test) Step runs your tests, exports your test results, the `.xcresult` file, all test attachments, and the log of the `xcodebuild test` command.

:::tip[Xcode test results in HTML]

You can also view your Xcode test results in a rich HTML format, using the [**Generate Xcode test report html**](https://github.com/bitrise-steplib/bitrise-step-generate-xcode-html-report) Step: [Viewing Xcode test results in rich HTML format](/bitrise-ci/testing/testing-ios-apps/viewing-xcode-test-results-in-rich-html-format).

:::

To run tests using the Step:

  

**Workflow Editor**

  1. Make sure [you install all of the app's dependencies](/bitrise-ci/dependencies-and-caching/ios-dependencies/managing-dependencies-with-carthage) in your Workflow.
  1. Add the [**Xcode Test for iOS**](https://github.com/bitrise-steplib/steps-xcode-test) Step to the Workflow.
  1. Make sure the **Project path** input points to the correct location.

     The input asks for the path to your `.xcodeproj,``.xcworkspace` , or `Package.swift` file. In most cases, you don't need to change this input: when adding a new app, the project scanner automatically finds the relevant file and stores its location in the [Environment Variable](/bitrise-ci/configure-builds/environment-variables) that is the default value of the input.

     ![xcode-test-for-ios.png](/img/_paligo/uuid-bba07440-4913-8b44-0391-1dd275534500.png)
  1. Make sure the **Scheme** input points to the scheme you want to use to build the app.

     The default value is the [Environment Variable](/bitrise-ci/configure-builds/environment-variables) that stores the scheme you set during the initial configuration of the app. If you wish to use a different scheme, type its name to the input field.

     :::important[Shared scheme only]

     The scheme must be a shared Xcode scheme!

     :::
  1. Configure the device destination in the **Device destination specifier** input: the input takes comma-separated key-value pairs. For example, if you wish to build an app to test on an iPhone 14 with the latest available OS:

     ```bash
     platform=iOS,name=iPhone 14 Plus,OS=latest
     ```

     The input sets the `-destination` option of `xcodebuild`. Read more about the possible options: [How do I run unit tests from the command line?](https://developer.apple.com/library/archive/technotes/tn2339/_index.html#//apple_ref/doc/uid/DTS40014588-CH1-UNIT)
  1. Optionally, set a specific [test plan](https://developer.apple.com/documentation/xcode/organizing-tests-to-improve-feedback?changes=_8) in the **Test plan** input.

     The input sets the `-testPlan` option of the `test` action of `xcodebuild`. If you leave this empty, the test plan specified in the Xcode scheme will be used.
  1. Add the [**Deploy to Bitrise.io - Build Artifacts, Test Reports, and Pipeline intermediate files**](https://github.com/bitrise-steplib/steps-deploy-to-bitrise-io) Step to the end of your Workflow to be able to access the test results and other outputs: [Deploying test results](/bitrise-ci/testing/test-reports/deploying-test-results).

  
  

**Configuration YAML**

  1. Make sure [you install all of the app's dependencies](/bitrise-ci/dependencies-and-caching/ios-dependencies/managing-dependencies-with-carthage) in your Workflow.
  1. Add the `xcode-test` Step to the Workflow.

     ```yaml
     your-workflow:
       steps:
         - activate-ssh-key: {}
         - git-clone: {}
         - xcode-test:
             inputs:
     ```
  1. Make sure the `project_path` input points to the correct location.

     The input asks for the path to your `.xcodeproj,``.xcworkspace` , or `Package.swift` file. In most cases, you don't need to change this input: when adding a new app, the project scanner automatically finds the relevant file and stores its location in the [Environment Variable](/bitrise-ci/configure-builds/environment-variables) that is the default value of the input.

     ```yaml
     your-workflow:
       steps:
         - activate-ssh-key: {}
         - git-clone: {}
         - xcode-test:
             inputs:
             - project_path: "$BITRISE_PROJECT_PATH"
     ```
  1. Make sure the `scheme` input points to the scheme you want to use to build the app.

     The default value is the [Environment Variable](/bitrise-ci/configure-builds/environment-variables) that stores the scheme you set during the initial configuration of the app. If you wish to use a different scheme, type its name to the input field.

     ```yaml
     your-workflow:
       steps:
         - activate-ssh-key: {}
         - git-clone: {}
         - xcode-test:
             inputs:
             - project_path: "$BITRISE_PROJECT_PATH"
             - scheme: test
     ```

     :::important[Shared scheme only]

     The scheme must be a shared Xcode scheme!

     :::
  1. Configure the device destination in the `destination` input: the input takes comma-separated key-value pairs. For example, if you wish to build an app to test on an iPhone 14 with the latest available OS:

     ```yaml
     your-workflow:
       steps:
         - activate-ssh-key: {}
         - git-clone: {}
         - xcode-test:
             inputs:
             - project_path: "$BITRISE_PROJECT_PATH"
             - scheme: test
             - destination: platform=iOS Simulator,name=iPhone 14 Plus,OS=latest
     ```

     The input sets the `-destination` option of `xcodebuild`. Read more about the possible options: [How do I run unit tests from the command line?](https://developer.apple.com/library/archive/technotes/tn2339/_index.html#//apple_ref/doc/uid/DTS40014588-CH1-UNIT)
  1. Optionally, set a specific [test plan](https://developer.apple.com/documentation/xcode/organizing-tests-to-improve-feedback?changes=_8) in the `test_plan` input.

     The input sets the `-testPlan` option of the `test` action of `xcodebuild`. If you leave this empty, the test plan specified in the Xcode scheme will be used.

     ```yaml
     your-workflow:
       steps:
         - activate-ssh-key: {}
         - git-clone: {}
         - xcode-test:
             inputs:
             - project_path: "$BITRISE_PROJECT_PATH"
             - scheme: test
             - destination: platform=iOS Simulator,name=iPhone 11 Plus,OS=latest
             - test_plan: my_plan
     ```
  1. Add the `deploy-to-bitrise-io` Step to the end of your Workflow to be able to access the test results and other outputs: [Deploying test results](/bitrise-ci/testing/test-reports/deploying-test-results).

     ```yaml
     your-workflow:
       steps:
         - activate-ssh-key: {}
         - git-clone: {}
         - xcode-test:
             inputs:
             - project_path: "$BITRISE_PROJECT_PATH"
             - scheme: test
             - destination: platform=iOS Simulator,name=iPhone 11 Plus,OS=latest
             - test_plan: my_plan
         - deploy-to-bitrise-io:
     ```

  

:::note[Headless mode]

From Xcode 9 onwards, tests are run in headless mode by default: this means that the simulator will run in the background only. To change it, go to the Step’s Debug input group and set the **Run the simulator in headless mode** input’s value to `no`. However, with this option, tests will take more time.

```yaml
- xcode-test:
    inputs:
      - headless_mode: 'no'
```

:::

:::important[Using xcpretty]

The `xcpretty` output tool does not support parallel tests. If parallel tests are enabled in your project, go to the Step’s **xcodebuild log formatting** input group and set the **Log formatter** input’s value to `xcodebuild` or `xcbeautify`.

```yaml
- xcode-test:
    inputs:
      - log_formatter: xcbeautify
```

:::

## Rerunning failed tests

In **Xcode Test for iOS** versions earlier than 6.0.0, the **Should retry test on failure?** input in the **Test repetition** section ran `xcodebuild` one more time when a test failed, rerunning ALL your tests, not just the failed ones. The input no longer exists from version 6.0.0.

To rerun only the failed tests, use the **Test Repetition Mode** input with the `retry_on_failure` option selected: [Test Repetitions](#test-repetitions). This test repetition feature is available in the **Xcode Test for iOS** Step from version 3.0.0 and above.

## Test Repetitions

[Xcode’s test repetition modes](https://developer.apple.com/videos/play/wwdc2021/10296/) are available with the [Xcode Test for iOS Step](https://www.bitrise.io/integrations/steps/xcode-test) on stacks running Xcode 13 and above on Bitrise. With test repetitions, you can run any type of tests multiple times in various ways such as retry on failure, until failure and until max repetitions.

The **Xcode Test for iOS** Step’s **Test Repetitions Mode (Available in Xcode 13+)** input offers the following options:

- `none`: The tests won’t repeat.
- `until_failure`: Repeats a test until the test fails or until the maximum repetition. The default number of test runs is three.
- `retry_on_failure`: Failed tests run until they succeed or until the repetition number you specify. The default number of test repetitions is three.
- `up_until_maximum_repetitions`: Reruns all tests until maximum test repetition is reached regardless of the test outcomes.

The default option is `retry_on_failure` from version 6.0.0. In earlier versions, the default is `none`.

Please note that these options are only available from **Xcode Test for iOS** version 3.0.0 and above.

With the **Maximum Test Repetitions (Available in Xcode 13+)** input you can specify the maximum number of test repetitions. Please note that you have to add a greater number than one if the **Test Repetition Mode (Available in Xcode 13+)** input is set to other than `none`.

Enable the **Relaunch Tests for Each Repetition (Available in Xcode 13+)** input to launch tests in a completely new process for each repetition. The default is `no`.
