@overload pending() @overload pending(message) @overload pending(message, &block)

Stops execution of an example, and reports it as pending. Takes an optional message and block.

@param [String] message optional message to add to the summary report. @param [Block] block optional block. If it fails, the example is

  reported as pending. If it executes cleanly the example fails.

@example

    describe "an example" do
      # reported as "Pending: no reason given"
      it "is pending with no message" do
        pending
        this_does_not_get_executed
      end

      # reported as "Pending: something else getting finished"
      it "is pending with a custom message" do
        pending("something else getting finished")
        this_does_not_get_executed
      end

      # reported as "Pending: something else getting finished"
      it "is pending with a failing block" do
        pending("something else getting finished") do
          raise "this is the failure"
        end
      end

      # reported as failure, saying we expected the block to fail but
      # it passed.
      it "is pending with a passing block" do
        pending("something else getting finished") do
          true.should be(true)
        end
      end
    end

@note `before(:each)` 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