Class: RSpec::Core::ExampleGroup
- Inherits:
-
Object
- Object
- RSpec::Core::ExampleGroup
- Extended by:
- Hooks, MemoizedHelpers::ClassMethods, SharedExampleGroup
- Includes:
- MemoizedHelpers, Pending
- Defined in:
- lib/rspec/core/example_group.rb
Overview
ExampleGroup and Example are the main structural elements of rspec-core. Consider this example:
RSpec.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.
Example group bodies (e.g. describe
or context
blocks) are evaluated
in the context of a new subclass of ExampleGroup. Individual examples are
evaluated in the context of an instance of the specific ExampleGroup
subclass to which they belong.
Besides the class methods defined here, there are other interesting macros defined in Hooks, MemoizedHelpers::ClassMethods and SharedExampleGroup. There are additional instance methods available to your examples defined in MemoizedHelpers and Pending.
Constant Summary collapse
- WrongScopeError =
Raised when an RSpec API is called in the wrong scope, such as
before
being called from within an example rather than from within an example group block. Class.new(NoMethodError)
Metadata collapse
-
.description ⇒ String
The current example group description.
-
.metadata ⇒ void
The Metadata object associated with this group.
-
#described_class ⇒ void
Returns the class or module passed to the
describe
method (or alias).
Defining Examples collapse
-
.example {|Example| ... } ⇒ void
Defines an example within a group.
-
.fexample {|Example| ... } ⇒ void
Shortcut to define an example with
:focus => true
. -
.fit {|Example| ... } ⇒ void
Shortcut to define an example with
:focus => true
. -
.focus {|Example| ... } ⇒ void
Shortcut to define an example with
:focus => true
. -
.fspecify {|Example| ... } ⇒ void
Shortcut to define an example with
:focus => true
. -
.it {|Example| ... } ⇒ void
Defines an example within a group.
-
.pending {|Example| ... } ⇒ void
Shortcut to define an example with
:pending => true
. -
.skip {|Example| ... } ⇒ void
Shortcut to define an example with
:skip => true
. -
.specify {|Example| ... } ⇒ void
Defines an example within a group.
-
.xexample {|Example| ... } ⇒ void
Shortcut to define an example with
:skip => 'Temporarily skipped with xexample'
. -
.xit {|Example| ... } ⇒ void
Shortcut to define an example with
:skip => 'Temporarily skipped with xit'
. -
.xspecify {|Example| ... } ⇒ void
Shortcut to define an example with
:skip => 'Temporarily skipped with xspecify'
.
Including Shared Example Groups collapse
-
.add_example(example) ⇒ void
Adds an example to the example group.
-
.include_context(name, *args, &block) ⇒ void
Includes shared content mapped to
name
directly in the group in which it is declared, as opposed toit_behaves_like
, which creates a nested group. -
.include_examples(name, *args, &block) ⇒ void
Includes shared content mapped to
name
directly in the group in which it is declared, as opposed toit_behaves_like
, which creates a nested group. -
.remove_example(example) ⇒ void
Removes an example from the example group.
Class Method Summary collapse
-
.currently_executing_a_context_hook? ⇒ Boolean
Returns true if a
before(:context)
orafter(:context)
hook is currently executing. -
.id ⇒ String
The unique id of this example group.
-
.run(reporter = RSpec::Core::NullReporter) ⇒ void
Runs all the examples in this group.
Instance Method Summary collapse
-
#initialize(inspect_output = nil) ⇒ ExampleGroup
constructor
A new instance of ExampleGroup.
Methods included from SharedExampleGroup
Methods included from MemoizedHelpers::ClassMethods
Methods included from Hooks
after, append_after, around, before, prepend_before
Methods included from Pending
Methods included from MemoizedHelpers
#is_expected, #should, #should_not, #subject
Constructor Details
#initialize(inspect_output = nil) ⇒ ExampleGroup
Returns a new instance of ExampleGroup.
693 694 695 696 |
# File 'lib/rspec/core/example_group.rb', line 693 def initialize(inspect_output=nil) @__inspect_output = inspect_output || '(no description provided)' super() # no args get passed end |
Dynamic Method Handling
This class handles dynamic methods through the method_missing method
#method_missing(name, *args) ⇒ void (private)
744 745 746 747 748 749 750 751 752 753 754 |
# File 'lib/rspec/core/example_group.rb', line 744 def method_missing(name, *args) if self.class.respond_to?(name) raise WrongScopeError, "`#{name}` is not available from within an example (e.g. an " \ "`it` block) or from constructs that run in the scope of an " \ "example (e.g. `before`, `let`, etc). It is only available " \ "on an example group (e.g. a `describe` or `context` block)." end super end |
Class Method Details
.add_example(example) ⇒ void
Adds an example to the example group
356 357 358 359 |
# File 'lib/rspec/core/example_group.rb', line 356 def self.add_example(example) reset_memoized examples << example end |
.currently_executing_a_context_hook? ⇒ Boolean
Returns true if a before(:context)
or after(:context)
hook is currently executing.
531 532 533 |
# File 'lib/rspec/core/example_group.rb', line 531 def self.currently_executing_a_context_hook? @currently_executing_a_context_hook end |
.description ⇒ String
Returns the current example group description.
85 86 87 88 |
# File 'lib/rspec/core/example_group.rb', line 85 def self.description description = [:description] RSpec.configuration.format_docstrings_block.call(description) end |
.example ⇒ void .example(&example_implementation) ⇒ void .example(doc_string, *metadata_keys, metadata = {}) ⇒ void .example(doc_string, *metadata_keys, metadata = {}, &example_implementation) ⇒ void
Defines an example within a group.
155 |
# File 'lib/rspec/core/example_group.rb', line 155 define_example_method :example |
.fexample ⇒ void .fexample(&example_implementation) ⇒ void .fexample(doc_string, *metadata_keys, metadata = {}) ⇒ void .fexample(doc_string, *metadata_keys, metadata = {}, &example_implementation) ⇒ void
Shortcut to define an example with :focus => true
.
174 |
# File 'lib/rspec/core/example_group.rb', line 174 define_example_method :fexample, :focus => true |
.fit ⇒ void .fit(&example_implementation) ⇒ void .fit(doc_string, *metadata_keys, metadata = {}) ⇒ void .fit(doc_string, *metadata_keys, metadata = {}, &example_implementation) ⇒ void
Shortcut to define an example with :focus => true
.
177 |
# File 'lib/rspec/core/example_group.rb', line 177 define_example_method :fit, :focus => true |
.focus ⇒ void .focus(&example_implementation) ⇒ void .focus(doc_string, *metadata_keys, metadata = {}) ⇒ void .focus(doc_string, *metadata_keys, metadata = {}, &example_implementation) ⇒ void
Shortcut to define an example with :focus => true
.
171 |
# File 'lib/rspec/core/example_group.rb', line 171 define_example_method :focus, :focus => true |
.fspecify ⇒ void .fspecify(&example_implementation) ⇒ void .fspecify(doc_string, *metadata_keys, metadata = {}) ⇒ void .fspecify(doc_string, *metadata_keys, metadata = {}, &example_implementation) ⇒ void
Shortcut to define an example with :focus => true
.
180 |
# File 'lib/rspec/core/example_group.rb', line 180 define_example_method :fspecify, :focus => true |
.id ⇒ String
Returns the unique id of this example group. Pass this at the command line to re-run this exact example group.
662 663 664 |
# File 'lib/rspec/core/example_group.rb', line 662 def self.id Metadata.id_from() end |
.include_context(name, *args, &block) ⇒ void
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.
332 333 334 |
# File 'lib/rspec/core/example_group.rb', line 332 def self.include_context(name, *args, &block) find_and_eval_shared("context", name, caller.first, *args, &block) end |
.include_examples(name, *args, &block) ⇒ void
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.
342 343 344 |
# File 'lib/rspec/core/example_group.rb', line 342 def self.include_examples(name, *args, &block) find_and_eval_shared("examples", name, caller.first, *args, &block) end |
.it ⇒ void .it(&example_implementation) ⇒ void .it(doc_string, *metadata_keys, metadata = {}) ⇒ void .it(doc_string, *metadata_keys, metadata = {}, &example_implementation) ⇒ void
Defines an example within a group. This is the primary API to define a code example.
158 |
# File 'lib/rspec/core/example_group.rb', line 158 define_example_method :it |
.metadata ⇒ void
The Metadata object associated with this group.
51 52 53 |
# File 'lib/rspec/core/example_group.rb', line 51 def self. @metadata ||= nil end |
.pending ⇒ void .pending(&example_implementation) ⇒ void .pending(doc_string, *metadata_keys, metadata = {}) ⇒ void .pending(doc_string, *metadata_keys, metadata = {}, &example_implementation) ⇒ void
Shortcut to define an example with :pending => true
195 |
# File 'lib/rspec/core/example_group.rb', line 195 define_example_method :pending, :pending => true |
.remove_example(example) ⇒ void
Removes an example from the example group
362 363 364 365 |
# File 'lib/rspec/core/example_group.rb', line 362 def self.remove_example(example) reset_memoized examples.delete example end |
.run(reporter = RSpec::Core::NullReporter) ⇒ void
Runs all the examples in this group.
588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 |
# File 'lib/rspec/core/example_group.rb', line 588 def self.run(reporter=RSpec::Core::NullReporter) return if RSpec.world.wants_to_quit reporter.example_group_started(self) should_run_context_hooks = descendant_filtered_examples.any? begin run_before_context_hooks(new('before(:context) hook')) if should_run_context_hooks result_for_this_group = run_examples(reporter) results_for_descendants = ordering_strategy.order(children).map { |child| child.run(reporter) }.all? result_for_this_group && results_for_descendants rescue Pending::SkipDeclaredInExample => ex for_filtered_examples(reporter) { |example| example.skip_with_exception(reporter, ex) } true rescue Support::AllExceptionsExceptOnesWeMustNotRescue => ex for_filtered_examples(reporter) { |example| example.fail_with_exception(reporter, ex) } RSpec.world.wants_to_quit = true if reporter.fail_fast_limit_met? false ensure run_after_context_hooks(new('after(:context) hook')) if should_run_context_hooks reporter.example_group_finished(self) end end |
.skip ⇒ void .skip(&example_implementation) ⇒ void .skip(doc_string, *metadata_keys, metadata = {}) ⇒ void .skip(doc_string, *metadata_keys, metadata = {}, &example_implementation) ⇒ void
Shortcut to define an example with :skip => true
192 |
# File 'lib/rspec/core/example_group.rb', line 192 define_example_method :skip, :skip => true |
.specify ⇒ void .specify(&example_implementation) ⇒ void .specify(doc_string, *metadata_keys, metadata = {}) ⇒ void .specify(doc_string, *metadata_keys, metadata = {}, &example_implementation) ⇒ void
Defines an example within a group.
Useful for when your docstring does not read well off of it
.
167 |
# File 'lib/rspec/core/example_group.rb', line 167 define_example_method :specify |
.xexample ⇒ void .xexample(&example_implementation) ⇒ void .xexample(doc_string, *metadata_keys, metadata = {}) ⇒ void .xexample(doc_string, *metadata_keys, metadata = {}, &example_implementation) ⇒ void
Shortcut to define an example with :skip => 'Temporarily skipped with xexample'
.
183 |
# File 'lib/rspec/core/example_group.rb', line 183 define_example_method :xexample, :skip => 'Temporarily skipped with xexample' |
.xit ⇒ void .xit(&example_implementation) ⇒ void .xit(doc_string, *metadata_keys, metadata = {}) ⇒ void .xit(doc_string, *metadata_keys, metadata = {}, &example_implementation) ⇒ void
Shortcut to define an example with :skip => 'Temporarily skipped with xit'
.
186 |
# File 'lib/rspec/core/example_group.rb', line 186 define_example_method :xit, :skip => 'Temporarily skipped with xit' |
.xspecify ⇒ void .xspecify(&example_implementation) ⇒ void .xspecify(doc_string, *metadata_keys, metadata = {}) ⇒ void .xspecify(doc_string, *metadata_keys, metadata = {}, &example_implementation) ⇒ void
Shortcut to define an example with :skip => 'Temporarily skipped with xspecify'
.
189 |
# File 'lib/rspec/core/example_group.rb', line 189 define_example_method :xspecify, :skip => 'Temporarily skipped with xspecify' |
Instance Method Details
#described_class ⇒ void
Returns the class or module passed to the describe
method (or alias).
Returns nil if the subject is not a class or module.
99 100 101 |
# File 'lib/rspec/core/example_group.rb', line 99 def described_class self.class.described_class end |