RSpec::Illustrate

allows you to pass illustrative objects to the output formatter.

Given the file 'spec/example.rb'

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.to_s, :label=>"Given the array"
      illustrate expected.to_s, :label=>"After sort it looks like this"
      illustrate actual.to_s, :show_when_passed=>false

      expect(actual).to eq(expected)
    end
  end
end

Output from the formatter

Array
  #sort
    should sort the array
    --- Given the array ---
    [3, 1, 2]
    --- After sort it looks like this ---
    [1, 2, 3]

Finished in 0.00173 seconds (files took 0.0939 seconds to load)
1 example, 0 failures

when an example is executed from RSpec

stores an empty list of illustrations (Hashes) in the metadata

RSpec::Illustrate#illustrate
when invoked from within an RSpec example

stores the illustration as a Hash in the list in the metadata

the Hash that corresponds to the illustration

contains the content and the default settings

{:text=>"This is an example illustration",
 :show_when_passed=>true,
 :show_when_failed=>true,
 :show_when_pending=>true}
when providing arguments in the 'illustrate' statement

should merge the arguments with the hash

{:text=>"An example with arguments",
 :show_when_passed=>true,
 :show_when_failed=>true,
 :show_when_pending=>true,
 :my_option=>true,
 :my_arg=>42}
RSpec::Formatters#filter

should only return hashes where the key is set to true

Given illustration_1

{:text=>"This is illustration 1",
 :show_when_passed=>true,
 :show_when_failed=>true,
 :show_when_pending=>true}

Given illustration_2

{:text=>"This is illustration 2",
 :show_when_passed=>false,
 :show_when_failed=>true,
 :show_when_pending=>true}

Given illustration_3

{:text=>"This is illustration 3",
 :show_when_passed=>true,
 :show_when_failed=>false,
 :show_when_pending=>true}

Given illustration_4

{:text=>"This is illustration 4",
 :show_when_passed=>true,
 :show_when_failed=>true,
 :show_when_pending=>false}

Expected when filtered by :show_when_passed)

[:illustration_1, :illustration_3, :illustration_4]

Expected when filtered by :show_when_failed)

[:illustration_1, :illustration_2, :illustration_4]

Expected when filtered by :show_when_pending)

[:illustration_1, :illustration_2, :illustration_3]
RSpec::Core::Configuration#illustration_formatter
behaves like a formatter configuration

should return a Proc

should take an illustration Hash and return a text representation

should be configurable by assigning a new proc

RSpec::Core::Configuration#illustration_html_formatter

should render content from hash key :html instead of :text if present

behaves like a formatter configuration

should return a Proc

should take an illustration Hash and return a text representation

should be configurable by assigning a new proc