Question

What’s the proper way to force an RSpec test to fail?

I’m considering 1.should == 2 however there’s probably something better.

Answer 1

fail/raise will do the trick (they are aliases of each other).

Example

specify "this test fails" do
  raise "this is my failure message"
end

Fails with:

1) failing this test fails
   Failure/Error: raise "this is my failure message"

   RuntimeError:
     this is my failure message

Alternatives

If you are thinking of using raise/fail in a spec, you should consider that there are probably more explicit ways of writing your expectation.

Additionally, raise/fail doesn’t play well with aggregate_failures because the exception short-circuits the block and won’t run any following matchers.

Mark a test as pending

If you need to mark a test as pending to make sure you get back to it, you could use the fail/raise, but you can also use pending.

#  Instead of this:
it "should do something" do
   # ...
   raise "this needs to be implemented"
end

# ✅ Try this:
it "should do something" do
  pending "this needs to be implemented"
end

Assert that a block is not called

If you need to ensure a block is not being executed, consider using the yield matchers. For example:

describe "Enumerable#any?" do
  #  Instead of this:
  it "doesn't yield to the block if the collection is empty" do
    [].any? { raise "it should not call this block" }
  end

  # ✅ Try this:
  it "doesn't yield to the block if the collection is empty" do
    expect { |b| [].any?(&b) }.not_to yield_control
  end
end