Class: RSpec::Core::Example

Inherits:
Object
  • Object
show all
Defined in:
lib/rspec/core/example.rb

Overview

Wrapper for an instance of a subclass of ExampleGroup. An instance of Example is returned by the example method exposed to examples, before and after hooks, and yielded to around hooks.

Useful for configuring logging and/or taking some action based on the state of an example's metadata.

Examples:

RSpec.configure do |config|
  config.before do
    log example.description
  end
  config.after do
    log example.description
  end
  config.around do |ex|
    log example.description
    ex.run
  end
end
shared_examples "auditable" do
  it "does something" do
    log "#{example.full_description}: #{auditable.inspect}"
    auditable.should do_something
  end
end

See Also:

Defined Under Namespace

Modules: Procsy

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Example) initialize(example_group_class, description, metadata, example_block = nil)

Creates a new instance of Example.

Parameters:

  • example_group_class —

    the subclass of ExampleGroup in which this Example is declared

  • description —

    the String passed to the it method (or alias)

  • metadata —

    additional args passed to it to be used as metadata

  • example_block (defaults to: nil) —

    the block of code that represents the example

79
80
81
82
83
84
 
# File 'lib/rspec/core/example.rb', line 79
def initialize(example_group_class, description, metadata, example_block=nil)
  @example_group_class, @options, @example_block = example_group_class, metadata, example_block
  @metadata  = @example_group_class.metadata.for_example(description, metadata)
  @example_group_instance = @exception = nil
  @pending_declared_in_example = false
end

Instance Attribute Details

- (Object) exception (readonly)

Returns the first exception raised in the context of running this example (nil if no exception is raised)

60
61
62
 
# File 'lib/rspec/core/example.rb', line 60
def exception
  @exception
end

- (Object) metadata (readonly)

Returns the metadata object associated with this example.

65
66
67
 
# File 'lib/rspec/core/example.rb', line 65
def metadata
  @metadata
end

Class Method Details

+ (Object) procsy(metadata)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Wraps the example block in a Proc so it can invoked using run or call in around hooks.

146
147
148
 
# File 'lib/rspec/core/example.rb', line 146
def self.procsy(metadata, &proc)
  proc.extend(Procsy).with(metadata)
end

Instance Method Details

- (Object) description

Returns the string submitted to example or its aliases (e.g. specify, it, etc). If no string is submitted (e.g. it { should do_something }) it returns the message generated by the matcher if there is one, otherwise returns a message including the location of the example.

51
52
53
54
 
# File 'lib/rspec/core/example.rb', line 51
def description
  description = metadata[:description].to_s.empty? ? "example at #{location}" : metadata[:description]
  RSpec.configuration.format_docstrings_block.call(description)
end

- (Object) example_group

Returns the example group class that provides the context for running this example.

93
94
95
 
# File 'lib/rspec/core/example.rb', line 93
def example_group
  @example_group_class
end

- (Object) options

Deprecated.

access options via metadata instead

87
88
89
 
# File 'lib/rspec/core/example.rb', line 87
def options
  @options
end

- (Object) run(example_group_instance, reporter)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

instance_evals the block passed to the constructor in the context of the instance of RSpec::Core::ExampleGroup.

Parameters:

  • example_group_instance —

    the instance of an ExampleGroup subclass

103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/rspec/core/example.rb', line 103
def run(example_group_instance, reporter)
  @example_group_instance = example_group_instance
  @example_group_instance.example = self
  start(reporter)
  begin
    unless pending
      with_around_each_hooks do
        begin
          run_before_each
          @example_group_instance.instance_eval(&@example_block)
        rescue Pending::PendingDeclaredInExample => e
          @pending_declared_in_example = e.message
        rescue Exception => e
          set_exception(e)
        ensure
          run_after_each
        end
      end
    end
  rescue Exception => e
    set_exception(e)
  ensure
    @example_group_instance.instance_variables.each do |ivar|
      @example_group_instance.instance_variable_set(ivar, nil)
    end
    @example_group_instance = nil
    begin
      assign_generated_description
    rescue Exception => e
      set_exception(e, "while assigning the example description")
    end
  end
  finish(reporter)
end