xctool

xctool is a replacement for Apple's xcodebuild that makes it easier to build and test iOS and Mac products. It's especially helpful for continuous integration.

It's a drop-in replacement for xcodebuild that adds a few extra features:

• Runs the same tests as Xcode.app.

  Surprisingly, Apple's command-line xcodebuild tool does not run your product's tests the same way as Xcode.app. xcodebuild doesn't understand which targets in your scheme are test targets, which test suites or cases you might have disabled in your scheme, or how to run simulator-based, application tests.

  If you use application tests, you've probably seen xcodebuild skipping them with this message:

  Skipping tests; the iPhoneSimulator platform does not currently support
  application-hosted tests (TEST_HOST set).

  xctool fixes this - it looks at your Xcode scheme and is able to reproduce the same test run you would get with Xcode.app via Cmd-U or Product → Test, including running application tests that require the iOS simulator.

• Structured output of build and test results.

  xctool captures all build events and test results as structured JSON objects. If you're building a continous integration system, this means you don't have to regex parse xcodebuild output anymore.

  Try one of the Reporters to customize the output or get the full event stream with the -reporter json-stream option.

• Human-friendly, ANSI-colored output.

  xcodebuild is incredibly verbose, printing the full compile command and output for every source file. By default, xctool is only verbose if something goes wrong, making it much easier to identify where the problems are.

  Example:

Requirements

You'll need Xcode's Command Line Tools installed. From Xcode, install via Xcode → Preferences → Downloads.

Usage

xctool's commands and options are mostly a superset of xcodebuild's. In most cases, you can just swap xcodebuild with xctool and things will run as expected but with more attractive output.

You can always get help and a full list of options with:

path/to/xctool.sh -help

Building

Building products with xctool is the same as building them withxcodebuild.

If you use workspaces and schemes:

path/to/xctool.sh \
 -workspace YourWorkspace.xcworkspace \
 -scheme YourScheme \
 build

If you use projects and schemes:

path/to/xctool.sh \
 -project YourProject.xcodeproj \
 -scheme YourScheme \
 build

All of the common options like -configuration, -sdk, -arch work just as they do with xcodebuild.

NOTE: xctool doesn't support directly building targets using-target; you must use schemes.

Testing

xctool has a test action which knows how to build and run the tests in your scheme. You can optionally limit what tests are run or change the SDK they're run against.

To build and run all tests in your scheme, you would use:

path/to/xctool.sh \
 -workspace YourWorkspace.xcworkspace \
 -scheme YourScheme \
 test

To build and run just the tests in a specific target, use the -only option:

path/to/xctool.sh \
 -workspace YourWorkspace.xcworkspace \
 -scheme YourScheme \
 test -only SomeTestTarget

You can go further and just run a specific test class:

path/to/xctool.sh \
 -workspace YourWorkspace.xcworkspace \
 -scheme YourScheme \
 test -only SomeTestTarget:SomeTestClass

Or, even further and run just a single test method:

path/to/xctool.sh \
 -workspace YourWorkspace.xcworkspace \
 -scheme YourScheme \
 test -only SomeTestTarget:SomeTestClass/testSomeMethod

You can also run tests against a different SDK:

path/to/xctool.sh \
 -workspace YourWorkspace.xcworkspace \
 -scheme YourScheme \
 test -test-sdk iphonesimulator5.1

Building Tests

While test will build and run your tests, sometimes you want to build them without running them. For that, use build-tests.

For example:

path/to/xctool.sh \
 -workspace YourWorkspace.xcworkspace \
 -scheme YourScheme \
 build-tests

You can optionally just build a single test target with the -only option:

path/to/xctool.sh \
 -workspace YourWorkspace.xcworkspace \
 -scheme YourScheme \
 build-tests -only SomeTestTarget

Running Tests

If you've already built tests with build-tests, you can userun-tests to run them. This is helpful if you want to build tests once but run them against multiple SDKs.

To run all tests, you would use:

path/to/xctool.sh \
 -workspace YourWorkspace.xcworkspace \
 -scheme YourScheme \
 run-tests

Just as with the test action, you can limit which tests are run with the -only. And, you can change which SDK they're run against with the -test-sdk.

Reporters

xctool has reporters that output build and test results in different formats. By default, xctool always uses the pretty reporter.

You can change or add reporters with the -reporter option:

path/to/xctool.sh \
 -workspace YourWorkspace.xcworkspace \
 -scheme YourScheme \
 -reporter plain \
 build

By default, reporters output to standard out, but you can also direct the output to a file by adding :OUTPUT_PATH after the reporter name:

path/to/xctool.sh \
 -workspace YourWorkspace.xcworkspace \
 -scheme YourScheme \
 -reporter plain:/path/to/plain-output.txt \
 build

Included Reporters

• pretty: a text-based reporter that uses ANSI colors and unicode symbols for pretty output (the default).
• plain: like pretty, but with with no colors or unicode.
• phabricator: outputs a JSON array of build/test results which can be fed into the Phabricator code-review tool.
• json-stream: a stream of build/test events as JSON dictionaries, one per line (example output).

You could also add your own Reporter - seeReporter.h.

Configuration (.xctool-args)

If you routinely need to pass many arguments to xctool on the command-line, you can use an .xctool-args file to speed up your workflow. If xctool finds an .xctool-args file in the current directory, it will automatically pre-populate its arguments from there.

The format is just a JSON array of arguments:

[
 "-workspace", "YourWorkspace.xcworkspace",
 "-scheme", "YourScheme",
 "-configuration", "Debug",
 "-sdk", "iphonesimulator",
 "-arch", "i386"
]

Any extra arguments you pass on the command-line will take precendence over those in the .xctool-args file.

Contributing

Bug fixes, improvements, and especially newReporter implementations are welcome. Submit a pull request.

License

Copyright 2013 Facebook

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this work except in compliance with the License. You may obtain a copy of the License in the LICENSE file, or at:

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.