From c75cfa0e545024b8011a9b350c911ee590a4d3a0 Mon Sep 17 00:00:00 2001
From: scottwillson <scott@butlerpress.com>
Date: Wed, 28 May 2008 07:38:20 -0700
Subject: [PATCH] Updated README example to ActionController::TestCase from
 Test::Unit::TestCase. Added usage example for ActionController::TestCase.

---
 actionpack/README                             | 18 +++++----------
 actionpack/lib/action_controller/test_case.rb | 23 +++++++++++++++++++
 2 files changed, 29 insertions(+), 12 deletions(-)

diff --git a/actionpack/README b/actionpack/README
index 2746c3cc43..6090089bb9 100644
--- a/actionpack/README
+++ b/actionpack/README
@@ -31,7 +31,7 @@ http://www.rubyonrails.org.
 A short rundown of the major features:
 
 * Actions grouped in controller as methods instead of separate command objects
-  and can therefore share helper methods.
+  and can therefore share helper methods
 
     BlogController < ActionController::Base
       def show
@@ -168,7 +168,7 @@ A short rundown of the major features:
   {Learn more}[link:classes/ActionController/Base.html]
 
 
-* Javascript and Ajax integration.
+* Javascript and Ajax integration
 
     link_to_function "Greeting", "alert('Hello world!')"
     link_to_remote "Delete this post", :update => "posts", 
@@ -177,7 +177,7 @@ A short rundown of the major features:
   {Learn more}[link:classes/ActionView/Helpers/JavaScriptHelper.html]
 
 
-* Pagination for navigating lists of results.
+* Pagination for navigating lists of results
 
     # controller
     def list
@@ -192,15 +192,9 @@ A short rundown of the major features:
   {Learn more}[link:classes/ActionController/Pagination.html]
 
 
-* Easy testing of both controller and template result through TestRequest/Response
-
-    class LoginControllerTest < Test::Unit::TestCase
-      def setup
-        @controller = LoginController.new
-        @request    = ActionController::TestRequest.new
-        @response   = ActionController::TestResponse.new
-      end
+* Easy testing of both controller and rendered template through ActionController::TestCase
 
+    class LoginControllerTest < ActionController::TestCase
       def test_failing_authenticate
         process :authenticate, :user_name => "nop", :password => ""
         assert flash.has_key?(:alert)
@@ -208,7 +202,7 @@ A short rundown of the major features:
       end
     end
 
-  {Learn more}[link:classes/ActionController/TestRequest.html]
+  {Learn more}[link:classes/ActionController/TestCase.html]
 
 
 * Automated benchmarking and integrated logging
diff --git a/actionpack/lib/action_controller/test_case.rb b/actionpack/lib/action_controller/test_case.rb
index 77c6f26eac..f26e65ba34 100644
--- a/actionpack/lib/action_controller/test_case.rb
+++ b/actionpack/lib/action_controller/test_case.rb
@@ -15,6 +15,27 @@ module ActionController
     end
   end
 
+  # Superclass for Action Controller functional tests. Infers the controller under test from the test class name,
+  # and creates @controller, @request, @response instance variables.
+  #
+  #   class WidgetsControllerTest < ActionController::TestCase
+  #     def test_index
+  #       get :index
+  #     end
+  #   end
+  #
+  # * @controller - WidgetController.new
+  # * @request    - ActionController::TestRequest.new
+  # * @response   - ActionController::TestResponse.new
+  #
+  # (Earlier versions of Rails required each functional test to subclass Test::Unit::TestCase and define 
+  # @controller, @request, @response in +setup+.)
+  #
+  # If the controller cannot be inferred from the test class name, you can explicity set it with +tests+.
+  #
+  #   class SpecialEdgeCaseWidgetsControllerTest < ActionController::TestCase
+  #     tests WidgetController
+  #   end
   class TestCase < ActiveSupport::TestCase
     # When the request.remote_addr remains the default for testing, which is 0.0.0.0, the exception is simply raised inline
     # (bystepping the regular exception handling from rescue_action). If the request.remote_addr is anything else, the regular
@@ -41,6 +62,8 @@ module ActionController
     @@controller_class = nil
 
     class << self
+      # Sets the controller class name. Useful if the name can't be inferred from test class. 
+      # Expects +controller_class+ as a constant. Example: <tt>tests WidgetController</tt>.
       def tests(controller_class)
         self.controller_class = controller_class
       end