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.

Defined Under Namespace

Classes: DescriptionBehaviorChange

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

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods included from SharedExampleGroup

registry, share_as, share_examples_for, shared_example_groups, shared_examples

Methods included from Hooks

after, append_after, around, before, prepend_before

Methods included from Pending

const_missing, #pending_no_warning

Methods included from MemoizedHelpers

get_constant_or_yield, #is_expected, #should, #should_not, #subject

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.

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

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

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

+ (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:

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

+ (Object) description 

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) focused(desc = nil, *args)

Shortcut to define an example with :focus => true

See Also:

  • example
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

+ (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:

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

+ (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:

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

+ (Object) metadata

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

+ (Object) run(reporter)

Runs all the examples in this group

487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
 
# File 'lib/rspec/core/example_group.rb', line 487
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) warn_unexpected_args

no-op for Ruby < 1.9

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

260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
 
# File 'lib/rspec/core/example_group.rb', line 260
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

- (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
613
614
615
 
# File 'lib/rspec/core/example_group.rb', line 613
def described_class
  self.class.described_class
end

- (Object) example

Deprecated.

use a block argument

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

- (Object) example=(current_example) 

565
566
567
 
# File 'lib/rspec/core/example_group.rb', line 565
def example=(current_example)
  RSpec.current_example = current_example
end

- (Object) fit {|Example| ... }

Shortcut to define an example with :focus => true

Parameters:

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

Yields:

See Also:

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

- (Object) focus {|Example| ... }

Shortcut to define an example with :focus => true

Parameters:

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

Yields:

See Also:

  • example
130
 
# File 'lib/rspec/core/example_group.rb', line 130
define_example_method :focus,   :focused => true, :focus => true

- (Object) it {|Example| ... }

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

- (Object) it_behaves_like

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"

- (Object) it_should_behave_like

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

- (Object) pending {|Example| ... }

Shortcut to define an example with :pending => true

Parameters:

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

Yields:

See Also:

  • example
137
 
# File 'lib/rspec/core/example_group.rb', line 137
define_example_method :pending,  :pending => true

- (Object) running_example

Deprecated.

use a block argument

576
577
578
579
 
# File 'lib/rspec/core/example_group.rb', line 576
def running_example
  warn_deprecation_of_example_accessor :running_example
  RSpec.current_example
end

- (Object) skip {|Example| ... }

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:

  • example
141
 
# File 'lib/rspec/core/example_group.rb', line 141
define_example_method :skip,     :pending => true

- (Object) specify {|Example| ... }

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

- (Object) warn_deprecation_of_example_accessor(name) 

581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
 
# File 'lib/rspec/core/example_group.rb', line 581
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

- (Object) xexample {|Example| ... }

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

Parameters:

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

Yields:

See Also:

  • example
144
 
# File 'lib/rspec/core/example_group.rb', line 144
define_example_method :xexample, :pending => 'Temporarily disabled with xexample'

- (Object) xit {|Example| ... }

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

Parameters:

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

Yields:

See Also:

  • example
147
 
# File 'lib/rspec/core/example_group.rb', line 147
define_example_method :xit,      :pending => 'Temporarily disabled with xit'

- (Object) xspecify {|Example| ... }

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

Parameters:

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

Yields:

See Also:

  • example
150
 
# File 'lib/rspec/core/example_group.rb', line 150
define_example_method :xspecify, :pending => 'Temporarily disabled with xspecify'