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.

Defined Under Namespace

Classes: DescriptionBehaviorChange

Constant Summary

Constants included from Pending

Pending::NOT_YET_IMPLEMENTED, Pending::NO_REASON_GIVEN

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, share_examples_for, shared_example_groups, shared_examples

Methods included from Pending

const_missing, #pending_no_warning

Methods included from MemoizedHelpers

#is_expected, #should, #should_not, #subject

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.



172
173
174
175
176
 
# File 'lib/rspec/core/example_group.rb', line 172

def self.alias_example_to name, extra={}
  RSpec.deprecate("`RSpec::Core::ExampleGroup.alias_example_to`",
                  :replacement => "`RSpec::Core::Configuration#alias_example_to`")
  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.



208
209
210
211
212
 
# File 'lib/rspec/core/example_group.rb', line 208

def self.alias_it_behaves_like_to name, *args, &block
  RSpec.deprecate("`RSpec::Core::ExampleGroup.alias_it_behaves_like_to`",
                  :replacement => "`RSpec::Core::Configuration#alias_it_behaves_like_to`")
  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:



323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
 
# File 'lib/rspec/core/example_group.rb', line 323

def self.describe(*args, &example_group_block)
  @_subclass_count ||= 0
  @_subclass_count += 1

  if Symbol === args.first || Hash === args.first
    description_arg_behavior_changing_in_rspec_3 = DescriptionBehaviorChange.new(
      args.first, CallerFilter.first_non_rspec_line
    )
  end

  args << {} unless args.last.is_a?(Hash)
  args.last.update(
    :example_group_block => example_group_block,
    :description_arg_behavior_changing_in_rspec_3 => description_arg_behavior_changing_in_rspec_3
  )

  # 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 



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

.focused(desc = nil, *args, &block) ⇒ Object

Shortcut to define an example with :focus => true

See Also:



154
155
156
157
158
159
160
161
162
163
 
# File 'lib/rspec/core/example_group.rb', line 154

def self.focused(desc=nil, *args, &block)
  RSpec.deprecate("`RSpec::Core::ExampleGroup.focused`",
                  :replacement => "`RSpec::Core::ExampleGroup.focus`")

  metadata = Hash === args.last ? args.pop : {}
  metadata.merge!(:focus => true, :focused => true)
  args << metadata

  example(desc, *args, &block)
end

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



219
220
221
 
# File 'lib/rspec/core/example_group.rb', line 219

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:



228
229
230
 
# File 'lib/rspec/core/example_group.rb', line 228

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

.metadata ⇒ Object

The Metadata object associated with this group.

See Also:



292
293
294
 
# File 'lib/rspec/core/example_group.rb', line 292

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

.run(reporter) ⇒ Object

Runs all the examples in this group



486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
 
# File 'lib/rspec/core/example_group.rb', line 486

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

.warn_unexpected_args ⇒ Object

no-op for Ruby < 1.9

Ruby 1.8 reports lambda {}.arity == -1, so can't support this warning reliably



240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
 
# File 'lib/rspec/core/example_group.rb', line 240

def self.warn_unexpected_args(label, name, args, shared_block)
  if !args.empty? && shared_block.parameters.count == 0
    if shared_example_groups[args.first]
      warn <<-WARNING
shared #{label} support#{'s' if /context/ =~ label.to_s} the name of only one example group, received #{[name, *args].inspect}
called from #{CallerFilter.first_non_rspec_line}"
WARNING
    else
        warn <<-WARNING
shared #{label} #{name.inspect} expected #{shared_block.arity} args, got #{args.inspect}
called from #{CallerFilter.first_non_rspec_line}"
WARNING
    end
  end
end

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


612
613
614
 
# File 'lib/rspec/core/example_group.rb', line 612

def described_class
  self.class.described_class
end

#example ⇒ Object

Deprecated.

use a block argument



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

define_example_method :example

#example=(current_example) ⇒ Object 



564
565
566
 
# File 'lib/rspec/core/example_group.rb', line 564

def example=(current_example)
  RSpec.current_example = current_example
end

#fit {|Example| ... } ⇒ Object

Shortcut to define an example with :focus => true

Parameters:

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

Yields:

See Also:



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

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

#focus {|Example| ... } ⇒ Object

Shortcut to define an example with :focus => true

Parameters:

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

Yields:

See Also:



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

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

#it {|Example| ... } ⇒ Object

Defines an example within a group.

Parameters:

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

Yields:



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

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:



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

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:



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

define_nested_shared_group_method :it_should_behave_like

#pending {|Example| ... } ⇒ Object

Shortcut to define an example with :pending => true

Parameters:

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

Yields:

See Also:



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

define_example_method :pending,  :pending => true

#running_example ⇒ Object

Deprecated.

use a block argument



575
576
577
578
 
# File 'lib/rspec/core/example_group.rb', line 575

def running_example
  warn_deprecation_of_example_accessor :running_example
  RSpec.current_example
end

#skip {|Example| ... } ⇒ Object

Shortcut to define an example with :pending => true Backported from RSpec 3 to aid migration.

Parameters:

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

Yields:

See Also:



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

define_example_method :skip,     :pending => true

#specify {|Example| ... } ⇒ 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)

Yields:



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

define_example_method :specify

#warn_deprecation_of_example_accessor(name) ⇒ Object 



580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
 
# File 'lib/rspec/core/example_group.rb', line 580

def warn_deprecation_of_example_accessor(name)
  RSpec.warn_deprecation(<<-EOS.gsub(/^\s*\|/, ''))
    |RSpec::Core::ExampleGroup##{name} is deprecated and will be removed
    |in RSpec 3. There are a few options for what you can use instead:
    |
    |  - rspec-core's DSL methods (`it`, `before`, `after`, `let`, `subject`, etc)
    |    now yield the example as a block argument, and that is the recommended
    |    way to access the current example from those contexts.
    |  - The current example is now exposed via `RSpec.current_example`,
    |    which is accessible from any context.
    |  - If you can't update the code at this call site (e.g. because it is in
    |    an extension gem), you can use this snippet to continue making this
    |    method available in RSpec 2.99 and RSpec 3:
    |
    |      RSpec.configure do |c|
    |        c.expose_current_running_example_as :#{name}
    |      end
    |
    |(Called from #{CallerFilter.first_non_rspec_line})
  EOS
end

#xexample {|Example| ... } ⇒ Object

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

Parameters:

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

Yields:

See Also:



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

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

#xit {|Example| ... } ⇒ Object

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

Parameters:

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

Yields:

See Also:



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

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

#xspecify {|Example| ... } ⇒ Object

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

Parameters:

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

Yields:

See Also:



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

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