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
Spec::Rake::SpecTask/RSpec::Core::RakeTask tasks for running tests or examples, respectively. In this fashion, it hooks into
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:minitesttask 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
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 your CI or simply call rspec passing this as one of the parameters:
rspec ... GENERATE_REPORTS=true
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)
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
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.rbfile 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
--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
cucumberscript 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 <[email protected]>.