rspec-rails 2.3.1 → 2.4.0

data/History.md

@@ -1,8 +1,28 @@
 ## rspec-rails-2 release history
 
+### 2.4.0 / 2011-01-02
+
+[full changelog](http://github.com/rspec/rspec-rails/compare/v2.3.1...2.4.0)
+
+* Enhancements
+  * include ApplicationHelper in helper object in helper specs
+  * include request spec extensions in files in spec/integration
+  * include controller spec extensions in groups that use :type => :controller
+    * same for :model, :view, :helper, :mailer, :request, :routing
+
+* Bug fixes
+  * restore global config.render_views so you only need to say it once
+  * support overriding render_views in nested groups
+  * matchers that delegate to Rails' assertions capture
+    ActiveSupport::TestCase::Assertion (so they work properly now with
+    should_not in Ruby 1.8.7 and 1.9.1)
+
+* Deprecations
+  * include_self_when_dir_matches
+
 ### 2.3.1 / 2010-12-16
 
-[full changelog](http://github.com/rspec/rspec-rails/compare/v2.3.0...master)
+[full changelog](http://github.com/rspec/rspec-rails/compare/v2.3.0...v2.3.1)
 
 * Bug fixes
   * respond_to? correctly handles 2 args

data/README.md

@@ -60,7 +60,7 @@ out of the box for the default scenario (`ActiveRecord` + `Webrat`).
 
 ### Autotest
 
-The `rspec:install` generator creates an `./autotest/discover.rb` file, which
+The `rspec:install` generator creates an `.rspec` file, which
 tells Autotest that you're using RSpec and Rails. You'll also need to add the
 autotest (not autotest-rails) gem to your Gemfile:
 
@@ -142,8 +142,8 @@ You can use RSpec expectations/matchers or Test::Unit assertions.
 ## `render_views`
 By default, controller specs do not render views.  This supports specifying
 controllers without concern for whether the views they render work correctly
-(NOTE: the template must exist, unlike rspec-rails-1. See Upgrade.markdown for
-more information about this). If you prefer to render the views (a la Rails'
+(NOTE: the template must exist, unlike rspec-rails-1. See Upgrade.md for more
+information about this). If you prefer to render the views (a la Rails'
 functional tests), you can use the `render_views` declaration in each example
 group:
 

data/Rakefile

@@ -105,10 +105,10 @@ namespace :clobber do
   end
 end
 
-desc "Push cukes to relishapp using the relish-client-gem"
+desc "Push docs/cukes to relishapp using the relish-client-gem"
 task :relish, :version do |t, args|
   raise "rake relish[VERSION]" unless args[:version]
-  sh "relish push --organization rspec --project rspec-rails -v #{args[:version]}"
+  sh "relish push rspec/rspec-rails:#{args[:version]}"
 end
 
 task :default => [:spec, "clobber:app", "generate:app", "generate:stuff", :smoke, :cucumber]

data/features/.nav

@@ -1,10 +1,10 @@
+- GettingStarted.md (Getting started)
+- Upgrade.md
+- Generators.md (Rails generators)
+- Autotest.md (Autotest integration)
+- transactional_examples.feature
 - model_specs:
-  - transactional_examples.feature
   - errors_on.feature
-- view_specs:
-  - view_spec.feature
-  - stub_template.feature
-  - inferred_controller_path.feature
 - controller_specs:
   - controller_spec.feature
   - isolation_from_views.feature
@@ -15,12 +15,17 @@
 - mailer_specs:
   - url_helpers.feature
 - routing_specs:
-  - access_to_named_routes.feature
+  - route_to_matcher.feature
+  - be_routable_matcher.feature
+  - named_routes.feature
+- view_specs:
+  - view_spec.feature
+  - stub_template.feature
+  - inferred_controller_path.feature
 - matchers:
   - new_record_matcher.feature
   - render_template_matcher.feature
   - redirect_to_matcher.feature
-  - be_routable_matcher.feature
 - mocks:
   - mock_model.feature
   - stub_model.feature

data/features/Autotest.md

@@ -0,0 +1,10 @@
+The rspec:install generator creates a .rspec file, which tells RSpec to tell
+Autotest that you're using RSpec and Rails. You'll also need to add the ZenTest
+gem to your Gemfile:
+
+    gem "ZenTest"
+
+At this point, if all of the gems in your Gemfile are installed in system gems,
+you can just type autotest. If, however, Bundler is managing any gems for you
+directly (i.e. you've got :git or :path attributes in the Gemfile), you'll need
+to run bundle exec autotest.

data/features/Generators.md

@@ -0,0 +1,8 @@
+If you type script/rails generate, the only RSpec generator you'll actually see
+is rspec:install. That's because RSpec is registered with Rails as the test
+framework, so whenever you generate application components like models,
+controllers, etc, RSpec specs are generated instead of Test::Unit tests.
+
+Note that the generators are there to help you get started, but they are no
+substitute for writing your own examples, and they are only guaranteed to work
+out of the box for the default scenario (ActiveRecord + Webrat).

data/features/GettingStarted.md

@@ -0,0 +1,40 @@
+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
+
+### 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
+
+If all went well, you should see output ending with:
+
+    29 examples, 0 failures, 2 pending

data/features/{README.markdown → README.md}

@@ -1,5 +1,5 @@
 rspec-rails extends Rails' built-in testing framework to support rspec examples
-for requests, controllers, models, views, and helpers.
+for requests, controllers, models, views, helpers, mailers and routing.
 
 ## Rails-3
 
@@ -36,30 +36,6 @@ Now you can run:
 This adds the spec directory and some skeleton files, including a .rspec
 file.
 
-## Generators
-
-If you type script/rails generate, the only RSpec generator you'll actually see
-is rspec:install. That's because RSpec is registered with Rails as the test
-framework, so whenever you generate application components like models,
-controllers, etc, RSpec specs are generated instead of Test::Unit tests.
-
-Note that the generators are there to help you get started, but they are no
-substitute for writing your own examples, and they are only guaranteed to work
-out of the box for the default scenario (ActiveRecord + Webrat).
-
-## Autotest
-
-The rspec:install generator creates a .rspec file, which tells RSpec to tell
-Autotest that you're using RSpec and Rails. You'll also need to add the ZenTest
-gem to your Gemfile:
-
-    gem "ZenTest"
-
-At this point, if all of the gems in your Gemfile are installed in system gems,
-you can just type autotest. If, however, Bundler is managing any gems for you
-directly (i.e. you've got :git or :path attributes in the Gemfile), you'll need
-to run bundle exec autotest.
-
 ## Webrat and Capybara
 
 You can choose between webrat or capybara for simulating a browser, automating
@@ -80,4 +56,3 @@ 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,56 @@
+# 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 spec: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/core'
+
+    RSpec.configure do |config|
+      ...
+    end
+
+## Controller specs
+
+### `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.

data/features/controller_specs/README.md

@@ -1,25 +1,36 @@
-A controller spec is an RSpec wrapper for a Rails functional test. It allows
-you to simulate a single http request in each example, and then specify
-expected outcomes, such as:
+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).  It allows you to simulate a single
+http request in each example, and then specify expected outcomes, including:
 
 * templates that are rendered by the action
-* instance variables that are assigned in the controller to be shared with
-  the view
+* instance variables that are assigned in the controller to be shared with the
+  view
 * cookies that get 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)
+* 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)
+  * `response.should render_template (wraps assert_template)`
+  * `response.should redirect_to (wraps assert_redirected_to)`
+  * `assigns(:widget).should be_a_new(Widget)`
     
-Conventions:
+## Conventions:
+
+### Controller
+
+* pass the controller being specified to the outermost `describe` method.
+
+      describe AccountController do
+        # ...
+
+### Views
 
-* pass the controller being spec'd to the describe method
-  * this is only necessary for the outermost example group
-* by default, views are not rendered. See "isolation from views" and
-  "render_views" for details
+* 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/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 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:

data/features/controller_specs/render_views.feature

@@ -1,4 +1,4 @@
-Feature: render views
+Feature: render_views
 
   You can tell a controller example group to render views with the render_views
   declaration.
@@ -101,3 +101,32 @@ Feature: render views
       """
     When I run "rspec spec"
     Then the output should contain "4 examples, 0 failures"
+
+  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 "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"
+    

data/features/helper_specs/helper_spec.feature

@@ -1,7 +1,7 @@
 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`. 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:
@@ -50,4 +50,37 @@ Feature: helper spec
       end
       """
     When I run "rspec spec/helpers/application_helper_spec.rb"
-    Then the output should contain "1 example, 0 failures"
+    Then the output should contain "1 example, 0 failures"
+
+  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 output should contain "1 example, 0 failures"

data/features/mocks/mock_model.feature

@@ -1,8 +1,8 @@
 Feature: mock_model
 
-  The mock_model method generates a test double object that acts like an
-  Active Model model. This is different from the stub_model method which
-  generates an instance of a real ActiveModel class.
+  The mock_model method generates a test double that acts like an Active Model
+  model. This is different from the stub_model method which generates an
+  instance of a real ActiveModel class.
 
   The benefit of mock_model over stub_model is that its a true double, so the
   examples are not dependent on the behaviour (or mis-behaviour), or even the

data/features/model_specs/README.md

@@ -0,0 +1,19 @@
+Model specs live in spec/models, e.g. spec/models/account_spec.rb. A model spec
+is a thin wrapper for an ActiveSupport::TestCase, and includes all of the
+behavior and assertions that it provides, in addition to RSpec's own behavior
+and expectations.
+
+## Examples
+
+    require "spec_helper"
+    
+    describe Post do
+      context "with 2 or more comments" do
+        it "orders them in reverse" do
+          post = Post.create
+          comment1 = post.comment("first")
+          comment2 = post.comment("second")
+          post.reload.comments.should eq([comment2, comment1])
+        end
+      end
+    end