Class: RSpec::Core::ExampleGroup

### Home Classes Methods

### In Files

- lib/rspec/core/example_group.rb

### Parent

Object

### Methods

- ::alias_example_to
- ::alias_it_behaves_like_to
- ::all_apply?
- ::any_apply?
- ::assign_before_all_ivars
- ::before_all_ivars
- ::children
- ::context
- ::declaration_line_numbers
- ::define_example_method
- ::define_nested_shared_group_method
- ::delegate_to_metadata
- ::descendant_filtered_examples
- ::descendants
- ::describe
- ::description
- ::display_name
- ::ensure_example_groups_are_configured
- ::examples
- ::fail_fast?
- ::fail_filtered_examples
- ::filtered_examples
- ::find_and_eval_shared
- ::include_context
- ::include_examples
- ::metadata
- ::parent_groups
- ::register
- ::run
- ::run_after_all_hooks
- ::run_after_each_hooks
- ::run_around_each_hooks
- ::run_before_all_hooks
- ::run_before_each_hooks
- ::run_examples
- ::set_it_up
- ::set_ivars
- ::store_before_all_ivars
- ::subclass
- ::superclass_metadata
- ::top_level?
- ::top_level_description
- ::world
- #described_class
- #instance_eval_with_rescue
- #running_example

### Included Modules

- RSpec::Core::MemoizedHelpers
- RSpec::Core::Extensions::InstanceEvalWithArgs
- RSpec::Core::Pending
- RSpec::Core::SharedExampleGroup

### Class/Module Index

Quicksearch

- RSpec
- RSpec::Core
- RSpec::Core::BacktraceCleaner
- RSpec::Core::BacktraceFormatter
- RSpec::Core::CommandLine
- RSpec::Core::Configuration
- RSpec::Core::Configuration::MustBeConfiguredBeforeExampleGroupsError
- RSpec::Core::ConfigurationOptions
- RSpec::Core::ConstMissing
- RSpec::Core::DRbCommandLine
- RSpec::Core::DSL
- RSpec::Core::Deprecation
- RSpec::Core::DrbOptions
- RSpec::Core::Example
- RSpec::Core::Example::NotPendingExampleFixed
- RSpec::Core::Example::Procsy
- RSpec::Core::ExampleGroup
- RSpec::Core::Extensions
- RSpec::Core::Extensions::InstanceEvalWithArgs
- RSpec::Core::Extensions::ModuleEvalWithArgs
- RSpec::Core::Extensions::Ordered
- RSpec::Core::Extensions::Ordered::ExampleGroups
- RSpec::Core::Extensions::Ordered::Examples
- RSpec::Core::FilterManager
- RSpec::Core::FilterManager::BackwardCompatibility
- RSpec::Core::FilterManager::Describable
- RSpec::Core::Formatters
- RSpec::Core::Formatters::BaseFormatter
- RSpec::Core::Formatters::BaseTextFormatter
- RSpec::Core::Formatters::DeprecationFormatter
- RSpec::Core::Formatters::DocumentationFormatter
- RSpec::Core::Formatters::Helpers
- RSpec::Core::Formatters::HtmlFormatter
- RSpec::Core::Formatters::HtmlPrinter
- RSpec::Core::Formatters::JsonFormatter
- RSpec::Core::Formatters::ProgressFormatter
- RSpec::Core::Formatters::SnippetExtractor
- RSpec::Core::Formatters::SnippetExtractor::NullConverter
- RSpec::Core::Formatters::TextMateFormatter
- RSpec::Core::Hooks
- RSpec::Core::Hooks::AfterAllHook
- RSpec::Core::Hooks::AfterHook
- RSpec::Core::Hooks::AroundHook
- RSpec::Core::Hooks::AroundHookCollection
- RSpec::Core::Hooks::BeforeHook
- RSpec::Core::Hooks::GroupHookCollection
- RSpec::Core::Hooks::Hook
- RSpec::Core::Hooks::HookCollection
- RSpec::Core::Hooks::HookCollectionAliases
- RSpec::Core::Hooks::RegistersGlobals
- RSpec::Core::MemoizedHelpers
- RSpec::Core::MemoizedHelpers::BeforeAllMemoizedHash
- RSpec::Core::MemoizedHelpers::ClassMethods
- RSpec::Core::Metadata
- RSpec::Core::Metadata::ExampleMetadataHash
- RSpec::Core::Metadata::GroupMetadataHash
- RSpec::Core::Metadata::MetadataHash
- RSpec::Core::MetadataHashBuilder
- RSpec::Core::MetadataHashBuilder::Common
- RSpec::Core::MetadataHashBuilder::WithConfigWarning
- RSpec::Core::MetadataHashBuilder::WithDeprecationWarning
- RSpec::Core::MockFrameworkAdapter
- RSpec::Core::Parser
- RSpec::Core::Pending
- RSpec::Core::Pending::PendingDeclaredInExample
- RSpec::Core::Pending::PendingExampleFixedError
- RSpec::Core::ProjectInitializer
- RSpec::Core::RakeTask
- RSpec::Core::Reporter
- RSpec::Core::RubyProject
- RSpec::Core::Runner
- RSpec::Core::SharedContext
- RSpec::Core::SharedExampleGroup
- RSpec::Core::SharedExampleGroup::Collection
- RSpec::Core::SharedExampleGroup::Registry
- RSpec::Core::SharedExampleGroup::TopLevelDSL
- RSpec::Core::Time
- RSpec::Core::Version
- RSpec::Core::World
- RSpec::Rake
- RSpec::Runner
- Autotest
- Autotest::Rspec2
- Kernel

No matching classes.

# 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.

### Attributes

example[RW]

@attr_reader Returns the {Example} object that wraps this instance of `ExampleGroup`

### Public Class Methods

alias_example_to(name, extra={}) click to toggle source

Works like `alias_method :name, :example` with the added benefit of assigning default metadata to the generated example.

@note Use with caution. This extends the language used in your

    specs, but does not add any additional documentation.  We use this
    in rspec to define methods like `focus` and `xit`, but we also add
    docs for those methods.

    # File lib/rspec/core/example_group.rb, line 109
    def alias_example_to name, extra={}
      (class << self; self; end).define_example_method name, extra
    end

alias_it_behaves_like_to(name, *args, &block) click to toggle source

Works like `alias_method :name, :it_behaves_like` with the added benefit of assigning default metadata to the generated example.

@note Use with caution. This extends the language used in your

    specs, but does not add any additional documentation.  We use this
    in rspec to define `it_should_behave_like` (for backward
    compatibility), but we also add docs for that method.

    # File lib/rspec/core/example_group.rb, line 143
    def alias_it_behaves_like_to name, *args, &block
      (class << self; self; end).define_nested_shared_group_method name, *args, &block
    end

all_apply?(filters) click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 419
    def self.all_apply?(filters)
      metadata.all_apply?(filters)
    end

any_apply?(filters) click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 414
    def self.any_apply?(filters)
      metadata.any_apply?(filters)
    end

assign_before_all_ivars(ivars, example_group_instance) click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 320
    def self.assign_before_all_ivars(ivars, example_group_instance)
      ivars.each { |ivar, val| example_group_instance.instance_variable_set(ivar, val) }
    end

before_all_ivars() click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 306
    def self.before_all_ivars
      @before_all_ivars ||= {}
    end

children() click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 258
    def self.children
      @children ||= [].extend(Extensions::Ordered::ExampleGroups)
    end

context(*args, &example_group_block) click to toggle source
Alias for: describe
declaration_line_numbers() click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 424
    def self.declaration_line_numbers
      @declaration_line_numbers ||= [metadata[:example_group][:line_number]] +
        examples.collect {|e| e.metadata[:line_number]} +
        children.inject([]) {|l,c| l + c.declaration_line_numbers}
    end

define_example_method(name, extra_options={}) click to toggle source

@private @macro [attach] define_example_method

    @param [String] name
    @param [Hash] extra_options
    @param [Block] implementation

    # File lib/rspec/core/example_group.rb, line 61
    def self.define_example_method(name, extra_options={})
      module_eval(            def #{name}(desc=nil, *args, &block)              options = build_metadata_hash_from(args)              options.update(:pending => RSpec::Core::Pending::NOT_YET_IMPLEMENTED) unless block              options.update(#{extra_options.inspect})              examples << RSpec::Core::Example.new(self, desc, options, block)              examples.last            end, __FILE__, __LINE__)
    end

define_nested_shared_group_method(new_name, report_label=nil) click to toggle source

@private @macro [attach] define_nested_shared_group_method

    @see SharedExampleGroup

    # File lib/rspec/core/example_group.rb, line 117
    def self.define_nested_shared_group_method(new_name, report_label=nil)
      module_eval(            def #{new_name}(name, *args, &customization_block)              group = describe("#{report_label || "it should behave like"} \#{name}") do                find_and_eval_shared("examples", name, *args, &customization_block)              end              group.metadata[:shared_group_name] = name              group            end, __FILE__, __LINE__)
    end

delegate_to_metadata(*names) click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 38
    def self.delegate_to_metadata(*names)
      names.each do |name|
        define_method name do
          metadata[:example_group][name]
        end
      end
    end

descendant_filtered_examples() click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 186
    def self.descendant_filtered_examples
      @descendant_filtered_examples ||= filtered_examples + children.inject([]){|l,c| l + c.descendant_filtered_examples}
    end

descendants() click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 263
    def self.descendants
      @_descendants ||= [self] + children.inject([]) {|list, c| list + c.descendants}
    end

describe(*args, &example_group_block) click to toggle source

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

## Examples

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

      let(:thing) { Thing.new }

      describe "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 223
    def self.describe(*args, &example_group_block)
      @_subclass_count ||= 0
      @_subclass_count += 1
      args << {} unless args.last.is_a?(Hash)
      args.last.update(:example_group_block => example_group_block)

      # TODO 2010-05-05: Because we don't know if const_set is thread-safe
      child = const_set(
        "Nested_#{@_subclass_count}",
        subclass(self, args, &example_group_block)
      )
      children << child
      child
    end

Also aliased as: context
description() click to toggle source

    # File lib/rspec/core/example_group.rb, line 46
    def description
      description = metadata[:example_group][:description]
      RSpec.configuration.format_docstrings_block.call(description)
    end

Also aliased as: display_name
display_name() click to toggle source
Alias for: description
ensure_example_groups_are_configured() click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 278
    def self.ensure_example_groups_are_configured
      unless defined?(@@example_groups_configured)
        RSpec.configuration.configure_mock_framework
        RSpec.configuration.configure_expectation_framework
        @@example_groups_configured = true
      end
    end

examples() click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 176
    def self.examples
      @examples ||= []
    end

fail_fast?() click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 409
    def self.fail_fast?
      RSpec.configuration.fail_fast?
    end

fail_filtered_examples(exception, reporter) click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 397
    def self.fail_filtered_examples(exception, reporter)
      filtered_examples.each { |example| example.fail_with_exception(reporter, exception) }

      children.each do |child|
        reporter.example_group_started(child)
        child.fail_filtered_examples(exception, reporter)
        reporter.example_group_finished(child)
      end
      false
    end

filtered_examples() click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 181
    def self.filtered_examples
      world.filtered_examples[self]
    end

find_and_eval_shared(label, name, *args, &customization_block) click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 167
    def self.find_and_eval_shared(label, name, *args, &customization_block)
      raise ArgumentError, "Could not find shared #{label} #{name.inspect}" unless
      shared_block = shared_example_groups[name]

      module_eval_with_args(*args, &shared_block)
      module_eval(&customization_block) if customization_block
    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 153
    def self.include_context(name, *args, &block)
      find_and_eval_shared("context", name, *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 162
    def self.include_examples(name, *args, &block)
      find_and_eval_shared("examples", name, *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 192
    def self.metadata
      @metadata if defined?(@metadata)
    end

parent_groups() click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 268
    def self.parent_groups
      @parent_groups ||= ancestors.select {|a| a < RSpec::Core::ExampleGroup}
    end

register() click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 32
    def self.register
      world.register(self)
    end

run(reporter) click to toggle source

Runs all the examples in this group

    # File lib/rspec/core/example_group.rb, line 362
    def self.run(reporter)
      if RSpec.wants_to_quit
        RSpec.clear_remaining_example_groups if top_level?
        return
      end
      reporter.example_group_started(self)

      begin
        run_before_all_hooks(new)
        result_for_this_group = run_examples(reporter)
        results_for_descendants = children.ordered.map {|child| child.run(reporter)}.all?
        result_for_this_group && results_for_descendants
      rescue Exception => ex
        RSpec.wants_to_quit = true if fail_fast?
        fail_filtered_examples(ex, reporter)
      ensure
        run_after_all_hooks(new)
        before_all_ivars.clear
        reporter.example_group_finished(self)
      end
    end

run_after_all_hooks(example_group_instance) click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 354
    def self.run_after_all_hooks(example_group_instance)
      return if descendant_filtered_examples.empty?
      assign_before_all_ivars(before_all_ivars, example_group_instance)

      run_hook(:after, :all, example_group_instance)
    end

run_after_each_hooks(example) click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 349
    def self.run_after_each_hooks(example)
      run_hook(:after, :each, example)
    end

run_around_each_hooks(example, initial_procsy) click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 339
    def self.run_around_each_hooks(example, initial_procsy)
      run_hook(:around, :each, example, initial_procsy)
    end

run_before_all_hooks(example_group_instance) click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 325
    def self.run_before_all_hooks(example_group_instance)
      return if descendant_filtered_examples.empty?
      begin
        assign_before_all_ivars(superclass.before_all_ivars, example_group_instance)

        BeforeAllMemoizedHash.isolate_for_before_all(example_group_instance) do
          run_hook(:before, :all, example_group_instance)
        end
      ensure
        store_before_all_ivars(example_group_instance)
      end
    end

run_before_each_hooks(example) click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 344
    def self.run_before_each_hooks(example)
      run_hook(:before, :each, example)
    end

run_examples(reporter) click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 385
    def self.run_examples(reporter)
      filtered_examples.ordered.map do |example|
        next if RSpec.wants_to_quit
        instance = new
        set_ivars(instance, before_all_ivars)
        succeeded = example.run(instance, reporter)
        RSpec.wants_to_quit = true if fail_fast? && !succeeded
        succeeded
      end.all?
    end

set_it_up(*args) click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 287
    def self.set_it_up(*args)
      # 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

      symbol_description = args.shift if args.first.is_a?(Symbol)
      args << build_metadata_hash_from(args)
      args.unshift(symbol_description) if symbol_description
      @metadata = RSpec::Core::Metadata.new(superclass_metadata).process(*args)
      hooks.register_globals(self, RSpec.configuration.hooks)
      world.configure_group(self)
    end

set_ivars(instance, ivars) click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 436
    def self.set_ivars(instance, ivars)
      ivars.each {|name, value| instance.instance_variable_set(name, value)}
    end

store_before_all_ivars(example_group_instance) click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 311
    def self.store_before_all_ivars(example_group_instance)
      return if example_group_instance.instance_variables.empty?

      example_group_instance.instance_variables.each { |ivar|
        before_all_ivars[ivar] = example_group_instance.instance_variable_get(ivar)
      }
    end

subclass(parent, args, &example_group_block) click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 243
    def self.subclass(parent, args, &example_group_block)
      subclass = Class.new(parent)
      subclass.set_it_up(*args)
      subclass.module_eval(&example_group_block) if example_group_block

      # The LetDefinitions module must be included _after_ other modules
      # to ensure that it takes precendence 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_metadata() click to toggle source

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

    # File lib/rspec/core/example_group.rb, line 198
    def self.superclass_metadata
      @superclass_metadata ||= self.superclass.respond_to?(:metadata) ? self.superclass.metadata : nil
    end

top_level?() click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 273
    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 431
    def self.top_level_description
      parent_groups.last.description
    end

world() click to toggle source

@private

    # File lib/rspec/core/example_group.rb, line 27
    def self.world
      RSpec.world
    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 462
    def described_class
      self.class.described_class
    end

instance_eval_with_rescue(context = nil, &hook) click to toggle source

@private instance_evals the block, capturing and reporting an exception if raised

    # File lib/rspec/core/example_group.rb, line 469
    def instance_eval_with_rescue(context = nil, &hook)
      begin
        instance_eval(&hook)
      rescue Exception => e
        raise unless example
        example.set_exception(e, context)
      end
    end

running_example() click to toggle source

@deprecated use {ExampleGroup#example}

    # File lib/rspec/core/example_group.rb, line 446
    def running_example
      RSpec.deprecate("running_example",
                      :replacement => "example")
      example
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.