Class: RSpec::Core::ExampleGroup

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

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 Hooks

after, append_after, around, before, prepend_before

Methods included from SharedExampleGroup

registry, share_as, shared_example_groups, shared_examples

Methods included from Pending

#pending

Methods included from MemoizedHelpers

#should, #should_not, #subject

Instance Attribute Details

#example ⇒ Object

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

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



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

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



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

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



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

.description ⇒ Object 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

.example ⇒ Object

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

.fit ⇒ Object

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

.focus ⇒ Object

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

.focused ⇒ Object

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

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



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

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



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

.it ⇒ Object

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

.it_behaves_like ⇒ Object

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"

.it_should_behave_like ⇒ Object

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

.metadata ⇒ Object

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

.pending ⇒ Object

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

.run(reporter) ⇒ Object

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

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


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

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) 


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

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) 


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

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) 


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

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


462
463
464
 
# File 'lib/rspec/core/example_group.rb', line 462

def described_class
  self.class.described_class
end

#running_example ⇒ Object

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