Module: RSpec::Illustrate

Defined in:
lib/rspec/illustrate.rb,
lib/rspec/illustrate/version.rb

Overview

Extension module to RSpec that allows you to define illustrations in the examples that will be forwarded to the output formatter.

Specifications

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

Constant Summary

VERSION =

The version used by gemspec

"0.2.5"

Instance Method Summary (collapse)

Instance Method Details

- (Object) illustrate(content, *args)

Stores an object in the surrounding example's metadata, which can be used by the output formatter as an illustration for the example.

Parameters:

  • content

    The object that will act as an illustration.

  • args (Array<Hash, Symbol>)

    Additional options.

Returns:

  • The given illustration object.

Specifications:

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}


14
15
16
17
18
19
20
21
22
23
24
25
26
27
# File 'lib/rspec/illustrate.rb', line 14

def illustrate(content, *args)
  illustration = { :text => content.to_s,
                   :show_when_passed  => true,
                   :show_when_failed => true,
                   :show_when_pending => true }

  args.each{|arg|
    illustration[arg] = true if arg.is_a?(Symbol)
    illustration.merge!(arg) if arg.kind_of?(Hash)
  }

  RSpec.current_example.[:illustrations] << illustration
  content
end