Class: RSpec::Core::ExampleGroup

Inherits:
Object
  • Object
show all
Extended by:
RSpec::Core::Extensions::ModuleEvalWithArgs, Hooks, MetadataHashBuilder::WithDeprecationWarning, SharedExampleGroup
Includes:
RSpec::Core::Extensions::InstanceEvalWithArgs, MemoizedHelpers, Pending, SharedExampleGroup
Defined in:
lib/rspec/core/example_group.rb

Overview

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.

Constant Summary

Constant Summary

Constants included from Hooks

Hooks::HOOK_TYPES, Hooks::SCOPES

Constants included from Pending

Pending::NOT_YET_IMPLEMENTED, Pending::NO_REASON_GIVEN

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods included from SharedExampleGroup

registry, share_as, shared_example_groups, shared_examples

Methods included from Hooks

after, append_after, around, before, prepend_before

Methods included from Pending

#pending

Methods included from MemoizedHelpers

get_constant_or_yield, #should, #should_not, #subject

Instance Attribute Details

- (Object) example

Returns the RSpec::Core::Example object that wraps this instance of ExampleGroup

443
444
445
 
# File 'lib/rspec/core/example_group.rb', line 443
def example
  @example
end

Class Method Details

+ (Object) alias_example_to(name, extra = {})

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.

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

109
110
111
 
# 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

+ (Object) alias_it_behaves_like_to(name, *args)

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.

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

143
144
145
 
# 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

+ (Object) describe(*args) Also known as: context

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 Also:

223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# 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

+ (Object) description Also known as: display_name 

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

+ (Object) example

Defines an example within a group.

Parameters:

  • name (String)
  • extra_options (Hash)
  • implementation (Block) 
74
 
# File 'lib/rspec/core/example_group.rb', line 74
define_example_method :example

+ (Object) fit

Shortcut to define an example with :focus => true

Parameters:

  • name (String)
  • extra_options (Hash)
  • implementation (Block)

See Also:

91
 
# File 'lib/rspec/core/example_group.rb', line 91
define_example_method :fit,     :focused => true, :focus => true

+ (Object) focus

Shortcut to define an example with :focus => true

Parameters:

  • name (String)
  • extra_options (Hash)
  • implementation (Block) 
86
 
# File 'lib/rspec/core/example_group.rb', line 86
define_example_method :focus,   :focused => true, :focus => true

+ (Object) focused

Shortcut to define an example with :focus => true

Parameters:

  • name (String)
  • extra_options (Hash)
  • implementation (Block) 
88
 
# File 'lib/rspec/core/example_group.rb', line 88
define_example_method :focused, :focused => true, :focus => true

+ (Object) include_context(name, *args)

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 Also:

153
154
155
 
# 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

+ (Object) include_examples(name, *args)

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 Also:

162
163
164
 
# 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

+ (Object) it

Defines an example within a group.

Parameters:

  • name (String)
  • extra_options (Hash)
  • implementation (Block)

See Also:

78
 
# File 'lib/rspec/core/example_group.rb', line 78
define_example_method :it

+ (Object) it_behaves_like

Generates a nested example group and includes the shared content mapped to name in the nested group.

See Also:

131
 
# File 'lib/rspec/core/example_group.rb', line 131
define_nested_shared_group_method :it_behaves_like, "behaves like"

+ (Object) it_should_behave_like

Generates a nested example group and includes the shared content mapped to name in the nested group.

See Also:

134
 
# File 'lib/rspec/core/example_group.rb', line 134
define_nested_shared_group_method :it_should_behave_like

+ (Object) metadata

The Metadata object associated with this group.

See Also:

192
193
194
 
# File 'lib/rspec/core/example_group.rb', line 192
def self.metadata
  @metadata if defined?(@metadata)
end

+ (Object) pending

Shortcut to define an example with :pending => true

Parameters:

  • name (String)
  • extra_options (Hash)
  • implementation (Block) 
94
 
# File 'lib/rspec/core/example_group.rb', line 94
define_example_method :pending,  :pending => true

+ (Object) run(reporter)

Runs all the examples in this group

362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
 
# 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

+ (Object) specify

Defines an example within a group. This is here primarily for backward compatibility with early versions of RSpec which used context and specify instead of describe and it.

Parameters:

  • name (String)
  • extra_options (Hash)
  • implementation (Block) 
83
 
# File 'lib/rspec/core/example_group.rb', line 83
define_example_method :specify

+ (Object) xexample

Shortcut to define an example with :pending => 'Temporarily disabled with xexample'

Parameters:

  • name (String)
  • extra_options (Hash)
  • implementation (Block) 
96
 
# File 'lib/rspec/core/example_group.rb', line 96
define_example_method :xexample, :pending => 'Temporarily disabled with xexample'

+ (Object) xit

Shortcut to define an example with :pending => 'Temporarily disabled with xit'

Parameters:

  • name (String)
  • extra_options (Hash)
  • implementation (Block) 
98
 
# File 'lib/rspec/core/example_group.rb', line 98
define_example_method :xit,      :pending => 'Temporarily disabled with xit'

+ (Object) xspecify

Shortcut to define an example with :pending => 'Temporarily disabled with xspecify'

Parameters:

  • name (String)
  • extra_options (Hash)
  • implementation (Block) 
100
 
# File 'lib/rspec/core/example_group.rb', line 100
define_example_method :xspecify, :pending => 'Temporarily disabled with xspecify'

Instance Method Details

- (Object) described_class

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

Examples:

describe Thing do
  it "does something" do
    described_class == Thing
  end
end
462
463
464
 
# File 'lib/rspec/core/example_group.rb', line 462
def described_class
  self.class.described_class
end

- (Object) running_example

Deprecated.

use #example

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