Understanding RSpec 2's generated specs

Question

I think I may be biting off more than I can chew by trying to learn RSpec on my own...there doesn't appear to be any complete documentation on RSpec 2?!? at least none that I have been able to find...

Anyway, I, in a feeble attempt to integrate RSpec, started by examining the 29 specs created by the scaffold generator in Rails 3. Some I understand but much still escapes me. Hoping someone can help (or point me to decent RSpec 2 documentation).

For example in the first code block below (def mock_clown...) I can assume mock_clown is creating a mock of my Clown class to test against. But what exactly is going on? what is generating this "mock"? what does .as_null_object and .tap mean? This is very confusing as I can't find an example to compare this block to in any docs or tutorials I've come across...

#clowns_controller_spec.rb

require 'spec_helper'

describe ClownsController do

  def mock_clown(stubs={})
    (@mock_clown ||= mock_model(Clown).as_null_object).tap do |clown|
      clown.stub(stubs) unless stubs.empty?
    end
  end

  describe "GET index" do
    it "assigns all clowns as @clowns" do
      Clown.stub(:all) { [mock_clown] }
      get :index
      assigns(:clowns).should eq([mock_clown])
    end
  end

... 


  describe "POST create" do

...


    describe "with invalid params" do
      it "assigns a newly created but unsaved clown as @clown" do
        Clown.stub(:new).with({'these' => 'params'}) { mock_clown(:save => false) }
        post :create, :clown => {'these' => 'params'}
        assigns(:clown).should be(mock_clown)
      end

      it "re-renders the 'new' template" do
        Clown.stub(:new) { mock_clown(:save => false) }
        post :create, :clown => {}
        response.should render_template("new")
      end
    end

...

end

Answer 1

The best source of documentation for rspec is probably its github wikis. Here's a general link to all gems:https://github.com/rspec/rspec/wiki. Also, checkout the rdoc, linked to here.

As for specific answers, as_null_object causes the mock to record and ignore all method calls. (This is great, as you don't have to spec out every single method on an object, just the ones you care about.)

Tap is a Ruby 1.9 feature. From the documentation at this link:

Object#tap

Passes the object to the block and returns it (meant to be used for call chaining).

For learning Rspec 2 Webrat and Cucumber on your own, I definitely recommend checking out the RSpec Book. Awesome resource, and covers all aspects.