# RSpec JUnit Formatter

[![Build results](http://img.shields.io/travis/sj26/rspec_junit_formatter/master.svg)](https://travis-ci.org/sj26/rspec_junit_formatter) 
[![Gem version](http://img.shields.io/gem/v/rspec_junit_formatter.svg)](https://rubygems.org/gems/rspec_junit_formatter)

[RSpec][rspec] 2 & 3 results that [Jenkins][jenkins] can read. Probably a few other CI services, too.

Inspired by the work of [Diego Souza][dgvncsz0f] on [RSpec Formatters][dgvncsz0f/rspec_formatters] after frustration with [CI Reporter][ci_reporter].

## Usage

Install the gem:

```sh
gem install rspec_junit_formatter
```

Use it:

```sh
rspec --format RspecJunitFormatter --out rspec.xml
```

You'll get an XML file `rspec.xml` with your results in it.

You can use it in combination with other [formatters][rspec-formatters], too:

```sh
rspec --format progress --format RspecJunitFormatter --out rspec.xml
```

### Using in your project with Bundler

Add it to your Gemfile if you're using [Bundler][bundler]. Put it in the same groups as rspec.

```ruby
group :test do
  gem "rspec"
  gem "rspec_junit_formatter"
end
```

Put the same arguments as the commands above in [your `.rspec`][rspec-file]:

```sh
--format RspecJunitFormatter
--out rspec.xml
```

### Parallel tests

For use with `parallel_tests`, add `$TEST_ENV_NUMBER` in the output file option (in `.rspec` or `.rspec_parallel`) to avoid concurrent process write conflicts.

```sh
--format RspecJunitFormatter
--out tmp/rspec<%= ENV["TEST_ENV_NUMBER"] %>.xml
```

The formatter includes `$TEST_ENV_NUMBER` in the test suite name within the XML, too.

## Caveats

 * XML can only represent a [limited subset of characters][xml-charsets] which
   excludes null bytes and most control characters. This gem will use character
   entities where possible and fall back to replacing invalid characters with
   Ruby-like escape codes otherwise. For example, the null byte becomes `\0`.

## Roadmap

 * It would be nice to split things up into individual test suites, although
   would this correspond to example groups? The subject? The spec file? Not
   sure yet.

## License

The MIT License, see [LICENSE][license].

  [rspec]: http://rspec.info/
  [rspec-formatters]: https://relishapp.com/rspec/rspec-core/v/3-6/docs/formatters
  [rspec-file]: https://relishapp.com/rspec/rspec-core/v/3-6/docs/configuration/read-command-line-configuration-options-from-files
  [jenkins]: http://jenkins-ci.org/
  [dgvncsz0f]: https://github.com/dgvncsz0f
  [dgvncsz0f/rspec_formatters]: https://github.com/dgvncsz0f/rspec_formatters
  [ci_reporter]: https://github.com/nicksieger/ci_reporter
  [bundler]: http://gembundler.com/
  [fuubar]: http://jeffkreeftmeijer.com/2010/fuubar-the-instafailing-rspec-progress-bar-formatter/
  [license]: https://github.com/sj26/rspec-junit-formatter/blob/master/LICENSE
  [xml-charsets]: https://www.w3.org/TR/xml/#charsets