Using rspec-expectations gem to validate arguments in an API

Question

So, let's say I'm writing an API to make delicious frosted cakes. It's all nice and documented, but occasionally an error squeezes through, or maybe the user is exploring the library via IRB and has fat-fingered a variable while they're prototyping away.

This is how I normally indicate to callers that a parameter must not be nil / has other constraints:

# Cake.rb
def make_cake(cake_type, *arguments)
  raise "cake_type required!" unless !cake_type.nil?
  raise "cake_type must be in KNOWN_CAKES" unless KNOWN_CAKES.include?(cake_type)
  # blah blah blah
end

However, I've recently considered something like this, using the rspec-expectations gem:

# Cake.rb
include RSpec::Matchers
def make_cake(cake_type, *arguments)
  cake_type.should_not be_nil, "cake_type required"
  KNOWN_CAKES.should include(cake_type), "cake_type not found"
end

The pros:

• terse DSL makes it a real easy read for people developing against the API.
• RSpec::Expectations::ExpectationNotMetError has some nice exception formatting, giving you the expected value vs the actual received value.

The con(s?):

• RSpec::Expectations::ExpectationNotMetError might be a little too verbose.

So, this approach: good idea, or bad idea? What design principles does it violate?

Answer 1

As a caller, I'd be surprised to get an RSpec exception back from an API call.

Do you really gain much? What if you just change to raise 'cake type required!' if cake_type.nil?. Seems to read clearer than your original code to me. Perhaps you wrote it like that so that you'd be using unless both times?

Couldn't you achieve your goal of passing back expected/received values simply by raising better messages - perhaps via your own exception class?