class RSpec::Core::Example

Wrapper for an instance of a subclass of {ExampleGroup}. An instance of `RSpec::Core::Example` is returned by example definition methods such as {ExampleGroup.it it} and is yielded to the {ExampleGroup.it it}, {Hooks#before before}, {Hooks#after after}, {Hooks#around around}, {MemoizedHelpers::ClassMethods#let let} and {MemoizedHelpers::ClassMethods#subject subject} blocks.

This allows us to provide rich metadata about each individual example without adding tons of methods directly to the ExampleGroup that users may inadvertantly redefine.

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

@example

RSpec.configure do |config|
  config.before do |example|
    log example.description
  end

  config.after do |example|
    log example.description
  end

  config.around do |example|
    log example.description
    example.run
  end
end

shared_examples "auditable" do
  it "does something" do
    log "#{example.full_description}: #{auditable.inspect}"
    auditable.should do_something
  end
end

@see ExampleGroup @note Example blocks are evaluated in the context of an instance

of an `ExampleGroup`, not in the context of an instance of `Example`.

Attributes

clock[RW]

@attr @private

example_group_instance[R]

@attr_reader @private

Returns the #example_group_instance that provides the context for running this example.

exception[R]

@attr_reader

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

metadata[R]

@attr_reader

Returns the metadata object associated with this example.

Public Class Methods

delegate_to_metadata(key) click to toggle source

@private

Used to define methods that delegate to this example's metadata.

# File lib/rspec/core/example.rb, line 48
def self.delegate_to_metadata(key)
  define_method(key) { @metadata[key] }
end
new(example_group_class, description, user_metadata, example_block=nil) click to toggle source

Creates a new instance of Example. @param example_group_class [Class] the subclass of ExampleGroup in which

this Example is declared

@param description [String] the String passed to the `it` method (or

alias)

@param user_metadata [Hash] additional args passed to `it` to be used as

metadata

@param example_block [Proc] the block of code that represents the

example

@api private

# File lib/rspec/core/example.rb, line 136
def initialize(example_group_class, description, user_metadata, example_block=nil)
  @example_group_class = example_group_class
  @example_block       = example_block

  @metadata = Metadata::ExampleHash.create(
    @example_group_class.metadata, user_metadata, description, example_block
  )

  @example_group_instance = @exception = nil
  @clock = RSpec::Core::Time
end

Public Instance Methods

description() click to toggle source

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.

# File lib/rspec/core/example.rb, line 76
def description
  description = if metadata[:description].to_s.empty?
                  location_description
                else
                  metadata[:description]
                end

  RSpec.configuration.format_docstrings_block.call(description)
end
example_group() click to toggle source

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

# File lib/rspec/core/example.rb, line 150
def example_group
  @example_group_class
end
fail_with_exception(reporter, exception) click to toggle source

@private

Used internally to set an exception and fail without actually executing the example when an exception is raised in before(:context).

# File lib/rspec/core/example.rb, line 308
def fail_with_exception(reporter, exception)
  start(reporter)
  set_exception(exception)
  finish(reporter)
end
inspect_output() click to toggle source

Returns a description of the example that always includes the location.

# File lib/rspec/core/example.rb, line 87
def inspect_output
  inspect_output = "\"#{description}\""
  unless metadata[:description].to_s.empty?
    inspect_output << " (#{location})"
  end
  inspect_output
end
instance_exec(*args, &block) click to toggle source

@private

# File lib/rspec/core/example.rb, line 332
def instance_exec(*args, &block)
  @example_group_instance.instance_exec(*args, &block)
end
instance_exec_with_rescue(context, &block) click to toggle source

@private

# File lib/rspec/core/example.rb, line 325
def instance_exec_with_rescue(context, &block)
  @example_group_instance.instance_exec(self, &block)
rescue Exception => e
  set_exception(e, context)
end
rerun_argument() click to toggle source

Returns the argument that can be passed to the `rspec` command to rerun this example.

# File lib/rspec/core/example.rb, line 96
def rerun_argument
  loaded_spec_files = RSpec.configuration.loaded_spec_files

  Metadata.ascending(metadata) do |meta|
    return meta[:location] if loaded_spec_files.include?(meta[:absolute_file_path])
  end
end
run(example_group_instance, reporter) click to toggle source

@api private instance_execs the block passed to the constructor in the context of the instance of {ExampleGroup}. @param #example_group_instance the instance of an ExampleGroup subclass

# File lib/rspec/core/example.rb, line 161
def run(example_group_instance, reporter)
  @example_group_instance = example_group_instance
  hooks.register_global_singleton_context_hooks(self, RSpec.configuration.hooks)
  RSpec.configuration.configure_example(self)
  RSpec.current_example = self

  start(reporter)
  Pending.mark_pending!(self, pending) if pending?

  begin
    if skipped?
      Pending.mark_pending! self, skip
    elsif !RSpec.configuration.dry_run?
      with_around_and_singleton_context_hooks do
        begin
          run_before_example
          @example_group_instance.instance_exec(self, &@example_block)

          if pending?
            Pending.mark_fixed! self

            raise Pending::PendingExampleFixedError,
                  'Expected example to fail since it is pending, but it passed.',
                  [location]
          end
        rescue Pending::SkipDeclaredInExample
          # no-op, required metadata has already been set by the `skip`
          # method.
        rescue Exception => e
          set_exception(e)
        ensure
          run_after_example
        end
      end
    end
  rescue Exception => e
    set_exception(e)
  ensure
    ExampleGroup.each_instance_variable_for_example(@example_group_instance) do |ivar|
      @example_group_instance.instance_variable_set(ivar, nil)
    end
    @example_group_instance = nil
  end

  finish(reporter)
ensure
  RSpec.current_example = nil
end
set_exception(exception, context=nil) click to toggle source

@private

Used internally to set an exception in an after hook, which captures the exception but doesn't raise it.

# File lib/rspec/core/example.rb, line 283
    def set_exception(exception, context=nil)
      if pending? && !(Pending::PendingExampleFixedError === exception)
        execution_result.pending_exception = exception
      else
        if @exception
          # An error has already been set; we don't want to override it,
          # but we also don't want silence the error, so let's print it.
          msg = <<-EOS

An error occurred #{context}
  #{exception.class}: #{exception.message}
  occurred at #{exception.backtrace.first}

          EOS
          RSpec.configuration.reporter.message(msg)
        end

        @exception ||= exception
      end
    end
skip_with_exception(reporter, exception) click to toggle source

@private

Used internally to skip without actually executing the example when skip is used in before(:context).

# File lib/rspec/core/example.rb, line 318
def skip_with_exception(reporter, exception)
  start(reporter)
  Pending.mark_skipped! self, exception.argument
  finish(reporter)
end

Private Instance Methods

assign_generated_description() click to toggle source
# File lib/rspec/core/example.rb, line 414
def assign_generated_description
  if metadata[:description].empty? && (description = generate_description)
    metadata[:description] = description
    metadata[:full_description] << description
  end
ensure
  RSpec::Matchers.clear_generated_description
end
finish(reporter) click to toggle source
# File lib/rspec/core/example.rb, line 353
def finish(reporter)
  pending_message = execution_result.pending_message

  if @exception
    record_finished :failed
    execution_result.exception = @exception
    reporter.example_failed self
    false
  elsif pending_message
    record_finished :pending
    execution_result.pending_message = pending_message
    reporter.example_pending self
    true
  else
    record_finished :passed
    reporter.example_passed self
    true
  end
end
generate_description() click to toggle source
# File lib/rspec/core/example.rb, line 423
def generate_description
  RSpec::Matchers.generated_description
rescue Exception => e
  location_description + " (Got an error when generating description "            "from matcher: #{e.class}: #{e.message} -- #{e.backtrace.first})"
end
hooks() click to toggle source
# File lib/rspec/core/example.rb, line 338
def hooks
  example_group_instance.singleton_class.hooks
end
location_description() click to toggle source
# File lib/rspec/core/example.rb, line 430
def location_description
  "example at #{location}"
end
mocks_need_verification?() click to toggle source
# File lib/rspec/core/example.rb, line 410
def mocks_need_verification?
  exception.nil? || execution_result.pending_fixed?
end
record_finished(status) click to toggle source
# File lib/rspec/core/example.rb, line 373
def record_finished(status)
  execution_result.record_finished(status, clock.now)
end
run_after_example() click to toggle source
# File lib/rspec/core/example.rb, line 390
def run_after_example
  assign_generated_description if defined?(::RSpec::Matchers)
  hooks.run(:after, :example, self)
  verify_mocks
ensure
  @example_group_instance.teardown_mocks_for_rspec
end
run_before_example() click to toggle source
# File lib/rspec/core/example.rb, line 377
def run_before_example
  @example_group_instance.setup_mocks_for_rspec
  hooks.run(:before, :example, self)
end
skip_message() click to toggle source
# File lib/rspec/core/example.rb, line 434
def skip_message
  if String === skip
    skip
  else
    Pending::NO_REASON_GIVEN
  end
end
start(reporter) click to toggle source
# File lib/rspec/core/example.rb, line 348
def start(reporter)
  reporter.example_started(self)
  execution_result.started_at = clock.now
end
verify_mocks() click to toggle source
# File lib/rspec/core/example.rb, line 398
def verify_mocks
  @example_group_instance.verify_mocks_for_rspec if mocks_need_verification?
rescue Exception => e
  if pending?
    execution_result.pending_fixed = false
    execution_result.pending_exception = e
    @exception = nil
  else
    set_exception(e)
  end
end
with_around_and_singleton_context_hooks() { || ... } click to toggle source
# File lib/rspec/core/example.rb, line 382
def with_around_and_singleton_context_hooks
  singleton_context_hooks_host = example_group_instance.singleton_class
  singleton_context_hooks_host.run_before_context_hooks(example_group_instance)
  with_around_example_hooks { yield }
ensure
  singleton_context_hooks_host.run_after_context_hooks(example_group_instance)
end
with_around_example_hooks() { || ... } click to toggle source
# File lib/rspec/core/example.rb, line 342
def with_around_example_hooks
  hooks.run(:around, :example, self) { yield }
rescue Exception => e
  set_exception(e, "in an `around(:example)` hook")
end