= Remarkable Rails

Remarkable Rails is a collection of matchers to Rails. This package has some
ActionController matchers and soon some ActionView matchers.

Whenever using the Remarkable Rails gem, it will automatically add your ActiveRecord
matchers. So just one line is needed to install both:

  sudo gem install remarkable_rails

If you are using Rails 2.3, you need to have this configuration on your
config/environments/test.rb:

  config.gem "rspec",            :lib => false
  config.gem "rspec-rails",      :lib => false
  config.gem "remarkable_rails", :lib => false

And then require remarkable inside your spec_helper.rb, after "spec/rails":

  require 'spec/rails'
  require 'remarkable_rails'

== Matchers & Macros

The supported matchers and macros are:

  assign_to, filter_params, render_with_layout, respond_with, 
  respond_with_content_type, route, set_session and set_the_flash matchers.

In Remarkable 3.0, we also ported and extended redirect to and render template
from rspec rails matchers to provide I18n. You can also do:

  render_template 'edit', :layout => 'default'
  respond_with 404, :content_type => Mime::XML, :body => /Not found/

== Macro stubs

Another cool feature in Remarkable 3.0 is macro stubs, which makes your mocks
and stubs DRY and easier to maintain. An rspec default scaffold would be:

  describe TasksController do
    def mock_task(stubs={})
      @task ||= mock_model(Task, stubs)
    end

    describe “responding to #POST create” do
      it "exposes a newly created task as @task" do
        Task.should_receive(:new).with({'these' => 'params'}).
                                  and_return(mock_task(:save => true))
        post :create, :task => {:these => 'params'}
        assigns[:task].should equal(mock_task)
      end

      it "redirects to the created task" do
        Task.stub!(:new).and_return(mock_task(:save => true))
        post :create, :task => {}
        response.should redirect_to(task_url(mock_task))
      end
    end
  end

An equivalent in remarkable would be:

  describe TasksController do
    mock_models :task

    describe :post => :create, :task => { :these => 'params' } do
      expects :new,  :on => Task, :with => {'these' => 'params'}, :returns => task_proc
      expects :save, :on => task_proc, :returns => true

      should_assign_to :task, :with => task_proc
      should_redirect_to { task_url(mock_task) }
    end
  end

It automatically performs the action before running each macro. It executes the
expects as expectations (:should_receive), but you can supply :with_stubs => true
if you want it to be executed with stubs.

There are also params and mime methods:

  describe TasksController
    params :project_id => 42
    mime Mime::HTML

    describe :get => :show, :id => 37 do
      should_assign_to :project, :task

      describe Mime::XML do
        should_assign_to :project, :task
      end
    end
  end

And much more. Be sure to check macro stubs documentation.

== Rails plugin developers

Remarkable automatically loads files at the remarkable directory on your plugins
and frozen gems if RAILS_ROOT is defined. The lookup happens like this:

  RAILS_ROOT/spec/remarkable
  RAILS_ROOT/vendor/gems/*/remarkable
  RAILS_ROOT/vendor/plugins/*/remarkable

Remarkable will load both ruby files (.rb) and Remarkable locale files (.yml).

The only step remaining is to include the matchers, which Remarkable will not
do automatically if the user is not using a Remarkable namespace. For example,
if the developer includes his matchers to Remarkable::ActiveRecord::Matchers,
the matchers will be automatically available in users spec. But if he creates
a new namespace, like MyPlugin::Matchers, he has to tell Remarkable to include
them in the proper example group:

  Remarkable.include_matchers!(MyPlugin::Matchers, Spec::Rails::Example::ModelExampleGroup)