ci_reporter: A Ruby repository from pivotal-cloudplanner

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 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
```

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 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.

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 <img src=“https://secure.travis-ci.org/nicksieger/ci_reporter.png”/>¶ ↑

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/.

pivotal-cloudplanner/ci_reporter