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.
CI::Reporter is available as a gem. To install the gem, use the usual gem command:
gem install ci_reporter
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 plugin, step 1 is unnecessary; skip to step
2.
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
or
ci: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
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.
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 the
ci/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 the spec
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.
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.
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/.
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>.