Name: xctool
Owner: AutoScout24
Owner: AutoScout24
Description: xctool is a replacement for Apple's xcodebuild that makes it easier to build and test iOS and Mac projects.
Created: 2013-11-20 12:23:16.0
Updated: 2015-04-27 13:26:00.0
Pushed: 2016-08-04 15:48:53.0
Homepage: null
Size: 6559
Language: Objective-C
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
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.
[ Features • Requirements • Usage • Continuous Integration • Reporters • Configuration • Contributing • Known Issues & Tips • License ]
xctool is drop-in replacement for xcodebuild that adds a few extra features:
Structured output of build and test results.
xctool captures all build events and test results as structured JSON objects. If you're building a continuous 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:
Faster, parallelized test runs.
xctool can optionally run all of your test bundles in parallel, speeding up your test runs significantly. At Facebook, we've seen 2x and 3x speed ups by parallelizing our runs.
Use the -parallelize
option with run-tests or test to enable.
See Parallelizing Test Runs for more info.
Written in Objective-C.
xctool is written in Objective-C. Mac OS X and iOS developers can easily submit new features and fix any bugs they may encounter without learning a new language. We very much welcome pull requests!
xctool can be installed from homebrew via
install xctool
or can be downloaded and run via the xctool.sh command.
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:
/to/xctool.sh -help
Building products with xctool is the same as building them with xcodebuild.
If you use workspaces and schemes:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
ild
If you use projects and schemes:
/to/xctool.sh \
roject YourProject.xcodeproj \
cheme YourScheme \
ild
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.
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:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
st
To build and run just the tests in a specific target, use the -only
option:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
st -only SomeTestTarget
You can go further and just run a specific test class:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
st -only SomeTestTarget:SomeTestClass
Or, even further and run just a single test method:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
st -only SomeTestTarget:SomeTestClass/testSomeMethod
You can also specify prefix matching for classes or test methods:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
st -only SomeTestTarget:SomeTestClassPrefix*,SomeTestClass/testSomeMethodPrefix*
You can also run tests against a different SDK:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
st -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.
For example:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
ild-tests
You can optionally just build a single test target with the -only
option:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
ild-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:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
n-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
.
Optionally you can specify -testTimeout
when running tests. When an individual test hits this timeout, it is considered a failure rather than waiting indefinitely. This can prevent your test run from deadlocking forever due to misbehaving tests.
By default application tests will wait at most 30 seconds for the simulator
to launch. If you need to change this timeout, use the -launch-timeout
option.
xctool can optionally run unit tests in parallel, making better use of otherwise idle CPU cores. At Facebook, we've seen 2x and 3x gains by parallelizing our test runs.
To allow test bundles to run concurrently, use the -parallelize
option:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
n-tests -parallelize
The above gives you parallelism, but you're bounded by your slowest test bundle. For example, if you had two test bundles ('A' and 'B'), but 'B' took 10 times as long to run because it contained 10 times as many tests, then the above parallelism won't help much.
You can get further gains by breaking your test execution into buckets
using the -logicTestBucketSize
option:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
n-tests -parallelize -logicTestBucketSize 20
The above will break your test execution into buckets of 20 test cases each, and those bundles will be run concurrently. If some of your test bundles are much larger than others, this will help even things out and speed up the overall test run.
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:
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.
Travis CI is a very popular continuous
integration system offered for free to Open Source projects. It
integrates well with Github, and it now uses xctool as the default
build and test tool for Objective-C projects. Once you have set up your
shared Scheme for use with xctool, you will need to configure a
.travis.yml
file.
If you're using workspaces, your .travis.yml
might be:
uage: objective-c
e_workspace: path/to/YourApp.xcworkspace
e_scheme: YourApp
If you're using projects, your .travis.yml
might be:
uage: objective-c
e_project: path/to/YourApp.xcodeproj
e_scheme: YourApp
For more flexibility, you can also control how Travis installs and invokes xctool:
uage: objective-c
re_install:
- brew update
- brew install xctool
pt: xctool -workspace MyApp.xcworkspace -scheme MyApp test
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. If you do not specify any reporters yourself, xctool uses
the pretty
and user-notifications
reporters by default.
Overwrite is disabled on the pretty
reporter when xctool does not
detect a TTY. This can be overridden by setting XCTOOL_FORCE_TTY
in
the environment. The user-notifications
reporter will not be used
if xctool detects that the build is being run by Travis CI or TeamCity,
i.e. TRAVIS=true
, TEAMCITY_VERSION
in the environment.
You can choose your own reporters with the -reporter
option:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
eporter plain \
ild
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:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
eporter plain:/path/to/plain-output.txt \
ild
You can use as many reporters as you like; just use the -reporter
option multiple times.
You can also implement your own reporters using whatever language you like. Reporters in xctool are separate executables that read JSON objects from STDIN and write formatted results to STDOUT.
You can invoke reporters by passing their full path via the -reporter
option:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
eporter /path/to/your/reporter \
st
For example, here's a simple reporter in Python that outputs a period for every passing test and an exclamation mark for every failing test:
sr/bin/python
rt fileinput
rt json
rt sys
line in fileinput.input():
obj = json.loads(line)
if obj['event'] == 'end-test':
if obj['succeeded']:
sys.stdout.write('.')
else:
sys.stdout.write('!')
stdout.write('\n')
If you're writing a reporter in Objective-C, you'll find the
Reporter
class helpful - 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 precedence 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.
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.
Mostly the same, but use branches in the main xctool repo if you prefer. It's a nice way to keep things together.
Use shared schemes and disable the Autocreate Schemes feature.
Xcode has two kinds of schemes: shared, and user. User schemes are
the default, and they're stored under a folder called USERNAME.xcuserdatad
,
which most people correctly add to their .gitignore.
Use shared schemes instead, and commit them to your repo. This way everyone on your team (and your build server) are working from the same information, and are building in the same way.
Make sure simulators run in a GUI context.
If you are running xctool
in continuous integration, the user account
calling xctool
must have an active GUI context.
If not, the simulator will fail to start with cryptic warnings like:
d to install the test host app 'com.myapp.test' but failed.
aring test environment failed.
ST_BUNDLE FAILED_TO_START]
e was a problem starting the test bundle: Simulator 'iPhone 6' was not prepared: Failed for unknown reason.
did not run: Simulator 'iPhone 6' was not prepared: Failed for unknown reason.
-01-21 12:02:19.296 xcodebuild[35135:875297] iPhoneSimulator: Timed out waiting 120 seconds for simulator to boot, current state is 1.
ing failed:
target MyProjectTests encountered an error (Timed out waiting 120 seconds for simulator to boot, current state is 1.
Note that the
same holds true with xcodebuild
…this is not xctool
specific.
For more information, see this post by Jason Jarrett.
Copyright 2014-present 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.
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.
[ Features • Requirements • Usage • Continuous Integration • Reporters • Configuration • Contributing • Known Issues & Tips • License ]
xctool is drop-in replacement for xcodebuild that adds a few extra features:
Structured output of build and test results.
xctool captures all build events and test results as structured JSON objects. If you're building a continuous 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:
Faster, parallelized test runs.
xctool can optionally run all of your test bundles in parallel, speeding up your test runs significantly. At Facebook, we've seen 2x and 3x speed ups by parallelizing our runs.
Use the -parallelize
option with run-tests or test to enable.
See Parallelizing Test Runs for more info.
Written in Objective-C.
xctool is written in Objective-C. Mac OS X and iOS developers can easily submit new features and fix any bugs they may encounter without learning a new language. We very much welcome pull requests!
xctool can be installed from homebrew via
install xctool
or can be downloaded and run via the xctool.sh command.
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:
/to/xctool.sh -help
Building products with xctool is the same as building them with xcodebuild.
If you use workspaces and schemes:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
ild
If you use projects and schemes:
/to/xctool.sh \
roject YourProject.xcodeproj \
cheme YourScheme \
ild
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.
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:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
st
To build and run just the tests in a specific target, use the -only
option:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
st -only SomeTestTarget
You can go further and just run a specific test class:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
st -only SomeTestTarget:SomeTestClass
Or, even further and run just a single test method:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
st -only SomeTestTarget:SomeTestClass/testSomeMethod
You can also specify prefix matching for classes or test methods:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
st -only SomeTestTarget:SomeTestClassPrefix*,SomeTestClass/testSomeMethodPrefix*
You can also run tests against a different SDK:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
st -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.
For example:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
ild-tests
You can optionally just build a single test target with the -only
option:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
ild-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:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
n-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
.
Optionally you can specify -testTimeout
when running tests. When an individual test hits this timeout, it is considered a failure rather than waiting indefinitely. This can prevent your test run from deadlocking forever due to misbehaving tests.
By default application tests will wait at most 30 seconds for the simulator
to launch. If you need to change this timeout, use the -launch-timeout
option.
xctool can optionally run unit tests in parallel, making better use of otherwise idle CPU cores. At Facebook, we've seen 2x and 3x gains by parallelizing our test runs.
To allow test bundles to run concurrently, use the -parallelize
option:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
n-tests -parallelize
The above gives you parallelism, but you're bounded by your slowest test bundle. For example, if you had two test bundles ('A' and 'B'), but 'B' took 10 times as long to run because it contained 10 times as many tests, then the above parallelism won't help much.
You can get further gains by breaking your test execution into buckets
using the -logicTestBucketSize
option:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
n-tests -parallelize -logicTestBucketSize 20
The above will break your test execution into buckets of 20 test cases each, and those bundles will be run concurrently. If some of your test bundles are much larger than others, this will help even things out and speed up the overall test run.
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:
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.
Travis CI is a very popular continuous
integration system offered for free to Open Source projects. It
integrates well with Github, and it now uses xctool as the default
build and test tool for Objective-C projects. Once you have set up your
shared Scheme for use with xctool, you will need to configure a
.travis.yml
file.
If you're using workspaces, your .travis.yml
might be:
uage: objective-c
e_workspace: path/to/YourApp.xcworkspace
e_scheme: YourApp
If you're using projects, your .travis.yml
might be:
uage: objective-c
e_project: path/to/YourApp.xcodeproj
e_scheme: YourApp
For more flexibility, you can also control how Travis installs and invokes xctool:
uage: objective-c
re_install:
- brew update
- brew install xctool
pt: xctool -workspace MyApp.xcworkspace -scheme MyApp test
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. If you do not specify any reporters yourself, xctool uses
the pretty
and user-notifications
reporters by default.
Overwrite is disabled on the pretty
reporter when xctool does not
detect a TTY. This can be overridden by setting XCTOOL_FORCE_TTY
in
the environment. The user-notifications
reporter will not be used
if xctool detects that the build is being run by Travis CI or TeamCity,
i.e. TRAVIS=true
, TEAMCITY_VERSION
in the environment.
You can choose your own reporters with the -reporter
option:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
eporter plain \
ild
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:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
eporter plain:/path/to/plain-output.txt \
ild
You can use as many reporters as you like; just use the -reporter
option multiple times.
You can also implement your own reporters using whatever language you like. Reporters in xctool are separate executables that read JSON objects from STDIN and write formatted results to STDOUT.
You can invoke reporters by passing their full path via the -reporter
option:
/to/xctool.sh \
orkspace YourWorkspace.xcworkspace \
cheme YourScheme \
eporter /path/to/your/reporter \
st
For example, here's a simple reporter in Python that outputs a period for every passing test and an exclamation mark for every failing test:
sr/bin/python
rt fileinput
rt json
rt sys
line in fileinput.input():
obj = json.loads(line)
if obj['event'] == 'end-test':
if obj['succeeded']:
sys.stdout.write('.')
else:
sys.stdout.write('!')
stdout.write('\n')
If you're writing a reporter in Objective-C, you'll find the
Reporter
class helpful - 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 precedence 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.
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.
Mostly the same, but use branches in the main xctool repo if you prefer. It's a nice way to keep things together.
Use shared schemes and disable the Autocreate Schemes feature.
Xcode has two kinds of schemes: shared, and user. User schemes are
the default, and they're stored under a folder called USERNAME.xcuserdatad
,
which most people correctly add to their .gitignore.
Use shared schemes instead, and commit them to your repo. This way everyone on your team (and your build server) are working from the same information, and are building in the same way.
Make sure simulators run in a GUI context.
If you are running xctool
in continuous integration, the user account
calling xctool
must have an active GUI context.
If not, the simulator will fail to start with cryptic warnings like:
d to install the test host app 'com.myapp.test' but failed.
aring test environment failed.
ST_BUNDLE FAILED_TO_START]
e was a problem starting the test bundle: Simulator 'iPhone 6' was not prepared: Failed for unknown reason.
did not run: Simulator 'iPhone 6' was not prepared: Failed for unknown reason.
-01-21 12:02:19.296 xcodebuild[35135:875297] iPhoneSimulator: Timed out waiting 120 seconds for simulator to boot, current state is 1.
ing failed:
target MyProjectTests encountered an error (Timed out waiting 120 seconds for simulator to boot, current state is 1.
Note that the
same holds true with xcodebuild
…this is not xctool
specific.
For more information, see this post by Jason Jarrett.
Copyright 2014-present 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.