words

lib/rspec/rails/example/controller_example_group.rb

@@ -2,6 +2,76 @@
 require 'webrat'
 
 module RSpec::Rails
+  # Extends ActionController::TestCase::Behavior to work with RSpec.
+  #
+  # == Examples
+  #
+  # == 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
+  #
+  # === 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 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
+  #
+  # == 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 views. This means that a view template need
+  # not even exist in order to run a controller spec, and you can still specify
+  # which template the controller should render.
+  #
+  # == View rendering
+  #
+  # If you prefer a more integrated approach, similar to that of
+  # Rails' functional tests, you can tell controller groups to
+  # render views with the +render_views+ declaration:
+  #
+  #   describe WidgetsController do
+  #     render_views
+  #     ...
+  #     
   module ControllerExampleGroup
     extend ActiveSupport::Concern
 

lib/rspec/rails/example/helper_example_group.rb

@@ -2,6 +2,30 @@
 require 'rspec/rails/view_assigns'
 
 module RSpec::Rails
+  # Extends ActionView::TestCase::Behavior
+  #
+  # == Examples
+  #
+  #   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
 
@@ -18,8 +42,8 @@ def determine_default_helper_class(ignore)
     end
 
     module InstanceMethods
-      # Returns an instance of ActionView::Base instrumented with this helper and
-      # any of the built-in rails helpers.
+      # Returns an instance of ActionView::Base with the helper being specified
+      # mixed in, along with any of the built-in rails helpers.
       def helper
         _view
       end

lib/rspec/rails/example/view_example_group.rb

@@ -2,6 +2,23 @@
 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
 

lib/rspec/rails/view_rendering.rb

@@ -8,6 +8,7 @@ def metadata_for_rspec_rails
           metadata[:rspec_rails] ||= {}
         end
 
+        # See RSpec::Rails::ControllerExampleGroup
         def render_views
           metadata_for_rspec_rails[:render_views] = true
         end

spec/rspec/rails/example/helper_example_group_spec.rb

@@ -1,7 +1,9 @@
 require "spec_helper"
 
 module RSpec::Rails
-  describe HelperExampleGroup do
+  describe HelperExampleGroup::InstanceMethods do
+    module ::FoosHelper; end
+
     it "is included in specs in ./spec/views" do
       stub_metadata(
         :example_group => {:file_path => "./spec/helpers/whatever_spec.rb:15"}
@@ -10,13 +12,30 @@ module RSpec::Rails
       group.included_modules.should include(HelperExampleGroup)
     end
 
-    module ::FoosHelper; end
-
     it "provides a controller_path based on the helper module's name" do
-      helper_spec = Object.new
-      helper_spec.extend HelperExampleGroup::InstanceMethods
+      helper_spec = Object.new.extend HelperExampleGroup::InstanceMethods
       helper_spec.stub_chain(:running_example, :example_group, :describes).and_return(FoosHelper)
       helper_spec.__send__(:_controller_path).should == "foos"
     end
+
+    describe "#helper" do
+      it "returns the instance of AV::Base provided by AV::TC::Behavior" do
+        helper_spec = Object.new.extend HelperExampleGroup::InstanceMethods
+        av_tc_b_view = double('_view')
+        helper_spec.stub(:_view) { av_tc_b_view }
+        helper_spec.helper.should eq(av_tc_b_view)
+      end
+    end
+  end
+
+  describe HelperExampleGroup::ClassMethods do
+    describe "determine_default_helper_class" do
+      it "returns the helper module passed to describe" do
+        helper_spec = Object.new.extend HelperExampleGroup::ClassMethods
+        helper_spec.stub(:describes) { FoosHelper }
+        helper_spec.determine_default_helper_class("ignore this").
+          should eq(FoosHelper)
+      end
+    end
   end
 end