0
@@ -15,23 +15,61 @@ module ActionController
0
     end
0
   end
0
 
0
-  # Superclass for Action Controller functional tests. Infers the controller under test from the test class name,
0
-  # and creates @controller, @request, @response instance variables.
0
+  # Superclass for ActionController functional tests. Functional tests allow you to
0
+  # test a single controller action per test method. This should not be confused with
0
+  # integration tests (see ActionController::IntegrationTest), which are more like
0
+  # "stories" that can involve multiple controllers and mutliple actions (i.e. multiple
0
+  # different HTTP requests).
0
   #
0
-  #   class WidgetsControllerTest < ActionController::TestCase
0
-  #     def test_index
0
-  #       get :index
0
+  # == Basic example
0
+  #
0
+  # Functional tests are written as follows:
0
+  # 1. First, one uses the +get+, +post+, +put+, +delete+ or +head+ method to simulate
0
+  #    an HTTP request. 
0
+  # 2. Then, one asserts whether the current state is as expected. "State" can be anything:
0
+  #    the controller's HTTP response, the database contents, etc.
0
+  #
0
+  # For example:
0
+  #
0
+  #   class BooksControllerTest < ActionController::TestCase
0
+  #     def test_create
0
+  #       # Simulate a POST response with the given HTTP parameters.
0
+  #       post(:create, :book => { :title => "Love Hina" })
0
+  #       
0
+  #       # Assert that the controller tried to redirect us to
0
+  #       # the created book's URI.
0
+  #       assert_response :found
0
+  #       
0
+  #       # Assert that the controller really put the book in the database.
0
+  #       assert_not_nil Book.find_by_title("Love Hina")
0
   #     end
0
   #   end
0
   #
0
-  # * @controller - WidgetController.new
0
-  # * @request    - ActionController::TestRequest.new
0
-  # * @response   - ActionController::TestResponse.new
0
+  # == Special instance variables
0
+  #
0
+  # ActionController::TestCase will also automatically provide the following instance
0
+  # variables for use in the tests:
0
+  #
0
+  # <b>@controller</b>::
0
+  #      The controller instance that will be tested.
0
+  # <b>@request</b>::
0
+  #      An ActionController::TestRequest, representing the current HTTP
0
+  #      request. You can modify this object before sending the HTTP request. For example,
0
+  #      you might want to set some session properties before sending a GET request.
0
+  # <b>@response</b>::
0
+  #      An ActionController::TestResponse object, representing the response
0
+  #      of the last HTTP response. In the above example, <tt>@response</tt> becomes valid
0
+  #      after calling +post+. If the various assert methods are not sufficient, then you
0
+  #      may use this object to inspect the HTTP response in detail.
0
+  #
0
+  # (Earlier versions of Rails required each functional test to subclass
0
+  # Test::Unit::TestCase and define @controller, @request, @response in +setup+.)
0
   #
0
-  # (Earlier versions of Rails required each functional test to subclass Test::Unit::TestCase and define 
0
-  # @controller, @request, @response in +setup+.)
0
+  # == Controller is automatically inferred
0
   #
0
-  # If the controller cannot be inferred from the test class name, you can explicity set it with +tests+.
0
+  # ActionController::TestCase will automatically infer the controller under test
0
+  # from the test class name. If the controller cannot be inferred from the test
0
+  # class name, you can explicity set it with +tests+.
0
   #
0
   #   class SpecialEdgeCaseWidgetsControllerTest < ActionController::TestCase
0
   #     tests WidgetController
0
@@ -103,4 +141,4 @@ module ActionController
0
       @request.remote_addr = '208.77.188.166' # example.com
0
     end
0
  end
0
-end
0
\ No newline at end of file
0
+end

0
@@ -361,6 +361,7 @@ module ActionController #:nodoc:
0
   module TestProcess
0
     def self.included(base)
0
       # execute the request simulating a specific HTTP method and set/volley the response
0
+      # TODO: this should be un-DRY'ed for the sake of API documentation.
0
       %w( get post put delete head ).each do |method|
0
         base.class_eval <<-EOV, __FILE__, __LINE__
0
           def #{method}(action, parameters = nil, session = nil, flash = nil)