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

#initialize(example_group_class, description, metadata, example_block = nil) ⇒ Example

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

#exception ⇒ Object (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

#metadata ⇒ Object (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

.procsy(metadata, &proc) ⇒ Object

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.



150
151
152
 
# File 'lib/rspec/core/example.rb', line 150

def self.procsy(metadata, &proc)
  proc.extend(Procsy).with(metadata)
end

Instance Method Details

#description ⇒ Object

Returns the string submitted to example or its aliases (e.g. specify, it, etc). If no string is submitted (e.g. it { is_expected.to 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

#example_group ⇒ Object

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



95
96
97
 
# File 'lib/rspec/core/example.rb', line 95

def example_group
  @example_group_class
end

#options ⇒ Object

Deprecated.

access options via metadata instead



87
88
89
90
91
 
# File 'lib/rspec/core/example.rb', line 87

def options
  RSpec.deprecate("`RSpec::Core::Example#options`",
                  :replacement => "`RSpec::Core::Example#metadata`")
  @options
end

#run(example_group_instance, reporter) ⇒ Object

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



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
141
142
143
144
 
# File 'lib/rspec/core/example.rb', line 105

def run(example_group_instance, reporter)
  @example_group_instance = example_group_instance
  RSpec.current_example = self

  start(reporter)

  begin
    unless pending
      with_around_each_hooks do
        begin
          run_before_each
          @example_group_instance.instance_eval_with_args(self, &@example_block)
        rescue Pending::SkipDeclaredInExample => 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)
ensure
  RSpec.current_example = nil
end