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`.
@attr_reader @private
Returns the example_group_instance that provides the context for running this example.
@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 110 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
@private
# File lib/rspec/core/example.rb, line 231 def all_apply?(filters) MetadataFilter.all_apply?(filters, metadata) || @example_group_class.all_apply?(filters) end
@private
# File lib/rspec/core/example.rb, line 226 def any_apply?(filters) MetadataFilter.any_apply?(filters, metadata) end
@private
# File lib/rspec/core/example.rb, line 236 def around_example_hooks @around_example_hooks ||= example_group.hooks.around_example_hooks_for(self) end
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 75 def description description = metadata[:description].to_s.empty? ? "example at #{location}" : metadata[:description] RSpec.configuration.format_docstrings_block.call(description) end
Returns the example group class that provides the context for running this example.
# File lib/rspec/core/example.rb, line 124 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 269 def fail_with_exception(reporter, exception) start(reporter) set_exception(exception) finish(reporter) end
@private
# File lib/rspec/core/example.rb, line 293 def instance_exec(*args, &block) @example_group_instance.instance_exec(*args, &block) end
@private
# File lib/rspec/core/example.rb, line 286 def instance_exec_with_rescue(context, &block) @example_group_instance.instance_exec(self, &block) rescue Exception => e set_exception(e, context) 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 135 def run(example_group_instance, reporter) @example_group_instance = example_group_instance RSpec.current_example = self start(reporter) begin if skipped? Pending.mark_pending! self, skip elsif !RSpec.configuration.dry_run? with_around_example_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.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
@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 244 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 = An error occurred #{context} #{exception.class}: #{exception.message} occurred at #{exception.backtrace.first} RSpec.configuration.reporter.message(msg) end @exception ||= exception end 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 279 def skip_with_exception(reporter, exception) start(reporter) Pending.mark_skipped! self, exception.argument finish(reporter) end
Generated with the Darkfish Rdoc Generator 2.