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
@attr @private
@attr_reader @private
Returns the #example_group_instance that provides the context for running this example.
@attr_reader
Returns the first exception raised in the context of running this example (nil if no exception is raised).
@attr_reader
Returns the metadata object associated with this example.
@return [RSpec::Core::Reporter] the current reporter for the example
Public Class Methods
@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
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 153 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, example_group_class.method(:next_runnable_index_for), description, example_block ) # This should perhaps be done in `Metadata::ExampleHash.create`, # but the logic there has no knowledge of `RSpec.world` and we # want to keep it that way. It's easier to just assign it here. @metadata[:last_run_status] = RSpec.configuration.last_run_statuses[id] @example_group_instance = @exception = nil @clock = RSpec::Core::Time @reporter = RSpec::Core::NullReporter end
Public Instance Methods
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
@private
The exception that will be displayed to the user – either the failure of the example or the `pending_exception` if the example is pending.
# File lib/rspec/core/example.rb, line 309 def display_exception @exception || execution_result.pending_exception end
@private
Assigns the exception that will be displayed to the user – either the failure of the example or the `pending_exception` if the example is pending.
# File lib/rspec/core/example.rb, line 317 def display_exception=(ex) if pending? && !(Pending::PendingExampleFixedError === ex) @exception = nil execution_result.pending_fixed = false execution_result.pending_exception = ex else @exception = ex end end
Returns the example group class that provides the context for running this example.
# File lib/rspec/core/example.rb, line 178 def example_group @example_group_class end
@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 360 def fail_with_exception(reporter, exception) start(reporter) set_exception(exception) finish(reporter) end
@return [String] the unique id of this example. Pass
this at the command line to re-run this exact example.
# File lib/rspec/core/example.rb, line 117 def id @id ||= Metadata.id_from(metadata) end
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
@private
# File lib/rspec/core/example.rb, line 377 def instance_exec(*args, &block) @example_group_instance.instance_exec(*args, &block) end
Returns the location-based argument that can be passed to the `rspec` command to rerun this example.
# File lib/rspec/core/example.rb, line 96 def location_rerun_argument @location_rerun_argument ||= begin 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 end
Returns the location-based argument that can be passed to the `rspec` command to rerun this example.
@deprecated Use {#location_rerun_argument} instead. @note If there are multiple examples identified by this location, they will use {#id}
to rerun instead, but this method will still return the location (that's why it is deprecated!).
# File lib/rspec/core/example.rb, line 111 def rerun_argument location_rerun_argument end
@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 189 def run(example_group_instance, reporter) @example_group_instance = example_group_instance @reporter = reporter 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 @example_group_instance = nil # if you love something... let it go end finish(reporter) ensure RSpec.current_example = nil end
@private
Used to set the exception when `aggregate_failures` fails.
# File lib/rspec/core/example.rb, line 346 def set_aggregate_failures_exception(exception) return set_exception(exception) unless display_exception exception = RSpec::Core::MultipleExceptionError::InterfaceTag.for(exception) exception.add display_exception self.display_exception = exception end
@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 333 def set_exception(exception) return self.display_exception = exception unless display_exception unless RSpec::Core::MultipleExceptionError === display_exception self.display_exception = RSpec::Core::MultipleExceptionError.new(display_exception) end display_exception.add exception end
@private
Used internally to skip without actually executing the example when skip is used in before(:context).
# File lib/rspec/core/example.rb, line 370 def skip_with_exception(reporter, exception) start(reporter) Pending.mark_skipped! self, exception.argument finish(reporter) end
Private Instance Methods
# File lib/rspec/core/example.rb, line 453 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
# File lib/rspec/core/example.rb, line 398 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
# File lib/rspec/core/example.rb, line 462 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
# File lib/rspec/core/example.rb, line 383 def hooks example_group_instance.singleton_class.hooks end
# File lib/rspec/core/example.rb, line 469 def location_description "example at #{location}" end
# File lib/rspec/core/example.rb, line 449 def mocks_need_verification? exception.nil? || execution_result.pending_fixed? end
# File lib/rspec/core/example.rb, line 418 def record_finished(status) execution_result.record_finished(status, clock.now) end
# File lib/rspec/core/example.rb, line 435 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
# File lib/rspec/core/example.rb, line 422 def run_before_example @example_group_instance.setup_mocks_for_rspec hooks.run(:before, :example, self) end
# File lib/rspec/core/example.rb, line 393 def start(reporter) reporter.example_started(self) execution_result.started_at = clock.now end
# File lib/rspec/core/example.rb, line 443 def verify_mocks @example_group_instance.verify_mocks_for_rspec if mocks_need_verification? rescue Exception => e set_exception(e) end
# File lib/rspec/core/example.rb, line 427 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
# File lib/rspec/core/example.rb, line 387 def with_around_example_hooks hooks.run(:around, :example, self) { yield } rescue Exception => e set_exception(e) end