class RSpec::Core::ExampleGroup

ExampleGroup and {Example} are the main structural elements of rspec-core. Consider this example:

describe Thing do
  it "does something" do
  end
end

The object returned by `describe Thing` is a subclass of ExampleGroup. The object returned by `it “does something”` is an instance of Example, which serves as a wrapper for an instance of the ExampleGroup in which it is declared.

Example group bodies (e.g. `describe` or `context` blocks) are evaluated in the context of a new subclass of ExampleGroup. Individual examples are evaluated in the context of an instance of the specific ExampleGroup subclass to which they belong.

Besides the class methods defined here, there are other interesting macros defined in {Hooks}, {MemoizedHelpers::ClassMethods} and {SharedExampleGroup}. There are additional instance methods available to your examples defined in {MemoizedHelpers} and {Pending}.

Constants

INSTANCE_VARIABLE_TO_IGNORE

@private

WrongScopeError

Raised when an RSpec API is called in the wrong scope, such as `before` being called from within an example rather than from within an example group block.

Public Class Methods

before_context_ivars() click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 446
def self.before_context_ivars
  @before_context_ivars ||= {}
end
children() click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 415
def self.children
  @children ||= []
end
declaration_line_numbers() click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 573
def self.declaration_line_numbers
  @declaration_line_numbers ||= [metadata[:line_number]] +
    examples.map { |e| e.metadata[:line_number] } +
    FlatMap.flat_map(children, &:declaration_line_numbers)
end
define_example_group_method(name, metadata={}) click to toggle source

@private @macro [attach] ::define_example_group_method

@!scope class
@overload $1
@overload $1(&example_group_definition)
  @param example_group_definition [Block] The definition of the example group.
@overload $1(doc_string, *metadata_keys, metadata={}, &example_implementation)
  @param doc_string [String] The group's doc string.
  @param metadata [Hash] Metadata for the group.
  @param metadata_keys [Array<Symbol>] Metadata tags for the group.
    Will be transformed into hash entries with `true` values.
  @param example_group_definition [Block] The definition of the example group.

Generates a subclass of this example group which inherits
everything except the examples themselves.

@example

  RSpec.describe "something" do # << This describe method is defined in
                                # << RSpec::Core::DSL, included in the
                                # << global namespace (optional)
    before do
      do_something_before
    end

    let(:thing) { Thing.new }

    $1 "attribute (of something)" do
      # examples in the group get the before hook
      # declared above, and can access `thing`
    end
  end

@see DSL#describe

# File lib/rspec/core/example_group.rb, line 231
def self.define_example_group_method(name, metadata={})
  idempotently_define_singleton_method(name) do |*args, &example_group_block|
    thread_data = RSpec.thread_local_metadata
    top_level   = self == ExampleGroup

    if top_level
      if thread_data[:in_example_group]
        raise "Creating an isolated context from within a context is "                      "not allowed. Change `RSpec.#{name}` to `#{name}` or "                      "move this to a top-level scope."
      end

      thread_data[:in_example_group] = true
    end

    begin

      description = args.shift
      combined_metadata = metadata.dup
      combined_metadata.merge!(args.pop) if args.last.is_a? Hash
      args << combined_metadata

      subclass(self, description, args, &example_group_block).tap do |child|
        children << child
      end

    ensure
      thread_data.delete(:in_example_group) if top_level
    end
  end

  RSpec::Core::DSL.expose_example_group_alias(name)
end
define_example_method(name, extra_options={}) click to toggle source

@private @macro [attach] ::define_example_method

@!scope class
@overload $1
@overload $1(&example_implementation)
  @param example_implementation [Block] The implementation of the example.
@overload $1(doc_string, *metadata_keys, metadata={})
  @param doc_string [String] The example's doc string.
  @param metadata [Hash] Metadata for the example.
  @param metadata_keys [Array<Symbol>] Metadata tags for the example.
    Will be transformed into hash entries with `true` values.
@overload $1(doc_string, *metadata_keys, metadata={}, &example_implementation)
  @param doc_string [String] The example's doc string.
  @param metadata [Hash] Metadata for the example.
  @param metadata_keys [Array<Symbol>] Metadata tags for the example.
    Will be transformed into hash entries with `true` values.
  @param example_implementation [Block] The implementation of the example.
@yield [Example] the example object
@example
  $1 do
  end

  $1 "does something" do
  end

  $1 "does something", :slow, :uses_js do
  end

  $1 "does something", :with => 'additional metadata' do
  end

  $1 "does something" do |ex|
    # ex is the Example object that contains metadata about the example
  end
# File lib/rspec/core/example_group.rb, line 137
def self.define_example_method(name, extra_options={})
  idempotently_define_singleton_method(name) do |*all_args, &block|
    desc, *args = *all_args

    options = Metadata.build_hash_from(args)
    options.update(:skip => RSpec::Core::Pending::NOT_YET_IMPLEMENTED) unless block
    options.update(extra_options)

    examples << RSpec::Core::Example.new(self, desc, options, block)
    examples.last
  end
end
define_nested_shared_group_method(new_name, report_label="it should behave like") click to toggle source

@private @macro [attach] ::define_nested_shared_group_method

@!scope class

@see SharedExampleGroup
# File lib/rspec/core/example_group.rb, line 302
def self.define_nested_shared_group_method(new_name, report_label="it should behave like")
  idempotently_define_singleton_method(new_name) do |name, *args, &customization_block|
    # Pass :caller so the :location metadata is set properly.
    # Otherwise, it'll be set to the next line because that's
    # the block's source_location.
    group = example_group("#{report_label} #{name}", :caller => (the_caller = caller)) do
      find_and_eval_shared("examples", name, the_caller.first, *args, &customization_block)
    end
    group.metadata[:shared_group_name] = name
    group
  end
end
delegate_to_metadata(*names) click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 72
def self.delegate_to_metadata(*names)
  names.each do |name|
    idempotently_define_singleton_method(name) { metadata.fetch(name) }
  end
end
descendant_filtered_examples() click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 409
def self.descendant_filtered_examples
  @descendant_filtered_examples ||= filtered_examples +
    FlatMap.flat_map(children, &:descendant_filtered_examples)
end
descendants() click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 420
def self.descendants
  @_descendants ||= [self] + FlatMap.flat_map(children, &:descendants)
end
description() click to toggle source

@return [String] the current example group description

# File lib/rspec/core/example_group.rb, line 81
def self.description
  description = metadata[:description]
  RSpec.configuration.format_docstrings_block.call(description)
end
each_instance_variable_for_example(group) { |ivar| ... } click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 598
def self.each_instance_variable_for_example(group)
  group.instance_variables.each do |ivar|
    yield ivar unless ivar == INSTANCE_VARIABLE_TO_IGNORE
  end
end
ensure_example_groups_are_configured() click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 435
def self.ensure_example_groups_are_configured
  unless defined?(@@example_groups_configured)
    RSpec.configuration.configure_mock_framework
    RSpec.configuration.configure_expectation_framework
    # rubocop:disable Style/ClassVars
    @@example_groups_configured = true
    # rubocop:enable Style/ClassVars
  end
end
examples() click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 399
def self.examples
  @examples ||= []
end
fail_fast?() click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 568
def self.fail_fast?
  RSpec.configuration.fail_fast?
end
filtered_examples() click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 404
def self.filtered_examples
  RSpec.world.filtered_examples[self]
end
find_and_eval_shared(label, name, inclusion_location, *args, &customization_block) click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 343
def self.find_and_eval_shared(label, name, inclusion_location, *args, &customization_block)
  shared_block = RSpec.world.shared_example_group_registry.find(parent_groups, name)

  unless shared_block
    raise ArgumentError, "Could not find shared #{label} #{name.inspect}"
  end

  SharedExampleGroupInclusionStackFrame.with_frame(name, Metadata.relative_path(inclusion_location)) do
    module_exec(*args, &shared_block)
    module_exec(&customization_block) if customization_block
  end
end
for_filtered_examples(reporter, &block) click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 556
def self.for_filtered_examples(reporter, &block)
  filtered_examples.each(&block)

  children.each do |child|
    reporter.example_group_started(child)
    child.for_filtered_examples(reporter, &block)
    reporter.example_group_finished(child)
  end
  false
end
idempotently_define_singleton_method(name, &definition) click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 36
def self.idempotently_define_singleton_method(name, &definition)
  (class << self; self; end).module_exec do
    remove_method(name) if method_defined?(name) && instance_method(name).owner == self
    define_method(name, &definition)
  end
end
include_context(name, *args, &block) click to toggle source

Includes shared content mapped to `name` directly in the group in which it is declared, as opposed to `it_behaves_like`, which creates a nested group. If given a block, that block is also eval'd in the current context.

@see SharedExampleGroup

# File lib/rspec/core/example_group.rb, line 328
def self.include_context(name, *args, &block)
  find_and_eval_shared("context", name, caller.first, *args, &block)
end
include_examples(name, *args, &block) click to toggle source

Includes shared content mapped to `name` directly in the group in which it is declared, as opposed to `it_behaves_like`, which creates a nested group. If given a block, that block is also eval'd in the current context.

@see SharedExampleGroup

# File lib/rspec/core/example_group.rb, line 338
def self.include_examples(name, *args, &block)
  find_and_eval_shared("examples", name, caller.first, *args, &block)
end
metadata() click to toggle source

The [Metadata](Metadata) object associated with this group. @see Metadata

# File lib/rspec/core/example_group.rb, line 47
def self.metadata
  @metadata ||= nil
end
new(inspect_output=nil) click to toggle source
# File lib/rspec/core/example_group.rb, line 604
def initialize(inspect_output=nil)
  @__inspect_output = inspect_output || '(no description provided)'
end
ordering_strategy() click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 528
      def self.ordering_strategy
        order = metadata.fetch(:order, :global)
        registry = RSpec.configuration.ordering_registry

        registry.fetch(order) do
          warn "            |WARNING: Ignoring unknown ordering specified using `:order => #{order.inspect}` metadata.
            |         Falling back to configured global ordering.
            |         Unrecognized ordering specified at: #{location}
".gsub(/^ +\|/, '')

          registry.fetch(:global)
        end
      end
parent_groups() click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 425
def self.parent_groups
  @parent_groups ||= ancestors.select { |a| a < RSpec::Core::ExampleGroup }
end
run(reporter=RSpec::Core::NullReporter.new) click to toggle source

Runs all the examples in this group.

# File lib/rspec/core/example_group.rb, line 502
def self.run(reporter=RSpec::Core::NullReporter.new)
  if RSpec.world.wants_to_quit
    RSpec.world.clear_remaining_example_groups if top_level?
    return
  end
  reporter.example_group_started(self)

  should_run_context_hooks = descendant_filtered_examples.any?
  begin
    run_before_context_hooks(new('before(:context) hook')) if should_run_context_hooks
    result_for_this_group = run_examples(reporter)
    results_for_descendants = ordering_strategy.order(children).map { |child| child.run(reporter) }.all?
    result_for_this_group && results_for_descendants
  rescue Pending::SkipDeclaredInExample => ex
    for_filtered_examples(reporter) { |example| example.skip_with_exception(reporter, ex) }
    true
  rescue Exception => ex
    RSpec.world.wants_to_quit = true if fail_fast?
    for_filtered_examples(reporter) { |example| example.fail_with_exception(reporter, ex) }
  ensure
    run_after_context_hooks(new('after(:context) hook')) if should_run_context_hooks
    reporter.example_group_finished(self)
  end
end
run_after_context_hooks(example_group_instance) click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 491
def self.run_after_context_hooks(example_group_instance)
  set_ivars(example_group_instance, before_context_ivars)

  ContextHookMemoizedHash::After.isolate_for_context_hook(example_group_instance) do
    hooks.run(:after, :context, example_group_instance)
  end
ensure
  before_context_ivars.clear
end
run_before_context_hooks(example_group_instance) click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 458
def self.run_before_context_hooks(example_group_instance)
  set_ivars(example_group_instance, superclass_before_context_ivars)

  ContextHookMemoizedHash::Before.isolate_for_context_hook(example_group_instance) do
    hooks.run(:before, :context, example_group_instance)
  end
ensure
  store_before_context_ivars(example_group_instance)
end
run_examples(reporter) click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 544
def self.run_examples(reporter)
  ordering_strategy.order(filtered_examples).map do |example|
    next if RSpec.world.wants_to_quit
    instance = new(example.inspect_output)
    set_ivars(instance, before_context_ivars)
    succeeded = example.run(instance, reporter)
    RSpec.world.wants_to_quit = true if fail_fast? && !succeeded
    succeeded
  end.all?
end
set_it_up(*args, &example_group_block) click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 375
def self.set_it_up(*args, &example_group_block)
  # Ruby 1.9 has a bug that can lead to infinite recursion and a
  # SystemStackError if you include a module in a superclass after
  # including it in a subclass: https://gist.github.com/845896
  # To prevent this, we must include any modules in
  # RSpec::Core::ExampleGroup before users create example groups and have
  # a chance to include the same module in a subclass of
  # RSpec::Core::ExampleGroup. So we need to configure example groups
  # here.
  ensure_example_groups_are_configured

  description = args.shift
  user_metadata = Metadata.build_hash_from(args)
  args.unshift(description)

  @metadata = Metadata::ExampleGroupHash.create(
    superclass_metadata, user_metadata, *args, &example_group_block
  )

  hooks.register_globals(self, RSpec.configuration.hooks)
  RSpec.configuration.configure_group(self)
end
set_ivars(instance, ivars) click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 585
def self.set_ivars(instance, ivars)
  ivars.each { |name, value| instance.instance_variable_set(name, value) }
end
store_before_context_ivars(example_group_instance) click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 451
def self.store_before_context_ivars(example_group_instance)
  each_instance_variable_for_example(example_group_instance) do |ivar|
    before_context_ivars[ivar] = example_group_instance.instance_variable_get(ivar)
  end
end
subclass(parent, description, args, &example_group_block) click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 359
def self.subclass(parent, description, args, &example_group_block)
  subclass = Class.new(parent)
  subclass.set_it_up(description, *args, &example_group_block)
  ExampleGroups.assign_const(subclass)
  subclass.module_exec(&example_group_block) if example_group_block

  # The LetDefinitions module must be included _after_ other modules
  # to ensure that it takes precedence when there are name collisions.
  # Thus, we delay including it until after the example group block
  # has been eval'd.
  MemoizedHelpers.define_helpers_on(subclass)

  subclass
end
superclass_before_context_ivars() click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 470
def self.superclass_before_context_ivars
  superclass.before_context_ivars
end
superclass_metadata() click to toggle source

@private @return [Metadata] belonging to the parent of a nested {ExampleGroup}

# File lib/rspec/core/example_group.rb, line 67
def self.superclass_metadata
  @superclass_metadata ||= superclass.respond_to?(:metadata) ? superclass.metadata : nil
end
top_level?() click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 430
def self.top_level?
  @top_level ||= superclass == ExampleGroup
end
top_level_description() click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 580
def self.top_level_description
  parent_groups.last.description
end
with_replaced_metadata(meta) { || ... } click to toggle source

Temporarily replace the provided metadata. Intended primarily to allow an example group's singleton class to return the metadata of the example that it exists for. This is necessary for shared example group inclusion to work properly with singleton example groups. @private

# File lib/rspec/core/example_group.rb, line 57
def self.with_replaced_metadata(meta)
  orig_metadata = metadata
  @metadata = meta
  yield
ensure
  @metadata = orig_metadata
end

Private Class Methods

method_missing(name, *args) click to toggle source
Calls superclass method
# File lib/rspec/core/example_group.rb, line 625
def self.method_missing(name, *args)
  if method_defined?(name)
    raise WrongScopeError,
          "`#{name}` is not available on an example group (e.g. a "                  "`describe` or `context` block). It is only available from "                  "within individual examples (e.g. `it` blocks) or from "                  "constructs that run in the scope of an example (e.g. "                  "`before`, `let`, etc)."
  end

  super
end

Public Instance Methods

described_class() click to toggle source

Returns the class or module passed to the `describe` method (or alias). Returns nil if the subject is not a class or module. @example

describe Thing do
  it "does something" do
    described_class == Thing
  end
end
# File lib/rspec/core/example_group.rb, line 95
def described_class
  self.class.described_class
end
inspect() click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 609
def inspect
  "#<#{self.class} #{@__inspect_output}>"
end
singleton_class() click to toggle source

@private

# File lib/rspec/core/example_group.rb, line 615
def singleton_class
  class << self; self; end
end

Private Instance Methods

method_missing(name, *args) click to toggle source
Calls superclass method
# File lib/rspec/core/example_group.rb, line 641
def method_missing(name, *args)
  if self.class.respond_to?(name)
    raise WrongScopeError,
          "`#{name}` is not available from within an example (e.g. an "                  "`it` block) or from constructs that run in the scope of an "                  "example (e.g. `before`, `let`, etc). It is only available "                  "on an example group (e.g. a `describe` or `context` block)."
  end

  super
end