Permalink
Browse files

Consolidate rdoc for example groups to README

  • Loading branch information...
1 parent ad5e580 commit 80febb5b99deddb95827a742b01807b180b58988 @dchelimsky dchelimsky committed Dec 8, 2011
View
@@ -45,7 +45,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`).
+work out of the box for the default scenario (`ActiveRecord` & `Webrat`).
### Webrat and Capybara
@@ -128,23 +128,88 @@ 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.
+## Examples
+
+### 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:
+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:
```ruby
-describe SomeController do
+describe WidgetsController do
render_views
# ...
```
@@ -316,6 +381,9 @@ end
Helper specs live in spec/helpers, and mix in ActionView::TestCase::Behavior.
+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
@@ -9,7 +9,7 @@
Dir[Rails.root.join("spec/support/**/*.rb")].each {|f| require f}
RSpec.configure do |config|
- # == Mock Framework
+ # ## Mock Framework
#
# If you prefer to use mocha, flexmock or RR, uncomment the appropriate line:
#
@@ -3,85 +3,6 @@
end
module RSpec::Rails
- # Extends ActionController::TestCase::Behavior to work with RSpec, with
- # some caveats.
- #
- # rspec-rails is designed to support separate specs for models, controllers,
- # views (where appropriate) and helpers. Rails allows this separation, but
- # discourages real isolation by rendering views in controller tests
- #
- # ## Examples
- #
- # ### with fixtures
- #
- # 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
- #
- # 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
- #
- # 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:
- #
- # 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.
- #
- # ## View rendering
- #
- # 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:
- #
- # describe WidgetsController do
- # render_views
- # # ...
module ControllerExampleGroup
extend ActiveSupport::Concern
include RSpec::Rails::RailsExampleGroup
@@ -1,32 +1,6 @@
require 'rspec/rails/view_assigns'
module RSpec::Rails
- # Extends ActionView::TestCase::Behavior
- #
- # Provides a `helper` object which mixes in the helper module being spec'd,
- # along with `ApplicationHelper` (if present).
- #
- # @example
- #
- # describe RoleBasedDisplayHelper do
- # describe "display_for" do
- # context "given the role of the current user" do
- # it "yields to the block" do
- # helper.stub(:current_user) { double(:roles => ['admin']) }
- # text = helper.display_for('admin') { "this text" }
- # text.should eq("this text")
- # end
- # end
- #
- # context "given a different role that that of the current user" do
- # it "renders an empty String" do
- # helper.stub(:current_user) { double(:roles => ['manager']) }
- # text = helper.display_for('admin') { "this text" }
- # text.should eq("")
- # end
- # end
- # end
- # end
module HelperExampleGroup
extend ActiveSupport::Concern
include RSpec::Rails::RailsExampleGroup
@@ -1,5 +1,4 @@
module RSpec::Rails
- # The basis for model specs
module ModelExampleGroup
extend ActiveSupport::Concern
include RSpec::Rails::RailsExampleGroup
@@ -1,16 +1,4 @@
module RSpec::Rails
- # Extends ActionDispatch::Integration::Runner to work with RSpec.
- #
- # ## Matchers
- #
- # In addition to the stock matchers from rspec-expectations, request
- # specs add these matchers, which delegate to rails' assertions:
- #
- # response.should render_template(*args)
- # # => delegates to assert_template(*args)
- #
- # response.should redirect_to(destination)
- # # => delegates to assert_redirected_to(destination)
module RequestExampleGroup
extend ActiveSupport::Concern
include RSpec::Rails::RailsExampleGroup
@@ -1,19 +1,6 @@
require "action_dispatch/testing/assertions/routing"
module RSpec::Rails
- # Routing specs live in spec/routing. If `config/routes.rb` has nothing
- # beyond `map.resources :thing`, then you probably don't need a routing spec,
- # but they can be quite helpful when specifying non-standard routes.
- #
- # @example
- #
- # require 'spec_helper'
- #
- # describe "profiles routes" do
- # it "routes /profiles/jdoe" do
- # get("/profiles/jdoe").should route_to("profiles#show", :username => 'jdoe')
- # end
- # end
module RoutingExampleGroup
extend ActiveSupport::Concern
include RSpec::Rails::RailsExampleGroup
@@ -1,22 +1,6 @@
require 'rspec/rails/view_assigns'
module RSpec::Rails
- # Extends ActionView::TestCase::Behavior
- #
- # == Examples
- #
- # describe "widgets/index.html.erb" do
- # it "renders the @widgets" do
- # widgets = [
- # stub_model(Widget, :name => "Foo"),
- # stub_model(Widget, :name => "Bar")
- # ]
- # assign(:widgets, widgets)
- # render
- # rendered.should contain("Foo")
- # rendered.should contain("Bar")
- # end
- # end
module ViewExampleGroup
extend ActiveSupport::Concern
include RSpec::Rails::RailsExampleGroup
@@ -81,7 +65,7 @@ def view
# help isolate view examples from partials rendered by the view template
# that is the subject of the example.
#
- # == Example
+ # ## Example
#
# stub_template("widgets/_widget.html.erb" => "This content.")
def stub_template(hash)
View
@@ -200,14 +200,12 @@ def connection
# helper), it is especially useful in view examples, which are
# inherently more state-based than interaction-based.
#
- # == Examples
+ # ## Examples
#
- # stub_model(Person)
- # stub_model(Person).as_new_record
- # stub_model(Person, :to_param => 37)
- # stub_model(Person) do |person|
- # person.first_name = "David"
- # end
+ # stub_model(Person)
+ # stub_model(Person).as_new_record
+ # stub_model(Person, :to_param => 37)
+ # stub_model(Person) {|person| person.first_name = "David"}
def stub_model(model_class, stubs={})
model_class.new.tap do |m|
m.extend ActiveModelStubExtensions
@@ -7,7 +7,7 @@ module InstanceMethods
# Assigns a value to an instance variable in the scope of the
# view being rendered.
#
- # == Examples
+ # ## Examples
#
# assign(:widget, stub_model(Widget))
def assign(key, value)

0 comments on commit 80febb5

Please sign in to comment.