foo_spec.rb

describe "Widget#foo" do
  it "does something" do
    # This should be the functionality specs specific to the semantics of the method
    Widget.new.foo.should == "do something"
  end
end

# This captures the "type signature" of the method. Here are recipes for corner cases that you might forget.
# Note that the examples are not self-consistent by design. Only some of them might apply to any given method.
# However, the goal below is to include the union of all possible examples so that you can cut and paste
# the ones that apply to the specific method you are writing specs for

describe "Widget#foo type signature" do
  before :each do
    @widget = Widget.new
  end

  it "returns self" do
    @widget.foo.should equal(@widget)
  end

  it "returns nil" do
    @widget.foo.should be_nil
  end

  it "accepts a string-like and a Fixnum-like argument" do
    arg1 = mock("arg1")
    arg1.should_receive(:to_s).and_return("Hello")
    arg2 = mock("arg2")
    arg2.should_receive(:to_int).and_return(123)
    @widget.foo(arg1, arg2).should == @widget.foo("Hello", 123)
  end

  it "accepts a Bignum for arg2" do
    @widget.foo("Hello", bignum_value(1)).should == "some result"
  end

  it "raises TypeError if arguments are not a string and a Fixnum" do
    lambda{ @widget.foo("Hello", []) }.should raise_error(TypeError)
    lambda{ @widget.foo([], 123) }.should raise_error(TypeError)
  end

  it "raises TypeError if argument is nil" do
    lambda{ @widget.foo(nil) }.should raise_error(TypeError)
  end

  #
  # For methods which take a block
  #
  
  it "raises LocalJumpError if no block is given" do
    lambda{ @widget.foo }.should raise_error(LocalJumpError)
  end

  it "returns the result of the block" do
    @widget.foo { :end_of_block }.should == :end_of_block
  end

  it "calls block with a SomeType argument" do
    @widget.foo do {|arg1|
      arg1.should be_kind_of(SomeType)
    end
  end

  it "propagates exception raised inside block" do
    lambda { @widget.foo { raise "exception from block" }.should raise_error(RuntimeError)
  end

  it "rescues exception raised inside block" do
    @widget.foo { raise "exception from block" }.should == "some result"
  end

  def WidgetSpecs.call_foo_with_block_that_returns
    @widget.foo { return :return_from_block }
    flunk
  end
  
  it "allows return from block" do
    WidgetSpecs.call_foo_with_block_that_returns.should == :return_from_block
  end
end