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, , example_block=nil)
  @example_group_class, @options, @example_block = example_group_class, , example_block
  @metadata  = @example_group_class..for_example(description, )
  @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
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.

145
146
147
# File 'lib/rspec/core/example.rb', line 145
def self.procsy(, &proc)
  proc.extend(Procsy).with()
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 { 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 = [:description].to_s.empty? ? "example at #{location}" : [: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.

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

- (Object) options

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

- (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

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
# 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
          assign_generated_description
          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
  end
  finish(reporter)
ensure
  RSpec.current_example = nil
end