A plugin to RSpec and YARD that allows you to define illustrative objects in your examples that will be forwarded to the output formatter. The results can be imported into YARD, which makes your generated specs and documentation more readable, illustrative, and explanatory.
Source code at https://github.com/ErikSchlyter/rspec-illustrate.
Documentation at http://www.erisc.se/rspec-illustrate.
Add this line to your application's Gemfile:
And then execute:
Or install it yourself as:
$ gem install rspec-illustrate
Within an example you use the
illustrate statement to define an object that
will be passed to the output formatter. You can also provide additional options
if you want to set a label or define when the formatter should write the
illustration (e.g. omit if the example fails, etc.)
Given the file
require 'rspec/illustrate' describe Array do describe "#sort" do it "should sort the array" do given = [3, 1, 2] expected = [1, 2, 3] actual = given.sort illustrate given, :label=>"Given the array" illustrate expected, :label=>"After sort it looks like this" illustrate actual, :show_when_passed=>false expect(actual).to eq(expected) end end end
You execute RSpec with a formatter that takes the illustrations into consideration, i.e.:
$ rspec -f RSpec::Formatters::IllustratedDocumentationFormatter
The output would be something like this:
Array #sort should sort the array --- Given the array --- [3, 1, 2] --- After sort it looks like this --- [1, 2, 3]
Import test results and illustrations into YARD
RSpec-Illustrate comes with a template for YARD and an RSpec formatter that outputs a specific HTML format that the template can import.
To create the test report you have to execute RSpec with the specific formatter.
You need to add the following to your
require "rspec/core/rake_task" RSpec::Core::RakeTask.new(:spec) do |t| t.rspec_opts = "--format RSpec::Formatters::YARD --out ./doc/api.rspec" end
Keep in mind that the file must end with
.rspec in order for the template to
understand it's an RSpec output file. You load the template by invoking
require rspec/illustrate/yard and you import it by giving it to YARD as a normal input
file. Add the following to your
require 'yard' require 'rspec/illustrate/yard' YARD::Rake::YardocTask.new(:doc) do |t| t.files = ['lib/**/*.rb', 'doc/api.rspec'] end task :doc => [:spec]
You can also include it as an extra file if you want to view it as a complete
test report (it is HTML after all). Simply add it to the list of extra files by
adding it after the
require 'yard' require 'rspec/illustrate/yard' YARD::Rake::YardocTask.new(:doc) do |t| t.files = ['lib/**/*.rb', 'doc/api.rspec', '-', 'doc/api.rspec'] end task :doc => [:spec]
After checking out the repo, run
bin/setup to install dependencies.
To install this gem onto your local machine, run
bundle exec rake install. To
release a new version, update the version number in
version.rb, and then run
bundle exec rake release to create a git tag for the version, push git commits
and tags, and push the
.gem file to rubygems.org.
- Fork it ( https://github.com/ErikSchlyter/rspec-illustrate/fork )
- Create your feature branch (
git checkout -b my-new-feature)
- Commit your changes (
git commit -am 'Add some feature')
- Push to the branch (
git push origin my-new-feature)
- Create a new Pull Request