Module: RSpec::Core::Pending

Included in:
ExampleGroup
Defined in:
lib/rspec/core/pending.rb

Overview

Provides methods to mark examples as pending. These methods are available to be called from within any example or hook.

Defined Under Namespace

Classes: SkipDeclaredInExample

Instance Method Summary collapse

Instance Method Details

#pending ⇒ void #pending(message) ⇒ void

Note:

before(:example) hooks are eval'd when you use the pending method within an example. If you want to declare an example pending and bypass the before hooks as well, you can pass :pending => true to the it method:

it "does something", :pending => true do
  # ...
end

or pass :pending => "something else getting finished" to add a message to the summary report:

it "does something", :pending => "something else getting finished" do
  # ...
end

Marks an example as pending. The rest of the example will still be executed, and if it passes the example will fail to indicate that the pending can be removed.

Examples:

describe "an example" do
  # reported as "Pending: no reason given"
  it "is pending with no message" do
    pending
    raise "broken"
  end
  # reported as "Pending: something else getting finished"
  it "is pending with a custom message" do
    pending("something else getting finished")
    raise "broken"
  end
end

Parameters:

  • message (String) (defaults to: nil) —

    optional message to add to the summary report.

70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/rspec/core/pending.rb', line 70
def pending(message=nil)
  current_example = RSpec.current_example
  if block_given?
    raise ArgumentError, <<-EOS.gsub(/^\s+\|/, '')
      |The semantics of `RSpec::Core::Pending#pending` have changed in
      |RSpec 3. In RSpec 2.x, it caused the example to be skipped. In
      |RSpec 3, the rest of the example is still run but is expected to
      |fail, and will be marked as a failure (rather than as pending) if
      |the example passes.
      |
      |Passing a block within an example is now deprecated. Marking the
      |example as pending provides the same behavior in RSpec 3 which was
      |provided only by the block in RSpec 2.x.
      |
      |Move the code in the block provided to `pending` into the rest of
      |the example body.
      |
      |Called from #{CallerFilter.first_non_rspec_line}.
      |
    EOS
  elsif current_example
    Pending.mark_pending! current_example, message
  else
    raise "`pending` may not be used outside of examples, such as in " \
          "before(:context). Maybe you want `skip`?"
  end
end

#skip ⇒ void #skip(message) ⇒ void

Marks an example as pending and skips execution.

Examples:

describe "an example" do
  # reported as "Pending: no reason given"
  it "is skipped with no message" do
    skip
  end
  # reported as "Pending: something else getting finished"
  it "is skipped with a custom message" do
    skip "something else getting finished"
  end
end

Parameters:

  • message (String) (defaults to: nil) —

    optional message to add to the summary report.

Raises:

118
119
120
121
122
123
124
 
# File 'lib/rspec/core/pending.rb', line 118
def skip(message=nil)
  current_example = RSpec.current_example
  Pending.mark_skipped!(current_example, message) if current_example
  raise SkipDeclaredInExample.new(message)
end