step.yml

title: Xcode Build for testing for iOS
summary: Performs xcodebuild's build-for-testing action
description: |-
  The Step runs Xcode's `xcodebuild` command with the `build-for-testing` option. This builds your app and associated tests so that you can, for example, upload it to a third-party testing service to run your tests on a real device.
  The Step also creates an `.xctestrun` file.
  To be able to run your tests on a real device it needs code signing. The **Automatic code signing method** Step input allows you to log you into your Apple Developer account based on the [Apple service connection you provide on Bitrise](https://devcenter.bitrise.io/en/accounts/connecting-to-services/apple-services-connection.html) and download any provisioning profiles needed for your project based on the **Distribution method**.
  Please note that the **Automatic code signing method** input is by default set to `off`, so if you need code signing, select either the `api-key` or the `apple-id`option of the input.

  ### Configuring the Step
  Before you start:
  - Make sure you have connected your [Apple Service account to Bitrise](https://devcenter.bitrise.io/en/accounts/connecting-to-services/apple-services-connection.html).
  Alternatively, you can upload certificates and profiles to Bitrise manually, then use the **Certificate and Profile Installer** Step before this Step.
  - Make sure certificates are uploaded to Bitrise's **Code Signing** tab. The right provisioning profiles are automatically downloaded from Apple as part of the automatic code signing process.

  To configure the Step:
  1. **Project (or Workspace) path**: This is the path where the `.xcodeproj` or `.xcworkspace` files are localed.
  2. **Scheme**: Add the scheme name you wish to build for testing.
  3. **Build Configuration**: If not specified, the default Build Configuration will be used. The input value sets xcodebuild's `-configuration` option.
  4. **Device destination specifier**: Destination specifier describes the device to use as a destination. The input value sets xcodebuild's `-destination` option.

  Under **xcodebuild configuration**
  5. **Build settings (xcconfig)**:  Build settings to override the project's build settings. Can be the contents, file path or empty.
  6. **Additional options for the xcodebuild command**:  Additional options to be added to the executed xcodebuild command.

  Under **Xcode build log formatting**:
  1. **Log formatter**: Defines how `xcodebuild` command's log is formatted. Available options: `xcpretty`: The xcodebuild command's output will be prettified by xcpretty. `xcodebuild`: Only the last 20 lines of raw xcodebuild output will be visible in the build log. The raw xcodebuild log is exported in both cases.

  Under **Automatic code signing**:
  1. **Automatic code signing method**: Select the Apple service connection you want to use for code signing. Available options: `off` if you don't do automatic code signing, `api-key` [if you use API key authorization](https://devcenter.bitrise.io/en/accounts/connecting-to-services/connecting-to-an-apple-service-with-api-key.html), and `apple-id` [if you use Apple ID authorization](https://devcenter.bitrise.io/en/accounts/connecting-to-services/connecting-to-an-apple-service-with-apple-id.html).
  2. **Register test devices on the Apple Developer Portal**: If this input is set, the Step will register the known test devices on Bitrise from team members with the Apple Developer Portal. Note that setting this to `yes` may cause devices to be registered against your limited quantity of test devices in the Apple Developer Portal, which can only be removed once annually during your renewal window.
  3. **The minimum days the Provisioning Profile should be valid**: If this input is set to >0, the managed Provisioning Profile will be renewed if it expires within the configured number of days. Otherwise the Step renews the managed Provisioning Profile if it is expired.
  4. The **Code signing certificate URL**, the **Code signing certificate passphrase**, the **Keychain path**, and the **Keychain password** inputs are automatically populated if certificates are uploaded to Bitrise's **Code Signing** tab. If you store your files in a private repo, you can manually edit these fields.

  If you want to set the Apple service connection credentials on the step-level (instead of using the one configured in the App Settings), use the Step inputs in the **App Store Connect connection override** category. Note that this only works if **Automatic code signing method** is set to `api-key`.

  Under **Step Output configuration**:
  1. **Output directory path**: This directory contains the generated artifacts.

  Under **Caching**:
  1. **Enable collecting cache content**: Defines what cache content should be automatically collected. Available options are:
    - `none`: Disable collecting cache content
    - `swift_packages`: Collect Swift PM packages added to the Xcode project

  Under Debugging:
  1. **Verbose logging***: You can set this input to `yes` to produce more informative logs.
website: https://github.com/bitrise-steplib/steps-xcode-build-for-test
source_code_url: https://github.com/bitrise-steplib/steps-xcode-build-for-test
support_url: https://github.com/bitrise-steplib/steps-xcode-build-for-test/issues

project_type_tags:
- ios
- react-native
- cordova
- ionic

type_tags:
- build

toolkit:
  go:
    package_name: github.com/bitrise-steplib/steps-xcode-build-for-test

inputs:
- project_path: $BITRISE_PROJECT_PATH
  opts:
    title: Project path
    summary: Xcode Project (`.xcodeproj`) or Workspace (`.xcworkspace`) path.
    description: |-
      Xcode Project (`.xcodeproj`) or Workspace (`.xcworkspace`) path.

      The input value sets xcodebuild's `-project` or `-workspace` option.
    is_required: true

- scheme: $BITRISE_SCHEME
  opts:
    title: Scheme
    summary: Xcode Scheme name.
    description: |-
      Xcode Scheme name.

      The input value sets xcodebuild's `-scheme` option.
    is_required: true

- configuration: Debug
  opts:
    title: Build Configuration
    summary: Xcode Build Configuration.
    description: |-
      Xcode Build Configuration.

      If not specified, the default Build Configuration will be used.

      The input value sets xcodebuild's `-configuration` option.
    is_required: true

- destination: generic/platform=iOS
  opts:
    title: Device destination specifier
    summary: Destination specifier describes the device to use as a destination.
    description: |-
      Destination specifier describes the device to use as a destination.

      Recommended values:
      - `generic/platform=iOS` to build tests for physical devices
      - `generic/platform=iOS Simulator` to build tests for Simulators

      The input value sets xcodebuild's `-destination` option.
    is_required: true

- test_plan:
  opts:
    title: Test Plan
    summary: Build tests for a specific Test Plan associated with the Scheme.
    description: |-
      Build tests for a specific Test Plan associated with the Scheme.

      Leave this input empty to build all the Test Plans or Test Targets associated with the Scheme.

      The input value sets xcodebuild's `-testPlan` option.

# xcodebuild configuration

- xcconfig_content: COMPILER_INDEX_STORE_ENABLE = NO
  opts:
    category: xcodebuild configuration
    title: Build settings (xcconfig)
    summary: Build settings to override the project's build settings, using xcodebuild's `-xcconfig` option.
    description: |-
      Build settings to override the project's build settings, using xcodebuild's `-xcconfig` option.

      You can't define `-xcconfig` option in `Additional options for the xcodebuild command` if this input is set.

      If empty, no setting is changed. When set it can be either:
      1.  Existing `.xcconfig` file path.

          Example:

          `./ios-sample/ios-sample/Configurations/Dev.xcconfig`

      2.  The contents of a newly created temporary `.xcconfig` file. (This is the default.)

          Build settings must be separated by newline character (`\n`).

          Example:
          ```
          COMPILER_INDEX_STORE_ENABLE = NO
          ONLY_ACTIVE_ARCH[config=Debug][sdk=*][arch=*] = YES
          ```

- xcodebuild_options:
  opts:
    category: xcodebuild configuration
    title: Additional options for the xcodebuild command
    summary: Additional options to be added to the executed xcodebuild command.
    description: |-
      Additional options to be added to the executed xcodebuild command.

      Prefer using `Build settings (xcconfig)` input for specifying `-xcconfig` option. You can't use both.

# xcodebuild log formatting

- log_formatter: xcpretty
  opts:
    category: xcodebuild log formatting
    title: Log formatter
    summary: Defines how xcodebuild command's log is formatted.
    description: |-
      Defines how xcodebuild command's log is formatted.

      Available options:
      - `xcpretty`: The xcodebuild command’s output will be prettified by xcpretty.
      - `xcodebuild`: Only the last 20 lines of raw xcodebuild output will be visible in the build log.

      The raw xcodebuild log will be exported in both cases.
    value_options:
    - xcpretty
    - xcodebuild
    is_required: true

# Automatic code signing

- automatic_code_signing: "off"
  opts:
    category: Automatic code signing
    title: Automatic code signing method
    summary: This input determines which Bitrise Apple service connection should be used for automatic code signing.
    description: |-
      This input determines which Bitrise Apple service connection should be used for automatic code signing.

      Available values:
      - `off`: Do not do any auto code signing.
      - `api-key`: [Bitrise Apple Service connection with API Key](https://devcenter.bitrise.io/getting-started/connecting-to-services/setting-up-connection-to-an-apple-service-with-api-key/).
      - `apple-id`: [Bitrise Apple Service connection with Apple ID](https://devcenter.bitrise.io/getting-started/connecting-to-services/connecting-to-an-apple-service-with-apple-id/).
    value_options:
    - "off"
    - api-key
    - apple-id
    is_required: true

- register_test_devices: "no"
  opts:
    category: Automatic code signing
    title: Register test devices on the Apple Developer Portal
    summary: If this input is set, the Step will register the known test devices on Bitrise from team members with the Apple Developer Portal.
    description: |-
      If this input is set, the Step will register the known test devices on Bitrise from team members with the Apple Developer Portal.

      Note that setting this to yes may cause devices to be registered against your limited quantity of test devices in the Apple Developer Portal, which can only be removed once annually during your renewal window.
    is_required: true
    value_options:
    - "yes"
    - "no"

- test_device_list_path:
  opts:
    category: Automatic code signing
    title: Path of file containing the devices to be registered
    summary: If this input is set, the Step will register the listed devices from this file with the Apple Developer Portal.
    description: |-
      If this input is set, the Step will register the listed devices from this file with the Apple Developer Portal.

      The format of the file is a comma separated list of the identifiers. For example:
      `00000000–0000000000000001,00000000–0000000000000002,00000000–0000000000000003`

      And in the above example the registered devices appear with the name of `Device 1`, `Device 2` and `Device 3` in the Apple Developer Portal.

      Note that setting this will have a higher priority than the Bitrise provided devices list.

- min_profile_validity: "0"
  opts:
    category: Automatic code signing
    title: The minimum days the Provisioning Profile should be valid
    summary: If this input is set to >0, the managed Provisioning Profile will be renewed if it expires within the configured number of days.
    description: |-
      If this input is set to >0, the managed Provisioning Profile will be renewed if it expires within the configured number of days.

      Otherwise the Step renews the managed Provisioning Profile if it is expired.
    is_required: true

- apple_team_id: ""
  opts:
    category: Automatic code signing
    title: Developer Portal team ID
    summary: The Apple Developer Portal team to use for downloading code signing assets.
    description: |-
      The Apple Developer Portal team to use for downloading code signing assets.

      Defining this is only required when Automatic Code Signing is set to `apple-id` and the connected account belongs to multiple teams.

- certificate_url_list: $BITRISE_CERTIFICATE_URL
  opts:
    category: Automatic code signing
    title: Code signing certificate URL
    summary: URL of the code signing certificate to download.
    description: |-
      URL of the code signing certificate to download.

      Multiple URLs can be specified, separated by a pipe (`|`) character.

      Local file path can be specified, using the `file://` URL scheme.
    is_required: true
    is_sensitive: true

- passphrase_list: $BITRISE_CERTIFICATE_PASSPHRASE
  opts:
    category: Automatic code signing
    title: Code signing certificate passphrase
    summary: Passphrases for the provided code signing certificates.
    description: |-
      Passphrases for the provided code signing certificates.

      Specify as many passphrases as many Code signing certificate URL provided, separated by a pipe (`|`) character.

      Certificates without a passphrase: for using a single certificate, leave this step input empty. For multiple certificates, use the separator as if there was a passphrase (examples: `pass|`, `|pass|`, `|`)
    is_required: false  # A single cert with an empty passphrase is allowed too
    is_sensitive: true

- keychain_path: $HOME/Library/Keychains/login.keychain
  opts:
    category: Automatic code signing
    title: Keychain path
    summary: Path to the Keychain where the code signing certificates will be installed.
    is_required: true
    is_dont_change_value: true

- keychain_password: $BITRISE_KEYCHAIN_PASSWORD
  opts:
    category: Automatic code signing
    title: Keychain password
    summary: Password for the provided Keychain.
    is_required: true
    is_sensitive: true
    is_dont_change_value: true

# Step output configuration

- output_dir: $BITRISE_DEPLOY_DIR
  opts:
    category: Step output configuration
    title: Output directory path
    summary: This directory will contain the generated artifacts.
    is_required: true

# Caching

- cache_level: swift_packages
  opts:
    category: Caching
    title: Enable collecting cache content
    summary: Defines what cache content should be automatically collected.
    description: |-
      Defines what cache content should be automatically collected.

      Available options:
      - `none`: Disable collecting cache content.
      - `swift_packages`: Collect Swift PM packages added to the Xcode project.
    value_options:
    - none
    - swift_packages
    is_required: true

# App Store Connect connection override

- api_key_path:
  opts:
    category: App Store Connect connection override
    title: App Store Connect API private key
    summary: Local path or remote URL to the private key (p8 file). This overrides the Bitrise-managed API connection.
    description: |-
      Local path or remote URL to the private key (p8 file) for App Store Connect API.
      This overrides the Bitrise-managed API connection, only set this input if you want to control the API connection
      on a step-level. Most of the time it's easier to set up the connection on the App Settings page on Bitrise.
      The input value can be a file path (eg. `$TMPDIR/private_key.p8`) or an HTTPS URL.
      This input only takes effect if the other two connection override inputs are set too (`api_key_id`, `api_key_issuer_id`).
    is_required: false

- api_key_id:
  opts:
    category: App Store Connect connection override
    title: App Store Connect API key ID
    summary: Private key ID used for App Store Connect authentication. This overrides the Bitrise-managed API connection.
    description: |-
      Private key ID used for App Store Connect authentication.
      This overrides the Bitrise-managed API connection, only set this input if you want to control the API connection
      on a step-level. Most of the time it's easier to set up the connection on the App Settings page on Bitrise.
      This input only takes effect if the other two connection override inputs are set too (`api_key_path`, `api_key_issuer_id`).
    is_required: false

- api_key_issuer_id:
  opts:
    category: App Store Connect connection override
    title: App Store Connect API issuer ID
    summary: Private key issuer ID used for App Store Connect authentication. This overrides the Bitrise-managed API connection.
    description: |-
      Private key issuer ID used for App Store Connect authentication.
      This overrides the Bitrise-managed API connection, only set this input if you want to control the API connection
      on a step-level. Most of the time it's easier to set up the connection on the App Settings page on Bitrise.
      This input only takes effect if the other two connection override inputs are set too (`api_key_path`, `api_key_id`).
    is_required: false

# Debugging

- verbose_log: "no"
  opts:
    category: Debugging
    title: Enable verbose logging
    summary: If this input is set, the Step will print additional logs for debugging.
    value_options:
    - "yes"
    - "no"
    is_required: true

outputs:
- BITRISE_TEST_BUNDLE_PATH:
  opts:
    title: Test Bundle directory
    summary: Directory of the built targets' binaries and built associated tests.

- BITRISE_TEST_BUNDLE_ZIP_PATH:
  opts:
    title: Zipped Test Bundle directory
    summary: Zipped directory of the built targets' binaries and built associated tests.

- BITRISE_XCTESTRUN_FILE_PATH:
  opts:
    title: xctestrun file path
    summary: File path of the built xctestrun file.
    description: |-
      File path of the built xctestrun file (example: `$SYMROOT/ios-simple-objc_iphoneos12.0-arm64e.xctestrun`).

      If `Test Plan` Step Input is set BITRISE_XCTESTRUN_FILE_PATH points to the provided Test Plan's xctestrun file.
      Otherwise points to the scheme's default Test Plan's xctestrun file (or to the first xctestrun without default Test Plan).

- BITRISE_XCODE_RAW_RESULT_TEXT_PATH:
  opts:
    title: "`xcodebuild build-for-testing` command log file path"
    summary: File path of the raw `xcodebuild build-for-testing` command log.