module RSpec::Core::Pending

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

Constants

NOT_YET_IMPLEMENTED: @private
NO_REASON_GIVEN: @private

Public Class Methods

@private

Mark example as fixed.

@param example [RSpec::Core::Example] the example to mark as fixed

# File rspec-core/lib/rspec/core/pending.rb, line 152
def self.mark_fixed!(example)
  example.execution_result.pending_fixed = true
end

mark_pending! (example, message_or_bool)

@private

Mark example as pending.

@param example [RSpec::Core::Example] the example to mark as pending @param message_or_bool [Boolean, String] the message to use, or true

# File rspec-core/lib/rspec/core/pending.rb, line 135
def self.mark_pending!(example, message_or_bool)
  message = if !message_or_bool || !(String === message_or_bool)
              NO_REASON_GIVEN
            else
              message_or_bool
            end

  example.metadata[:pending] = true
  example.execution_result.pending_message = message
  example.execution_result.pending_fixed = false
end

mark_skipped! (example, message_or_bool)

@private

Mark example as skipped.

@param example [RSpec::Core::Example] the example to mark as skipped @param message_or_bool [Boolean, String] the message to use, or true

# File rspec-core/lib/rspec/core/pending.rb, line 124
def self.mark_skipped!(example, message_or_bool)
  Pending.mark_pending! example, message_or_bool
  example.metadata[:skip] = true
end

Public Instance Methods

pending (message=nil, &_block)

@overload pending() @overload pending(message)

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.

@param message [String] optional message to add to the summary report.

@example

describe "some behaviour" 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

@note When using ‘pending` inside an example body using this method

hooks, such as `before(:example)`, have already be run. This means that
a failure from the code in the `before` hook will prevent the example
from being considered pending, as the example body would not be
executed. If you need to consider hooks as pending as well you can use
the pending metadata as an alternative, e.g.
`it "does something", pending: "message"`.

# File rspec-core/lib/rspec/core/pending.rb, line 62
      def pending(message=nil, &_block)
        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 (message=nil)

@overload skip() @overload skip(message)

Marks an example as pending and skips execution.

@param message [String] optional message to add to the summary report.

@example

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

# File rspec-core/lib/rspec/core/pending.rb, line 110
def skip(message=nil)
  current_example = RSpec.current_example

  Pending.mark_skipped!(current_example, message) if current_example

  raise SkipDeclaredInExample.new(message)
end