Class: RSpec::Core::ExampleGroup

Inherits:
Object
  • Object
show all
Extended by:
Hooks, Subject::ExampleGroupMethods
Includes:
Let, Pending, SharedExampleGroup, Subject::ExampleMethods
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

Constants included from Pending

Pending::NOT_YET_IMPLEMENTED, Pending::NO_REASON_GIVEN

Instance Attribute Summary collapse

Attributes included from Subject::ExampleGroupMethods

#explicit_subject_block

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Subject::ExampleGroupMethods

its, subject

Methods included from Hooks

after, append_after, around, before, prepend_before

Methods included from SharedExampleGroup

#share_as, #shared_examples

Methods included from Pending

#pending

Methods included from Subject::ExampleMethods

#should, #should_not, #subject

Instance Attribute Details

#example ⇒ Object

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



441
442
443
 
# File 'lib/rspec/core/example_group.rb', line 441

def example
  @example
end

Class Method Details

.alias_example_to(name, extra = {}) ⇒ Object

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.



107
108
109
 
# File 'lib/rspec/core/example_group.rb', line 107

def alias_example_to name, extra={}
  (class << self; self; end).define_example_method name, extra
end

.alias_it_behaves_like_to(name, *args, &block) ⇒ Object

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.



141
142
143
 
# File 'lib/rspec/core/example_group.rb', line 141

def alias_it_behaves_like_to name, *args, &block
  (class << self; self; end).define_nested_shared_group_method name, *args, &block
end

.describe(*args, &example_group_block) ⇒ Object 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:



221
222
223
224
225
226
227
228
229
230
231
232
233
234
 
# File 'lib/rspec/core/example_group.rb', line 221

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

.description ⇒ Object Also known as: display_name 



47
48
49
50
 
# File 'lib/rspec/core/example_group.rb', line 47

def description
  description = metadata[:example_group][:description]
  RSpec.configuration.format_docstrings_block.call(description)
end

.example ⇒ Object

Defines an example within a group.

Parameters:

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


75
 
# File 'lib/rspec/core/example_group.rb', line 75

define_example_method :example

.focus ⇒ Object

Shortcut to define an example with :focus => true

Parameters:

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


87
 
# File 'lib/rspec/core/example_group.rb', line 87

define_example_method :focus,   :focused => true, :focus => true

.focused ⇒ Object

Shortcut to define an example with :focus => true

Parameters:

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


89
 
# File 'lib/rspec/core/example_group.rb', line 89

define_example_method :focused, :focused => true, :focus => true

.include_context(name, *args, &block) ⇒ Object

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:



151
152
153
 
# File 'lib/rspec/core/example_group.rb', line 151

def self.include_context(name, *args, &block)
  find_and_eval_shared("context", name, *args, &block)
end

.include_examples(name, *args, &block) ⇒ Object

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:



160
161
162
 
# File 'lib/rspec/core/example_group.rb', line 160

def self.include_examples(name, *args, &block)
  find_and_eval_shared("examples", name, *args, &block)
end

.it ⇒ Object

Defines an example within a group.

Parameters:

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

See Also:



79
 
# File 'lib/rspec/core/example_group.rb', line 79

define_example_method :it

.it_behaves_like ⇒ Object

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

See Also:



129
 
# File 'lib/rspec/core/example_group.rb', line 129

define_nested_shared_group_method :it_behaves_like, "behaves like"

.it_should_behave_like ⇒ Object

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

See Also:



132
 
# File 'lib/rspec/core/example_group.rb', line 132

define_nested_shared_group_method :it_should_behave_like

.metadata ⇒ Object

The Metadata object associated with this group.

See Also:



190
191
192
 
# File 'lib/rspec/core/example_group.rb', line 190

def self.metadata
  @metadata if defined?(@metadata)
end

.pending ⇒ Object

Shortcut to define an example with :pending => true

Parameters:

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


92
 
# File 'lib/rspec/core/example_group.rb', line 92

define_example_method :pending,  :pending => true

.run(reporter) ⇒ Object

Runs all the examples in this group



360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
 
# File 'lib/rspec/core/example_group.rb', line 360

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

.specify ⇒ Object

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) 


84
 
# File 'lib/rspec/core/example_group.rb', line 84

define_example_method :specify

.xexample ⇒ Object

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

Parameters:

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


94
 
# File 'lib/rspec/core/example_group.rb', line 94

define_example_method :xexample, :pending => 'Temporarily disabled with xexample'

.xit ⇒ Object

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

Parameters:

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


96
 
# File 'lib/rspec/core/example_group.rb', line 96

define_example_method :xit,      :pending => 'Temporarily disabled with xit'

.xspecify ⇒ Object

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

Parameters:

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


98
 
# File 'lib/rspec/core/example_group.rb', line 98

define_example_method :xspecify, :pending => 'Temporarily disabled with xspecify'

Instance Method Details

#described_class ⇒ Object

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


459
460
461
 
# File 'lib/rspec/core/example_group.rb', line 459

def described_class
  self.class.described_class
end

#running_example ⇒ Object

Deprecated.

use #example



444
445
446
447
 
# File 'lib/rspec/core/example_group.rb', line 444

def running_example
  RSpec.deprecate("running_example", "example")
  example
end