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.
xctool is 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
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.
You'll need Xcode's Command Line Tools installed. From Xcode, install via Xcode → Preferences → Downloads.
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:
Building products with xctool is the same as building them with xcodebuild.
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
just as they do with xcodebuild.
NOTE: xctool doesn't support directly building targets using
-target; you must use schemes.
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
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
While test will build and run your tests, sometimes you want to build them without running them. For that, use build-tests.
path/to/xctool.sh \ -workspace YourWorkspace.xcworkspace \ -scheme YourScheme \ build-tests
You can optionally just build a single test target with the
path/to/xctool.sh \ -workspace YourWorkspace.xcworkspace \ -scheme YourScheme \ build-tests -only SomeTestTarget
If you've already built tests with build-tests, you can use run-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
-only. And, you can change which SDK they're run against
xctool is an excellent choice for running your tests under a continuous integration server such as Travis CI or Jenkins. In order to your run your tests within a continuous integration environment, you must create Shared Schemes for your application target and ensure that all dependencies (such as CocoaPods) are added explicitly to the Scheme. To do so:
- Open up the Manage Schemes sheet by selecting the Product menu > Schemes > Manage Schemes...
- Locate your application target in the list. Ensure that the Shared checkbox in far right hand column of the sheet is checked.
- If your application or test targets include cross-project dependencies such as CocoaPods, then you will need to ensure that they have been
configured as explicit dependencies. To do so:
- Highlight your application target and hit the Edit... button to open the Scheme editing sheet.
- Click the Build tab in the left-hand panel of the Scheme editor.
- Click the + button and add each dependency to the project. CocoaPods will appears as static library named Pods.
- Drag the dependency above your application target so that it is built first.
You will now have a new file in the xcshareddata/xcschemes directory underneath your Xcode project. This is the shared Scheme that you just configured. Check this file into your repository and xctool will be able to find and execute your tests on the next CI build.
Example Travis CI Configuration
Travis CI is a very popular continuous integration system offered for free to Open Source projects.
It integrates well with Github and is easy to configure. Once you have set up your shared Scheme for use with xctool, you will
need to configure a
.travis.yml file. To make it a bit easier to get started with Travis, you may want to base your
script off of the following example:
language: objective-c before_install: - brew update - brew install xctool --HEAD script: xctool -workspace MyApp.xcworkspace -scheme 'MyApp' test
You will obviously need to replace 'MyApp.xcworkspace' and 'MyApp' with the name of your project and shared Xcode scheme, respectively.
You can learn more about the Travis CI environment for iOS and OS X application by referring to the About OS X Travis CI Environment document and find in-depth documentation for configuring your project by consulting the Getting Started page.
xctool has reporters that output build and test results in different
formats. By default, xctool always uses the
You can change or add reporters with the
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
- 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.
- junit: produces a JUnit/xUnit compatible XML file with test results.
- json-stream: a stream of build/test events as JSON dictionaries, one per line (example output).
- json-compilation-database: outputs a JSON Compilation Database of build events which can be used by Clang Tooling based tools, e.g. OCLint.
You could also add your own Reporter - see Reporter.h.
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.
Bug fixes, improvements, and especially new Reporter implementations are welcome. Before submitting a pull request, please be sure to sign the Facebook Contributor License Agreement. We can't accept pull requests unless it's been signed.
- Make a feature branch: git checkout -b my-feature
- Make your feature. Keep things tidy so you have one commit per self contained change (squashing can help).
- Push your branch to your fork: git push -u origin my-feature
- Open GitHub, under "Your recently pushed branches", click Pull Request for my-feature.
Be sure to use a separate feature branch and pull request for every self-contained feature. If you need to make changes from feedback, make the changes in place rather than layering on commits (use interactive rebase to edit your earlier commits). Then use git push --force origin my-feature to update your pull request.
Workflow (for Facebook people, other committers)
Mostly the same, but use branches in the main xctool repo if you prefer. It's a nice way to keep things together.
- Make a feature branch: git checkout -b myusername/my-feature
- Push your branch: git push -u origin myusername/my-feature
- Open GitHub to facebook/xctool, under "Your recently pushed branches", click Pull Request for myusername/my-feature.
- Find Implicit Dependencies is not supported. If you get unexplained linker or compile errors in xctool but not in Xcode, it might be this. Xcode.app has a mode where it will try to infer dependencies between your projects and make sure dependent projects are built first. Unfortunately it looks like this logic only exists in Xcode.app. The workaround is to setup correct Target Dependencies or to add the necessary targets to your scheme ahead of the targets that require them. More info in issue #16.
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:
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.