rspec-rails 2.8.0.rc1 → 2.8.0.rc2

data/License.txt

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2006 David Chelimsky, The RSpec Development Team
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -2,34 +2,42 @@
 
 rspec-2 for rails-3 with lightweight extensions to each
 
-NOTE: Use rspec-rails-1.3.x for rails-2.
+Note: Use [rspec-rails-1.3](http://github.com/dchelimsky/rspec-rails) for rails-2.
 
 ## Install
 
-    gem install rspec-rails
+```
+gem install rspec-rails
+```
 
 This installs the following gems:
 
-    rspec
-    rspec-core
-    rspec-expectations
-    rspec-mocks
-    rspec-rails
+```
+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.6"
-    end
+```ruby
+group :test, :development do
+  gem "rspec-rails", "~> 2.6"
+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:
 
-    rails generate rspec:install
+```
+rails generate rspec:install
+```
 
 This adds the spec directory and some skeleton files, including
 the "rake spec" task.
@@ -43,20 +51,7 @@ controllers, etc, RSpec specs are generated instead of Test::Unit tests.
 
 Please 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 an `.rspec` file, which tells 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`.
+work out of the box for the default scenario (`ActiveRecord` & `Webrat`).
 
 ### Webrat and Capybara
 
@@ -64,8 +59,10 @@ 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"
+```ruby
+gem "webrat"
+gem "capybara"
+```
 
 ## Living on edge
 
@@ -73,11 +70,13 @@ Bundler makes it a snap to use the latest code for any gem your app depends on.
 rspec-rails, you'll need to point bundler to the git repositories for `rspec-rails`
 and the other rspec related gems it depends on:
 
-    gem "rspec-rails",        :git => "git://github.com/rspec/rspec-rails.git"
-    gem "rspec",              :git => "git://github.com/rspec/rspec.git"
-    gem "rspec-core",         :git => "git://github.com/rspec/rspec-core.git"
-    gem "rspec-expectations", :git => "git://github.com/rspec/rspec-expectations.git"
-    gem "rspec-mocks",        :git => "git://github.com/rspec/rspec-mocks.git"
+```ruby
+gem "rspec-rails",        :git => "git://github.com/rspec/rspec-rails.git"
+gem "rspec",              :git => "git://github.com/rspec/rspec.git"
+gem "rspec-core",         :git => "git://github.com/rspec/rspec-core.git"
+gem "rspec-expectations", :git => "git://github.com/rspec/rspec-expectations.git"
+gem "rspec-mocks",        :git => "git://github.com/rspec/rspec-mocks.git"
+```
 
 Run `bundle install` and you'll have whatever is in git right now. Any time you
 want to update to a newer head, just run `bundle update`.
@@ -103,14 +102,16 @@ See http://github.com/rspec/rspec-rails/issues
 
 Request specs live in spec/requests.
 
-    describe "widgets resource" do
-      describe "GET index" do
-        it "contains the widgets header" do
-          get "/widgets/index"
-          response.should have_selector("h1", :content => "Widgets")
-        end
-      end
+```ruby
+describe "widgets resource" do
+  describe "GET index" do
+    it "contains the widgets header" do
+      get "/widgets/index"
+      response.should have_selector("h1", :content => "Widgets")
     end
+  end
+end
+```
 
 Request specs mix in behavior from Rails' integration tests. See the
 docs for ActionDispatch::Integration::Runner for more information.
@@ -118,25 +119,91 @@ docs for ActionDispatch::Integration::Runner for more information.
 # Controller Specs
 
 Controller specs live in spec/controllers, and mix in
-ActionController::TestCase::Behavior. See the documentation
-for ActionController::TestCase to see what facilities are
-available from Rails.
+ActionController::TestCase::Behavior, which is the basis for Rails' functional
+tests.
 
-You can use RSpec expectations/matchers or Test::Unit assertions.
+## with fixtures
+
+```ruby
+describe WidgetsController do
+  describe "GET index" do
+    fixtures :widgets
+
+    it "assigns all widgets to @widgets" do
+      get :index
+      assigns(:widgets).should eq(Widget.all)
+    end
+  end
+end
+```
+
+## with a factory
+
+```ruby
+describe WidgetsController do
+  describe "GET index" do
+    it "assigns all widgets to @widgets" do
+      widget = Factory(:widget)
+      get :index
+      assigns(:widgets).should eq([widget])
+    end
+  end
+end
+```
+
+## with stubs
+
+```ruby
+describe WidgetsController do
+  describe "GET index" do
+    it "assigns all widgets to @widgets" do
+      widget = stub_model(Widget)
+      Widget.stub(:all) { [widget] }
+      get :index
+      assigns(:widgets).should eq([widget])
+    end
+  end
+end
+```
+
+## matchers
+
+In addition to the stock matchers from rspec-expectations, controller
+specs add these matchers, which delegate to rails' assertions:
+
+```ruby
+response.should render_template(*args)
+# => delegates to assert_template(*args)
+
+response.should redirect_to(destination)
+# => delegates to assert_redirected_to(destination)
+```
+
+## isolation from views
+
+RSpec's preferred approach to spec'ing controller behaviour is to isolate
+the controller from its collaborators.  By default, therefore, controller
+example groups do not render the views in your app. Due to the way Rails
+searches for view templates, the template still needs to exist, but it
+won't actually be loaded.
+
+NOTE that this is different from rspec-rails-1 with rails-2, which did not
+require the presence of the file at all. Due to changes in rails-3, this
+was no longer feasible in rspec-rails-2.
 
 ## `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.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:
 
-    describe SomeController do
-      render_views
-      ...
+If you prefer a more integrated approach, similar to that of Rails'
+functional tests, you can tell controller groups to render the views in the
+app with the `render_views` declaration:
 
-### * Upgrade note
+```ruby
+describe WidgetsController do
+  render_views
+  # ...
+```
+
+### Upgrade note
 
 `render_views` replaces `integrate_views` from rspec-rails-1.3
 
@@ -145,36 +212,42 @@ group:
 Use `assigns(key)` to express expectations about instance variables that a controller
 assigns to the view in the course of an action:
 
-    get :index
-    assigns(:widgets).should eq(expected_value)
+```ruby
+get :index
+assigns(:widgets).should eq(expected_value)
+```
 
 # View specs
 
 View specs live in spec/views, and mix in ActionView::TestCase::Behavior.
 
-    describe "events/index.html.erb" do
-      it "renders _event partial for each event" do
-        assign(:events, [stub_model(Event), stub_model(Event)])
-        render
-        view.should render_template(:partial => "_event", :count => 2)
-      end
-    end
-
-    describe "events/show.html.erb" do
-      it "displays the event location" do
-        assign(:event, stub_model(Event,
-          :location => "Chicago"
-        )
-        render
-        rendered.should contain("Chicago")
-      end
-    end
+```ruby
+describe "events/index.html.erb" do
+  it "renders _event partial for each event" do
+    assign(:events, [stub_model(Event), stub_model(Event)])
+    render
+    view.should render_template(:partial => "_event", :count => 2)
+  end
+end
+
+describe "events/show.html.erb" do
+  it "displays the event location" do
+    assign(:event, stub_model(Event,
+      :location => "Chicago"
+    ))
+    render
+    rendered.should contain("Chicago")
+  end
+end
+```
 
 View specs infer the controller name and path from the path to the view
 template. e.g. if the template is "events/index.html.erb" then:
 
-    controller.controller_path == "events"
-    controller.request.path_parameters[:controller] == "events"
+```ruby
+controller.controller_path == "events"
+controller.request.path_parameters[:controller] == "events"
+```
 
 This means that most of the time you don't need to set these values. When
 spec'ing a partial that is included across different controllers, you _may_
@@ -183,14 +256,18 @@ need to override these values before rendering the view.
 To provide a layout for the render, you'll need to specify _both_ the template
 and the layout explicitly.  For example:
 
-    render :template => "events/show", :layout => "layouts/application"
+```ruby
+render :template => "events/show", :layout => "layouts/application"
+```
 
 ## `assign(key, val)`
 
 Use this to assign values to instance variables in the view:
 
-    assign(:widget, stub_model(Widget))
-    render
+```ruby
+assign(:widget, stub_model(Widget))
+render
+```
 
 The code above assigns `stub_model(Widget)` to the `@widget` variable in the view, and then
 renders the view.
@@ -200,47 +277,92 @@ instance variables you set will be transparently propagated into your views
 (similar to how instance variables you set in controller actions are made
 available in views). For example:
 
-    @widget = stub_model(Widget)
-    render # @widget is available inside the view
+```ruby
+@widget = stub_model(Widget)
+render # @widget is available inside the view
+```
 
 RSpec doesn't officially support this pattern, which only works as a
 side-effect of the inclusion of `ActionView::TestCase`. Be aware that it may be
 made unavailable in the future.
 
-### * Upgrade note
+### Upgrade note
 
-`assign(key, value)` replaces `assigns[key] = value` from rspec-rails-1.3
+```ruby
+# rspec-rails-1.x
+assigns[key] = value
+
+# rspec-rails-2.x
+assign(key, value)
+```
 
 ## `rendered`
 
 This represents the rendered view.
 
-    render
-    rendered.should =~ /Some text expected to appear on the page/
+```ruby
+render
+rendered.should =~ /Some text expected to appear on the page/
+```
+
+### Upgrade note
+
+```ruby
+# rspec-rails-1.x
+render
+response.should xxx
+
+# rspec-rails-2.x
+render
+rendered.should xxx
+```
 
-### * Upgrade note
+# Model specs
 
-`rendered` replaces `response` from rspec-rails-1.3
+Model specs live in spec/models.
+
+```ruby
+describe Articles do
+  describe ".recent" do
+    it "includes articles published less than one week ago" do
+      article = Article.create!(:published_at => Date.today - 1.week + 1.second)
+      Article.recent.should eq([article])
+    end
+
+    it "excludes articles published at midnight one week ago" do
+      article = Article.create!(:published_at => Date.today - 1.week)
+      Article.recent.should be_empty
+    end
+
+    it "excludes articles published more than one week ago" do
+      article = Article.create!(:published_at => Date.today - 1.week - 1.second)
+      Article.recent.should be_empty
+    end
+  end
+end
+```
 
 # Routing specs
 
 Routing specs live in spec/routing.
 
-    describe "routing to profiles" do
-      it "routes /profile/:username to profile#show for username" do
-        { :get => "/profiles/jsmith" }.should route_to(
-          :controller => "profiles",
-          :action => "show",
-          :username => "jsmith"
-        )
-      end
-
-      it "does not expose a list of profiles" do
-        { :get => "/profiles" }.should_not be_routable
-      end
-    end
+```ruby
+describe "routing to profiles" do
+  it "routes /profile/:username to profile#show for username" do
+    { :get => "/profiles/jsmith" }.should route_to(
+      :controller => "profiles",
+      :action => "show",
+      :username => "jsmith"
+    )
+  end
 
-### * Upgrade note
+  it "does not expose a list of profiles" do
+    { :get => "/profiles" }.should_not be_routable
+  end
+end
+```
+
+### Upgrade note
 
 `route_for` from rspec-rails-1.x is gone. Use `route_to` and `be_routable` instead.
 
@@ -248,16 +370,21 @@ Routing specs live in spec/routing.
 
 Helper specs live in spec/helpers, and mix in ActionView::TestCase::Behavior.
 
-    describe EventsHelper do
-      describe "#link_to_event" do
-        it "displays the title, and formatted date" do
-          event = Event.new("Ruby Kaigi", Date.new(2010, 8, 27))
-          # helper is an instance of ActionView::Base configured with the
-          # EventsHelper and all of Rails' built-in helpers
-          helper.link_to_event.should =~ /Ruby Kaigi, 27 Aug, 2010/
-        end
-      end
+Provides a `helper` object which mixes in the helper module being spec'd, along
+with `ApplicationHelper` (if present).
+
+```ruby
+describe EventsHelper do
+  describe "#link_to_event" do
+    it "displays the title, and formatted date" do
+      event = Event.new("Ruby Kaigi", Date.new(2010, 8, 27))
+      # helper is an instance of ActionView::Base configured with the
+      # EventsHelper and all of Rails' built-in helpers
+      helper.link_to_event.should =~ /Ruby Kaigi, 27 Aug, 2010/
     end
+  end
+end
+```
 
 # Matchers
 
@@ -268,9 +395,10 @@ of them simply delegate to Rails' assertions.
 * Available in all specs.
 * Primarily intended for controller specs
 
-<pre>
+```ruby
 object.should be_a_new(Widget)
-</pre>
+```
+
 
 Passes if the object is a `Widget` and returns true for `new_record?`
 
@@ -280,41 +408,47 @@ Passes if the object is a `Widget` and returns true for `new_record?`
 
 In request and controller specs, apply to the response object:
 
-    response.should render_template("new")
+```ruby
+response.should render_template("new")
+```
 
 In view specs, apply to the view object:
 
-    view.should render_template(:partial => "_form", :locals => { :widget => widget } )
+```ruby
+view.should render_template(:partial => "_form", :locals => { :widget => widget } )
+```
 
 ## `redirect_to`
 * Delegates to assert_redirect
 * Available in request and controller specs.
 
-<pre>
+```ruby
 response.should redirect_to(widgets_path)
-</pre>
+```
 
 ## `route_to`
 
 * Delegates to Rails' assert_routing.
 * Available in routing and controller specs.
 
-<pre>
+```ruby
 { :get => "/widgets" }.should route_to(:controller => "widgets", :action => "index")
-</pre>
+```
 
 ## `be_routable`
 
 Passes if the path is recognized by Rails' routing. This is primarily intended
 to be used with `should_not` to specify routes that should not be routable.
 
-    { :get => "/widgets/1/edit" }.should_not be_routable
+```ruby
+{ :get => "/widgets/1/edit" }.should_not be_routable
+```
 
-## Contribute
+# Contribute
 
 See [http://github.com/rspec/rspec-dev](http://github.com/rspec/rspec-dev)
 
-## Also see
+# Also see
 
 * [http://github.com/rspec/rspec](http://github.com/rspec/rspec)
 * [http://github.com/rspec/rspec-core](http://github.com/rspec/rspec-core)