rspec-rails 2.0.0.beta.22 → 2.6.0

data/features/GettingStarted.md

@@ -0,0 +1,84 @@
+Install Rails-3
+
+    $ gem install rails -v "~> 3.0.0"
+
+### Generate an app
+
+    $ rails new example
+    $ cd example
+
+### Add rspec-rails to the Gemfile
+
+    $ echo 'gem "rspec-rails", :group => [:development, :test]' >> Gemfile
+
+### Install the bundle
+
+    $ bundle install
+
+### Bootstrap RSpec
+
+    $ rails generate rspec:install
+
+### Generate a scaffold
+
+    $ rails generate scaffold Widgets name:string
+
+This generates files in the `app` and `spec` directories. The files in the
+`app` directory are generated by Rails, and Rails delegates the generation of
+the files in the `spec` directory to RSpec.
+
+### Run migrations
+
+    $ rake db:migrate && rake db:test:prepare
+
+### Run RSpec
+
+    $ rake spec
+
+or
+
+    $ rspec spec --format documentation
+
+If all went well, you should see output ending with:
+
+    29 examples, 0 failures, 2 pending
+
+This output also includes the following controller spec:
+
+    WidgetsController
+      GET index
+        assigns all widgets as @widgets
+      GET show
+        assigns the requested widget as @widget
+      GET new
+        assigns a new widget as @widget
+      GET edit
+        assigns the requested widget as @widget
+      POST create
+        with valid params
+          creates a new Widget
+          assigns a newly created widget as @widget
+          redirects to the created widget
+        with invalid params
+          assigns a newly created but unsaved widget as @widget
+          re-renders the 'new' template
+      PUT update
+        with valid params
+          updates the requested widget
+          assigns the requested widget as @widget
+          redirects to the widget
+        with invalid params
+          assigns the widget as @widget
+          re-renders the 'edit' template
+      DELETE destroy
+        destroys the requested widget
+        redirects to the widgets list
+
+Output like this can help to quickly gain a high level understanding of how an
+object behaves. It also exposes which cases have been specified and which have
+not. Note the balance between the examples for the `create` and `update`
+actions. If the `redirects to the widget` example was missing from one or the
+other, it would be easy to spot.
+
+Take a look at the generated `spec/controllers/widgets_controller_spec.rb` to
+get a sense of how to organize your specs to generate output like this.

data/features/README.md

@@ -0,0 +1,58 @@
+rspec-rails extends Rails' built-in testing framework to support rspec examples
+for requests, controllers, models, views, helpers, mailers and routing.
+
+## Rails-3
+
+rspec-rails-2 supports rails-3.0.0 and later. For earlier versions of Rails,
+you need [rspec-rails-1.3](http://rspec.info).
+
+## Install
+
+    gem install rspec-rails
+
+This installs the following gems:
+
+    rspec
+    rspec-core
+    rspec-expectations
+    rspec-mocks
+    rspec-rails
+
+## Configure
+
+Add rspec-rails to the :test and :development groups in the Gemfile:
+
+    group :test, :development do
+      gem "rspec-rails", "~> 2.4"
+    end
+
+It needs to be in the :development group to expose generators and rake tasks
+without having to type RAILS_ENV=test.
+
+Now you can run:
+
+    script/rails generate rspec:install
+
+This adds the spec directory and some skeleton files, including a .rspec
+file.
+
+## Webrat and Capybara
+
+You can choose between webrat or capybara for simulating a browser, automating
+a browser, or setting expectations using the matchers they supply. Just add
+your preference to the Gemfile:
+
+    gem "webrat"
+    gem "capybara"
+
+Note that Capybara matchers are not available in view or helper specs.
+
+## Issues
+
+The documentation for rspec-rails is a work in progress. We'll be adding
+Cucumber features over time, and clarifying existing ones.  If you have
+specific features you'd like to see added, find the existing documentation
+incomplete or confusing, or, better yet, wish to write a missing Cucumber
+feature yourself, please [submit an
+issue](http://github.com/rspec/rspec-rails/issues) or a [pull
+request](http://github.com/rspec/rspec-rails).

data/features/Upgrade.md

@@ -0,0 +1,117 @@
+# Upgrading from rspec-rails-1.x to rspec-rails-2.
+
+This is a work in progress. Please submit errata, missing steps, or patches to
+the [rspec-rails issue tracker](https://github.com/rspec/rspec-rails/issues).
+
+## Rake tasks
+
+Delete lib/tasks/rspec.rake, if present. Rake tasks now live in the rspec-rails
+gem.
+
+## `spec_helper.rb`
+
+There were a few changes to the generated `spec/spec_helper.rb` file. We
+recommend the following:
+
+1. set aside a copy of your existing `spec/spec_helper.rb` file.
+2. run `rails generate rspec:install`
+3. copy any customizations from your old spec_helper to the new one
+
+If you prefer to make the changes manually in the existing spec_helper, here
+is what you need to change:
+
+    # rspec-1
+    require 'spec/autorun'
+
+    Spec::Runner.configure do |config|
+      ...
+    end
+
+    # rspec-2
+    require 'rspec/rails'
+
+    RSpec.configure do |config|
+      ...
+    end
+
+## Controller specs
+
+### islation from view templates
+
+By default, controller specs do _not_ render view templates. This keeps
+controller specs isolated from the content of views and their requirements.
+
+NOTE that the template must exist, but it will not be rendered.  This is
+different from rspec-rails-1.x, in which the template didn't need to exist, but
+ActionController makes a number of new decisions in Rails 3 based on the
+existence of the template. To keep the RSpec code free of monkey patches, and
+to keep the rspec user experience simpler, we decided that this would be a fair
+trade-off.
+
+### `response.should render_template`
+
+This needs to move from before the action to after. For example:
+
+    # rspec-rails-1
+    controller.should render_template("edit")
+    get :edit, :id => "37"
+
+    # rspec-rails-2
+    get :edit, :id => "37"
+    response.should render_template("edit")
+
+rspec-1 had to monkey patch Rails to get render_template to work before the
+action, and this broke a couple of times with Rails releases (requiring urgent
+fix releases in RSpec). Part of the philosophy of rspec-rails-2 is to rely on
+public APIs in Rails as much as possible. In this case, `render_template`
+delegates directly to Rails' `assert_template`, which only works after the
+action.
+
+## View specs
+
+### `view.should render_template`
+
+Rails changed the way it renders partials, so to set an expectation that a
+partial gets rendered, you need
+
+    render
+    view.should render_template(:partial => "widget/_row")
+
+### stub_template
+
+Introduced in rspec-rails-2.2, simulates the presence of view templates on the
+file system. This supports isolation from partials rendered by the vew template
+that is the subject of a view example:
+
+    stub_template "widgets/_widget.html.erb" => "This Content"
+
+### No more `have_tag` or `have_text`
+
+Before Webrat came along, rspec-rails had its own `have_tag` and `have_text`
+matchers that wrapped Rails' `assert_select`. Webrat included replacements for
+these methods, as well as new matchers (`have_selector` and `have_xpath`), all
+of which rely on Nokogiri to do its work, and are far less brittle than RSpec's
+`have_tag`.
+
+Capybara has similar matchers, which will soon be available view specs (they
+are already available in controller specs with `render_views`).
+
+Given the brittleness of RSpec's `have_tag` and `have_text` matchers and the
+presence of new Webrat and Capybara matchers that do a better job, `have_tag`
+and `have_text` were not included in rspec-rails-2.
+
+## Mocks, stubs, doubles
+
+### as_new_record
+
+Earlier versions of the view generators generated stub_model with `:new_record?
+=> true`. That is no longer recognized in rspec-rails-2, so you need to change
+this:
+
+    stub_model(Widget, :new_record? => true)
+
+to this:
+
+    stub_model(Widget).as_new_record
+
+Generators in 2.0.0 final release will do the latter.

data/features/controller_specs/README.md

@@ -0,0 +1,45 @@
+Controller specs live in `spec/controllers` or any example group with
+`:type => :controller`.
+
+A controller spec is an RSpec wrapper for a Rails functional test
+([ActionController::TestCase::Behavior](https://github.com/rails/rails/blob/master/actionpack/lib/action_controller/test_case.rb)).
+It allows you to simulate a single http request in each example, and then
+specify expected outcomes such as:
+
+* rendered templates
+* redirects
+* instance variables assigned in the controller to be shared with the view
+* cookies sent back with the response
+
+To specify outcomes, you can use:
+    
+* standard rspec matchers (`response.code.should eq(200)`)
+* standard test/unit assertions (`assert_equal 200, response.code`)
+* rails assertions (`assert_response 200`)
+* rails-specific matchers:
+  * `response.should render_template (wraps assert_template)`
+  * `response.should redirect_to (wraps assert_redirected_to)`
+  * `assigns(:widget).should be_a_new(Widget)`
+    
+## Examples
+
+    describe TeamsController do
+      describe "GET index" do
+        it "assigns @teams" do
+          team = Team.create
+          get :index
+          assigns(:teams).should eq([team])
+        end
+
+        it "renders the index template" do
+          get :index
+          response.should render_template("index")
+        end
+      end
+    end
+
+## Views
+
+* by default, views are not rendered. See
+  [views are stubbed by default](controller-specs/views-are-stubbed-by-default) and
+  [render_views](controller-specs/render-views) for details.

data/features/controller_specs/anonymous_controller.feature

@@ -1,8 +1,8 @@
 Feature: anonymous controller
 
-  As a Rails developer using RSpec
-  In order to specify behaviour of ApplicationController
-  I want a simple DSL for generating anonymous subclasses
+  Use the `controller` method to define an anonymous controller derived from
+  ApplicationController, or any other base controller. This is useful for
+  specifying behavior like global error handling.
 
   Scenario: specify error handling in ApplicationController
     Given a file named "spec/controllers/application_controller_spec.rb" with:
@@ -36,8 +36,8 @@ Feature: anonymous controller
       end
     end
     """
-    When I run "rspec spec"
-    Then the output should contain "1 example, 0 failures"
+    When I run `rspec spec`
+    Then the examples should all pass
 
   Scenario: specify error handling in subclass of ApplicationController
     Given a file named "spec/controllers/application_controller_subclass_spec.rb" with:
@@ -74,5 +74,5 @@ Feature: anonymous controller
       end
     end
     """
-    When I run "rspec spec"
-    Then the output should contain "1 example, 0 failures"
+    When I run `rspec spec`
+    Then the examples should all pass

data/features/controller_specs/controller_spec.feature

@@ -0,0 +1,18 @@
+Feature: controller spec
+
+  Scenario: simple passing example
+    Given a file named "spec/controllers/widgets_controller_spec.rb" with:
+      """
+      require "spec_helper"
+
+      describe WidgetsController do
+        describe "GET index" do
+          it "has a 200 status code" do
+            get :index
+            response.code.should eq("200")
+          end
+        end
+      end
+      """
+    When I run `rspec spec`
+    Then the example should pass

data/features/controller_specs/isolation_from_views.feature

@@ -1,10 +1,11 @@
-Feature: do not render views
+Feature: views are stubbed by default
 
-  By default, controller specs do not render views. This allows you specify
-  which view template an action should try to render regardless of whether or
-  not the template compiles cleanly.
+  By default, controller specs stub views with a template that renders an empty
+  string instead of the views in the app. This allows you specify which view
+  template an action should try to render regardless of whether the template
+  compiles cleanly.
 
-  NOTE: unlike rspec-rails-1.x, the template must exist.
+  NOTE: unlike rspec-rails-1.x, the real template must exist.
 
   Scenario: expect template that is rendered by controller action (passes)
     Given a file named "spec/controllers/widgets_controller_spec.rb" with:
@@ -26,8 +27,8 @@ Feature: do not render views
         end
       end
       """
-    When I run "rspec ./spec"
-    Then the output should contain "2 examples, 0 failures"
+    When I run `rspec spec`
+    Then the examples should all pass
 
   Scenario: expect template that is not rendered by controller action (fails)
     Given a file named "spec/controllers/widgets_controller_spec.rb" with:
@@ -43,6 +44,52 @@ Feature: do not render views
         end
       end
       """
-    When I run "rspec ./spec"
+    When I run `rspec spec`
     Then the output should contain "1 example, 1 failure"
 
+  Scenario: expect empty templates to render when view path is changed at runtime (passes)
+    Given a file named "spec/controllers/things_controller_spec.rb" with:
+      """
+      require "spec_helper"
+
+      describe ThingsController do
+        describe "custom_action" do
+          it "renders an empty custom_action template" do
+            controller.prepend_view_path 'app/views'
+            controller.append_view_path 'app/views'
+            get :custom_action
+            response.should render_template("custom_action")
+            response.body.should == ""
+          end
+        end
+      end
+      """
+    When I run `rspec spec`
+    Then the examples should all pass
+
+  Scenario: expect template to render when view path is changed at runtime (fails)
+    Given a file named "spec/controllers/things_controller_spec.rb" with:
+      """
+      require "spec_helper"
+
+      describe ThingsController do
+        describe "custom_action" do
+          it "renders the custom_action template" do
+            render_views
+            controller.prepend_view_path 'app/views'
+            get :custom_action
+            response.should render_template("custom_action")
+            response.body.should == ""
+          end
+
+          it "renders an empty custom_action template" do
+            controller.prepend_view_path 'app/views'
+            get :custom_action
+            response.should render_template("custom_action")
+            response.body.should == ""
+          end
+        end
+      end
+      """
+    When I run `rspec spec`
+    Then the output should contain "2 examples, 1 failure"

data/features/controller_specs/render_views.feature

@@ -1,9 +1,9 @@
-Feature: render views
+Feature: render_views
 
-  You can tell a controller example group to render views with the render_views
-  declaration.
+  You can tell a controller example group to render views with the
+  `render_views` declaration in any individual group, or globally.
 
-  Scenario: expect template that exists and is rendered by controller (passes)
+  Scenario: render_views directly in a single group
     Given a file named "spec/controllers/widgets_controller_spec.rb" with:
       """
       require "spec_helper"
@@ -11,48 +11,18 @@ Feature: render views
       describe WidgetsController do
         render_views
 
-        describe "index" do
-          it "renders the index template" do
-            get :index
-            response.should contain("Listing widgets")
-          end
-
-          it "renders the widgets/index template" do
-            get :index
-            response.should contain("Listing widgets")
-          end
-        end
-      end
-      """
-    When I run "rspec spec"
-    Then the output should contain "2 examples, 0 failures"
-
-  Scenario: expect template that does not exist and is rendered by controller (fails)
-    Given a file named "spec/controllers/widgets_controller_spec.rb" with:
-      """
-      require "spec_helper"
-
-      describe WidgetsController do
-        render_views
-
-        before do
-          def controller.index
-            render :template => "other"
-          end
-        end
-
-        describe "index" do
-          it "renders the other template" do
+        describe "GET index" do
+          it "says 'Listing widgets'" do
             get :index
+            response.body.should =~ /Listing widgets/m
           end
         end
       end
       """
-    When I run "rspec spec"
-    Then the output should contain "1 example, 1 failure"
-    And the output should contain "Missing template"
+    When I run `rspec spec`
+    Then the examples should all pass
 
-  Scenario: render_views on and off in diff contexts
+  Scenario: render_views on and off in nested groups
     Given a file named "spec/controllers/widgets_controller_spec.rb" with:
       """
       require "spec_helper"
@@ -61,19 +31,30 @@ Feature: render views
         context "with render_views" do
           render_views
 
-          describe "index" do
+          describe "GET index" do
             it "renders the actual template" do
               get :index
               response.body.should =~ /Listing widgets/m
             end
           end
+
+          context "with render_views(false) nested in a group with render_views" do
+            render_views false
+
+            describe "GET index" do
+              it "renders the RSpec generated template" do
+                get :index
+                response.body.should eq("")
+              end
+            end
+          end
         end
 
         context "without render_views" do
-          describe "index" do
+          describe "GET index" do
             it "renders the RSpec generated template" do
               get :index
-              response.body.should == ""
+              response.body.should eq("")
             end
           end
         end
@@ -81,23 +62,53 @@ Feature: render views
         context "with render_views again" do
           render_views
 
-          describe "index" do
+          describe "GET index" do
             it "renders the actual template" do
               get :index
               response.body.should =~ /Listing widgets/m
             end
           end
         end
+      end
+      """
+    When I run `rspec spec --format documentation`
+    Then the output should contain:
+      """
+      WidgetsController
+        with render_views
+          GET index
+            renders the actual template
+          with render_views(false) nested in a group with render_views
+            GET index
+              renders the RSpec generated template
+        without render_views
+          GET index
+            renders the RSpec generated template
+        with render_views again
+          GET index
+            renders the actual template
+      """
 
-        context "without render_views again" do
-          describe "index" do
-            it "renders the RSpec generated template" do
-              get :index
-              response.body.should == ""
-            end
+  Scenario: render_views globally
+    Given a file named "spec/support/render_views.rb" with:
+      """
+      RSpec.configure do |config|
+        config.render_views
+      end
+      """
+    And a file named "spec/controllers/widgets_controller_spec.rb" with:
+      """
+      require "spec_helper"
+
+      describe WidgetsController do
+        describe "GET index" do
+          it "renders the index template" do
+            get :index
+            response.body.should =~ /Listing widgets/m
           end
         end
       end
       """
-    When I run "rspec spec"
-    Then the output should contain "4 examples, 0 failures"
+    When I run `rspec spec`
+    Then the examples should all pass
+    

data/features/helper_specs/helper_spec.feature

@@ -1,7 +1,8 @@
 Feature: helper spec
   
-  Helper specs live in spec/helpers. In order to access
-  the helper methods you can call them on the "helper" object.
+  Helper specs live in `spec/helpers`, or any example group with `:type =>
+  :helper`. In order to access the helper methods you can call them on the
+  `helper` object.
   
   Scenario: helper method that returns true
     Given a file named "spec/helpers/application_helper_spec.rb" with:
@@ -24,8 +25,8 @@ Feature: helper spec
         end
       end
       """
-    When I run "rspec spec/helpers/application_helper_spec.rb"
-    Then the output should contain "1 example, 0 failures"
+    When I run `rspec spec/helpers/application_helper_spec.rb`
+    Then the examples should all pass
     
   Scenario: helper method that accesses an instance variable
     Given a file named "spec/helpers/application_helper_spec.rb" with:
@@ -49,5 +50,38 @@ Feature: helper spec
         end
       end
       """
-    When I run "rspec spec/helpers/application_helper_spec.rb"
-    Then the output should contain "1 example, 0 failures"
+    When I run `rspec spec/helpers/application_helper_spec.rb`
+    Then the examples should all pass
+
+  Scenario: application helper is included in helper object
+    Given a file named "spec/helpers/widgets_helper_spec.rb" with:
+      """
+      require "spec_helper"
+
+      describe WidgetsHelper do
+        describe "#page_title" do
+          it "includes the app name" do
+            assign(:title, "This Page")
+            helper.page_title.should eq("The App: This Page")
+          end
+        end
+      end
+      """
+    And a file named "app/helpers/application_helper.rb" with:
+      """
+      module ApplicationHelper
+        def app_name
+          "The App"
+        end
+      end
+      """
+    And a file named "app/helpers/widgets_helper.rb" with:
+      """
+      module WidgetsHelper
+        def page_title
+          "#{app_name}: #{@title}"
+        end
+      end
+      """
+    When I run `rspec spec/helpers/widgets_helper_spec.rb`
+    Then the examples should all pass

data/features/mailer_specs/url_helpers.feature

@@ -15,8 +15,8 @@ Feature: URL helpers in mailer examples
         end
       end
       """
-    When I run "rspec spec"
-    Then the output should contain "1 example, 0 failures"
+    When I run `rspec spec`
+    Then the examples should all pass
 
   Scenario: using URL helpers without default options
     Given a file named "config/initializers/mailer_defaults.rb" with:
@@ -34,5 +34,5 @@ Feature: URL helpers in mailer examples
         end
       end
       """
-    When I run "rspec spec"
-    Then the output should contain "1 example, 0 failures"
+    When I run `rspec spec`
+    Then the examples should all pass