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'
.
Defining Example Groups collapse
-
.context ⇒ RSpec::Core::ExampleGroup
An alias of
example_group
. -
.describe ⇒ RSpec::Core::ExampleGroup
An alias of
example_group
. -
.example_group ⇒ RSpec::Core::ExampleGroup
Generates a subclass of this example group which inherits everything except the examples themselves.
-
.fcontext ⇒ RSpec::Core::ExampleGroup
Shortcut to define an example group with
:focus => true
. -
.fdescribe ⇒ RSpec::Core::ExampleGroup
Shortcut to define an example group with
:focus => true
. -
.xcontext ⇒ RSpec::Core::ExampleGroup
Shortcut to temporarily make an example group skipped.
-
.xdescribe ⇒ RSpec::Core::ExampleGroup
Shortcut to temporarily make an example group skipped.
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. - .it_behaves_like(name, *args, &block) ⇒ RSpec::Core::ExampleGroup
- .it_should_behave_like(name, *args, &block) ⇒ RSpec::Core::ExampleGroup
-
.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.
Methods included from Hooks
after, append_after, around, before, prepend_before
Methods included from MemoizedHelpers::ClassMethods
Methods included from SharedExampleGroup
Methods included from Pending
Methods included from MemoizedHelpers
#is_expected, #should, #should_not, #subject
Class Method Details
.add_example(example) ⇒ void
Adds an example to the example group
374 375 376 377 |
# File 'lib/rspec/core/example_group.rb', line 374 def self.add_example(example) reset_memoized examples << example end |
.context ⇒ RSpec::Core::ExampleGroup .context(&example_group_definition) ⇒ RSpec::Core::ExampleGroup .context(doc_string, *metadata, &example_implementation) ⇒ RSpec::Core::ExampleGroup
An alias of example_group
. Generally used when grouping examples
contextually (e.g. "with xyz", "when xyz" or "if xyz").
Generates a subclass of this example group which inherits
everything except the examples themselves.
292 |
# File 'lib/rspec/core/example_group.rb', line 292 define_example_group_method :context |
.currently_executing_a_context_hook? ⇒ Boolean
Returns true if a before(:context)
or after(:context)
hook is currently executing.
549 550 551 |
# File 'lib/rspec/core/example_group.rb', line 549 def self.currently_executing_a_context_hook? @currently_executing_a_context_hook end |
.describe ⇒ RSpec::Core::ExampleGroup .describe(&example_group_definition) ⇒ RSpec::Core::ExampleGroup .describe(doc_string, *metadata, &example_implementation) ⇒ RSpec::Core::ExampleGroup
An alias of example_group
. Generally used when grouping examples by a
thing you are describing (e.g. an object, class or method).
Generates a subclass of this example group which inherits
everything except the examples themselves.
287 |
# File 'lib/rspec/core/example_group.rb', line 287 define_example_group_method :describe |
.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) ⇒ void .example(doc_string, *metadata, &example_implementation) ⇒ void
Defines an example within a group.
158 |
# File 'lib/rspec/core/example_group.rb', line 158 define_example_method :example |
.example_group ⇒ RSpec::Core::ExampleGroup .example_group(&example_group_definition) ⇒ RSpec::Core::ExampleGroup .example_group(doc_string, *metadata, &example_implementation) ⇒ RSpec::Core::ExampleGroup
Generates a subclass of this example group which inherits everything except the examples themselves.
282 |
# File 'lib/rspec/core/example_group.rb', line 282 define_example_group_method :example_group |
.fcontext ⇒ RSpec::Core::ExampleGroup .fcontext(&example_group_definition) ⇒ RSpec::Core::ExampleGroup .fcontext(doc_string, *metadata, &example_implementation) ⇒ RSpec::Core::ExampleGroup
Shortcut to define an example group with :focus => true
.
Generates a subclass of this example group which inherits
everything except the examples themselves.
308 |
# File 'lib/rspec/core/example_group.rb', line 308 define_example_group_method :fcontext, :focus => true |
.fdescribe ⇒ RSpec::Core::ExampleGroup .fdescribe(&example_group_definition) ⇒ RSpec::Core::ExampleGroup .fdescribe(doc_string, *metadata, &example_implementation) ⇒ RSpec::Core::ExampleGroup
Shortcut to define an example group with :focus => true
.
Generates a subclass of this example group which inherits
everything except the examples themselves.
304 |
# File 'lib/rspec/core/example_group.rb', line 304 define_example_group_method :fdescribe, :focus => true |
.fexample ⇒ void .fexample(&example_implementation) ⇒ void .fexample(doc_string, *metadata) ⇒ void .fexample(doc_string, *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 :fexample, :focus => true |
.fit ⇒ void .fit(&example_implementation) ⇒ void .fit(doc_string, *metadata) ⇒ void .fit(doc_string, *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 :fit, :focus => true |
.focus ⇒ void .focus(&example_implementation) ⇒ void .focus(doc_string, *metadata) ⇒ void .focus(doc_string, *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 :focus, :focus => true |
.fspecify ⇒ void .fspecify(&example_implementation) ⇒ void .fspecify(doc_string, *metadata) ⇒ void .fspecify(doc_string, *metadata, &example_implementation) ⇒ void
Shortcut to define an example with :focus => true
.
183 |
# File 'lib/rspec/core/example_group.rb', line 183 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.
682 683 684 |
# File 'lib/rspec/core/example_group.rb', line 682 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.
350 351 352 |
# File 'lib/rspec/core/example_group.rb', line 350 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.
360 361 362 |
# File 'lib/rspec/core/example_group.rb', line 360 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) ⇒ void .it(doc_string, *metadata, &example_implementation) ⇒ void
Defines an example within a group. This is the primary API to define a code example.
161 |
# File 'lib/rspec/core/example_group.rb', line 161 define_example_method :it |
.it_behaves_like(name, *args, &block) ⇒ RSpec::Core::ExampleGroup
339 |
# File 'lib/rspec/core/example_group.rb', line 339 define_nested_shared_group_method :it_behaves_like, "behaves like" |
.it_should_behave_like(name, *args, &block) ⇒ RSpec::Core::ExampleGroup
342 |
# File 'lib/rspec/core/example_group.rb', line 342 define_nested_shared_group_method :it_should_behave_like |
.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) ⇒ void .pending(doc_string, *metadata, &example_implementation) ⇒ void
Shortcut to define an example with :pending => true
198 |
# File 'lib/rspec/core/example_group.rb', line 198 define_example_method :pending, :pending => true |
.remove_example(example) ⇒ void
Removes an example from the example group
380 381 382 383 |
# File 'lib/rspec/core/example_group.rb', line 380 def self.remove_example(example) reset_memoized examples.delete example end |
.run(reporter = RSpec::Core::NullReporter) ⇒ void
Runs all the examples in this group.
606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 |
# File 'lib/rspec/core/example_group.rb', line 606 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 RSpec.current_scope = :before_context_hook 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 RSpec.current_scope = :after_context_hook 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) ⇒ void .skip(doc_string, *metadata, &example_implementation) ⇒ void
Shortcut to define an example with :skip => true
195 |
# File 'lib/rspec/core/example_group.rb', line 195 define_example_method :skip, :skip => true |
.specify ⇒ void .specify(&example_implementation) ⇒ void .specify(doc_string, *metadata) ⇒ void .specify(doc_string, *metadata, &example_implementation) ⇒ void
Defines an example within a group.
Useful for when your docstring does not read well off of it
.
170 |
# File 'lib/rspec/core/example_group.rb', line 170 define_example_method :specify |
.xcontext ⇒ RSpec::Core::ExampleGroup .xcontext(&example_group_definition) ⇒ RSpec::Core::ExampleGroup .xcontext(doc_string, *metadata, &example_implementation) ⇒ RSpec::Core::ExampleGroup
Shortcut to temporarily make an example group skipped. Generates a subclass of this example group which inherits everything except the examples themselves.
300 |
# File 'lib/rspec/core/example_group.rb', line 300 define_example_group_method :xcontext, :skip => "Temporarily skipped with xcontext" |
.xdescribe ⇒ RSpec::Core::ExampleGroup .xdescribe(&example_group_definition) ⇒ RSpec::Core::ExampleGroup .xdescribe(doc_string, *metadata, &example_implementation) ⇒ RSpec::Core::ExampleGroup
Shortcut to temporarily make an example group skipped. Generates a subclass of this example group which inherits everything except the examples themselves.
296 |
# File 'lib/rspec/core/example_group.rb', line 296 define_example_group_method :xdescribe, :skip => "Temporarily skipped with xdescribe" |
.xexample ⇒ void .xexample(&example_implementation) ⇒ void .xexample(doc_string, *metadata) ⇒ void .xexample(doc_string, *metadata, &example_implementation) ⇒ void
Shortcut to define an example with :skip => 'Temporarily skipped with xexample'
.
186 |
# File 'lib/rspec/core/example_group.rb', line 186 define_example_method :xexample, :skip => 'Temporarily skipped with xexample' |
.xit ⇒ void .xit(&example_implementation) ⇒ void .xit(doc_string, *metadata) ⇒ void .xit(doc_string, *metadata, &example_implementation) ⇒ void
Shortcut to define an example with :skip => 'Temporarily skipped with xit'
.
189 |
# File 'lib/rspec/core/example_group.rb', line 189 define_example_method :xit, :skip => 'Temporarily skipped with xit' |
.xspecify ⇒ void .xspecify(&example_implementation) ⇒ void .xspecify(doc_string, *metadata) ⇒ void .xspecify(doc_string, *metadata, &example_implementation) ⇒ void
Shortcut to define an example with :skip => 'Temporarily skipped with xspecify'
.
192 |
# File 'lib/rspec/core/example_group.rb', line 192 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 |