CI::Reporter is an add-on to Test::Unit, RSpec and Cucumber that allows you to generate XML reports of your test, spec and/or feature runs. The resulting files can be read by a continuous integration system that understands Ant's JUnit report XML format, thus allowing your CI system to track test/spec successes and failures.
Installation¶ ↑
CI::Reporter is available as a gem. To install the gem, use the usual gem command:
gem install ci_reporter
Usage¶ ↑
CI::Reporter works best with projects that
use a Rakefile
along with the standard
Rake::TestTask
or
Spec::Rake::SpecTask/RSpec::Core::RakeTask
tasks for running
tests or examples, respectively. In this fashion, it hooks into
Test::Unit
or RSpec
using environment variables
recognized by these custom tasks to inject the CI::Reporter code into the test or spec runs.
If you're using the Rails skip to next section.
-
To use CI::Reporter, simply add one of the following lines to your Rakefile:
require 'ci/reporter/rake/rspec' # use this if you're using RSpec require 'ci/reporter/rake/cucumber' # use this if you're using Cucumber require 'ci/reporter/rake/spinach' # use this if you're using Spinach require 'ci/reporter/rake/test_unit' # use this if you're using Test::Unit require 'ci/reporter/rake/minitest' # use this if you're using Ruby 1.9 or minitest
Note: If you use both cucumber and spinach, you are likely to see strange errors, due to `gherkin` and `gherkin-ruby` both being loaded. So, you should choose only one of cucumber and spinach.
-
Next, either modify your Rakefile to make the
ci:setup:rspec
,ci:setup:cucumber
,ci:setup:testunit
orci:setup:minitest
task a dependency of your test tasks, or run one of these rake tasks:rake ci:setup:testunit test rake ci:setup:minitest test rake ci:setup:rspec spec rake ci:setup:cucumber features rake ci:setup:spinach features
Rails¶ ↑
If you use rails-rspec gem all you need to do is to create new rake task lib/tasks/ci_reporter.rake:
if ENV['GENERATE_REPORTS'] == 'true' require 'ci/reporter/rake/rspec' task :spec => 'ci:setup:rspec' end
And then you can either inject this variable in you CI or simply call rspec passing this as one of the parameters:
rspec ... GENERATE_REPORTS=true
RSpec Formatters¶ ↑
CI::Reporter has seperate Rake tasks for each builtin RSpec formatter. Depending upon which formatter you would like, call the following corresponding task.
- Progress (default)
-
ci:setup:rspec
- Base
-
ci:setup:rspecbase
- Documentation
-
ci:setup:rspecdoc
Jenkins setup¶ ↑
-
Tick the box labelled “Publish JUnit test result report” in the job configuration
-
Enter “test/reports/*.xml,spec/reports/*.xml” in the “Test report XMLs” field (adjust this to suit which tests you are running)
Report files are written, by default, to the test/reports
,
features/reports
or spec/reports
subdirectory of
your project. If you wish to customize the location, simply set the
environment variable CI_REPORTS (either in the environment, on the Rake
command line, or in your Rakefile) to the location where they should go.
Advanced Usage¶ ↑
If you don't have control over the Rakefile or don't want to modify
it, CI::Reporter has a substitute rake file
that you can specify on the command-line. It assumes that the main project
rake file is called Rakefile
and lives in the current
directory. Run like so:
rake -f GEM_PATH/stub.rake ci:setup:testunit test rake -f GEM_PATH/stub.rake ci:setup:minitest test rake -f GEM_PATH/stub.rake ci:setup:rspec spec rake -f GEM_PATH/stub.rake ci:setup:cucumber features rake -f GEM_PATH/stub.rake ci:setup:spinach features
If for some reason you can't use the above technique to inject CI::Reporter (e.g., you're not using Rake), you'll have to do one of these:
-
If you're using
Test::Unit
, ensure theci/reporter/rake/test_unit_loader.rb
file is loaded or required at some point before the tests are run. -
If you're using
RSpec
, you'll need to pass the following arguments to thespec
command:--require GEM_PATH/lib/ci/reporter/rake/rspec_loader --format CI::Reporter::RSpec
-
If you're using Cucumber, you'll need to cheat slightly so that Cucumber's step definition autoloading will still work. Instead of calling the
cucumber
script directly, run:ruby -r GEM_PATH/lib/ci/reporter/rake/cucumber_loader -S cucumber --format CI::Reporter::Cucumber
-
If you're using Spinach, you'll want to do this:
ruby -r GEM_PATH/lib/ci/reporter/rake/spinach_loader -S spinach
There's a bit of a chicken and egg problem because rubygems needs to be
loaded before you can require any CI::Reporter files. If you cringe hard-coding
a full path to a specific version of the gem, you can also copy the
cucumber_loader
file into your project and require it directly
– the contents are version-agnostic and are not likely to change in future
releases.
Environment Variables¶ ↑
-
CI_REPORTS
: if set, points to a directory where report files will be written. -
CI_CAPTURE
: if set to value “off”, stdout/stderr capture will be disabled.
Travis Build Status
¶ ↑
Source¶ ↑
You can get the CI::Reporter source using Git, in any of the following ways:
git clone git://git.caldersphere.net/ci_reporter.git git clone git://github.com/nicksieger/ci_reporter.git
You can also download a tarball of the latest CI::Reporter source at github.com/nicksieger/ci_reporter/.
License¶ ↑
This software is released under an MIT license. For details, see the LICENSE.txt file included with the distribution. The software is copyright © 2006-2010 Nick Sieger <nicksieger@gmail.com>.