Xcodebuild Formatters

fastlane uses formatters to make the output from xcodebuild easier to read. xcodebuild is used by scan, gym, and snapshot. The output of xcodebuild is piped into a formatter by fastlane. Below is an example of how fastlane uses formatters:

$ xcodebuild [flags] | xcbeautify

There are two main formatters the community is using. These are:

Specifying formatter with fastlane 2.201.0 and above

As of fastlane 2.201.0, scan, gym, and snapshot all offer a new xcodebuild_formatter option.

This option will default to xcbeautify if it's installed; otherwise, it will fallback to xcpretty. However, scan, gym, and snapshot will end up using xcpretty if any options are set that customize it with xcpretty (e.g., xcpretty_args).

scan(
  xcodebuild_formatter: "xcbeautify"
)

scan(
  xcodebuild_formatter: "xcpretty"
)

# Specify a local installation of xcbeautify
scan(
  xcodebuild_formatter: "/custom/path/to/xcbeautify"
)

# Specify your own custom formatter
scan(
  xcodebuild_formatter: "/custom/path/to/my_formatter"
)

fastlane has some custom logic if xcbeautify or xcpretty are specified but it will essentially run:

$ xcodebuild [flags] | <xcodebuild_formatter>

Formatters

xcbeautify

xcbeautify is now the recommended formatter to use. fastlane users are required to install xcbeautify themselves if they want to use it.

$ brew install xcbeautify

xcbeautify is the recommended because:

  • Faster than xcpretty
  • Supports Xcode's new build system output
  • Supports Xcode's parallel testing output
  • Supports formatting Swift Package Manager output

xcpretty

Historically, fastlane was tightly integrated with xcpretty. xcpretty is a RubyGem and a dependency of fastlane. This was the best option for fastlane as there were no extra steps for installing or using this formatter.

xcpretty also did more than formatting. It used the xcodebuild output to:

  • Generate a JUnit report
  • Generate an HTML report
  • Generate a JSON compilation database

Before 2.201.0, scan used xcpretty to generate these files and determine success/failure with xcpretty output
As of 2.201.0, scan will only generate these if xcodebuild_formatter is using xcpretty but now use trainer to parse test results to determine success/failure