Merge branch 'master' of https://github.com/rails/rails

1 files changed, 35 insertions, 30 deletions

diff --git a/railties/guides/source/testing.textile b/railties/guides/source/testing.textile
index 69695c93c8..4ebdb3edf6 100644
--- a/railties/guides/source/testing.textile
+++ b/railties/guides/source/testing.textile
@@ -182,21 +182,27 @@ class PostTest < ActiveSupport::TestCase
 
 The +PostTest+ class defines a _test case_ because it inherits from +ActiveSupport::TestCase+. +PostTest+ thus has all the methods available from +ActiveSupport::TestCase+. You'll see those methods a little later in this guide.
 
-<ruby>
-def test_truth
-</ruby>
-
 Any method defined within a +Test::Unit+ test case that begins with +test+ (case sensitive) is simply called a test. So, +test_password+, +test_valid_password+ and +testValidPassword+ all are legal test names and are run automatically when the test case is run.
 
-Rails adds a +test+ method that takes a test name and a block. It generates a normal +Test::Unit+ test with method names prefixed with +test_+.
+Rails adds a +test+ method that takes a test name and a block. It generates a normal +Test::Unit+ test with method names prefixed with +test_+. So,
 
 <ruby>
 test "the truth" do
-  # ...
+  assert true
 end
 </ruby>
 
-This makes test names more readable by replacing underscores with regular language.
+acts as if you had written
+
+<ruby>
+def test_the_truth
+  assert true
+end
+</ruby>
+
+only the +test+ macro allows a more readable test name. You can still use regular method definitions though.
+
+NOTE: The method name is generated by replacing spaces with underscores. The result does not need to be a valid Ruby identifier though, the name may contain punctuation characters etc. That's because in Ruby technically any string may be a method name. Odd ones need +define_method+ and +send+ calls, but formally there's no restriction.
 
 <ruby>
 assert true
@@ -223,13 +229,13 @@ $ rake db:test:load
 
 Above +rake db:migrate+ runs any pending migrations on the _development_ environment and updates +db/schema.rb+. +rake db:test:load+ recreates the test database from the current +db/schema.rb+. On subsequent attempts, it is a good idea to first run +db:test:prepare+, as it first checks for pending migrations and warns you appropriately.
 
-NOTE: +db:test:prepare+ will fail with an error if +db/schema.rb+ doesn't exists.
+NOTE: +db:test:prepare+ will fail with an error if +db/schema.rb+ doesn't exist.
 
 h5. Rake Tasks for Preparing your Application for Testing
 
 |_.Tasks                         |_.Description|
 |+rake db:test:clone+            |Recreate the test database from the current environment's database schema|
-|+rake db:test:clone_structure+  |Recreate the test databases from the development structure|
+|+rake db:test:clone_structure+  |Recreate the test database from the development structure|
 |+rake db:test:load+             |Recreate the test database from the current +schema.rb+|
 |+rake db:test:prepare+          |Check for pending migrations and load the test schema|
 |+rake db:test:purge+            |Empty the test database.|
@@ -241,8 +247,7 @@ h4. Running Tests
 Running a test is as simple as invoking the file containing the test cases through Ruby:
 
 <shell>
-$ cd test
-$ ruby unit/post_test.rb
+$ ruby -Itest test/unit/post_test.rb
 
 Loaded suite unit/post_test
 Started
@@ -252,12 +257,12 @@ Finished in 0.023513 seconds.
 1 tests, 1 assertions, 0 failures, 0 errors
 </shell>
 
-This will run all the test methods from the test case.
+This will run all the test methods from the test case. Note that +test_helper.rb+ is in the +test+ directory, hence this directory needs to be added to the load path using the +-I+ switch.
 
 You can also run a particular test method from the test case by using the +-n+ switch with the +test method name+.
 
 <shell>
-$ ruby unit/post_test.rb -n test_truth
+$ ruby -Itest test/unit/post_test.rb -n test_the_truth
 
 Loaded suite unit/post_test
 Started
@@ -316,7 +321,7 @@ Now to get this test to pass we can add a model level validation for the _title_
 
 <ruby>
 class Post < ActiveRecord::Base
-  validates_presence_of :title
+  validates :title, :presence => true
 end
 </ruby>
 
@@ -381,7 +386,7 @@ There are a bunch of different types of assertions you can use. Here's the compl
 |+assert( boolean, [msg] )+                                        |Ensures that the object/expression is true.|
 |+assert_equal( obj1, obj2, [msg] )+                               |Ensures that +obj1 == obj2+ is true.|
 |+assert_not_equal( obj1, obj2, [msg] )+                           |Ensures that +obj1 == obj2+ is false.|
-|+assert_same( obj1, obj2, [msg] )+			                       |Ensures that +obj1.equal?(obj2)+ is true.|
+|+assert_same( obj1, obj2, [msg] )+                                |Ensures that +obj1.equal?(obj2)+ is true.|
 |+assert_not_same( obj1, obj2, [msg] )+                            |Ensures that +obj1.equal?(obj2)+ is false.|
 |+assert_nil( obj, [msg] )+                                        |Ensures that +obj.nil?+ is true.|
 |+assert_not_nil( obj, [msg] )+                                    |Ensures that +obj.nil?+ is false.|
@@ -389,7 +394,7 @@ There are a bunch of different types of assertions you can use. Here's the compl
 |+assert_no_match( regexp, string, [msg] )+                        |Ensures that a string doesn't matches the regular expression.|
 |+assert_in_delta( expecting, actual, delta, [msg] )+              |Ensures that the numbers +expecting+ and +actual+ are within +delta+ of each other.|
 |+assert_throws( symbol, [msg] ) { block }+                        |Ensures that the given block throws the symbol.|
-|+assert_raise( exception1, exception2, ... ) { block }+          |Ensures that the given block raises one of the given exceptions.|
+|+assert_raise( exception1, exception2, ... ) { block }+           |Ensures that the given block raises one of the given exceptions.|
 |+assert_nothing_raised( exception1, exception2, ... ) { block }+  |Ensures that the given block doesn't raise one of the given exceptions.|
 |+assert_instance_of( class, obj, [msg] )+                         |Ensures that +obj+ is of the +class+ type.|
 |+assert_kind_of( class, obj, [msg] )+                             |Ensures that +obj+ is or descends from +class+.|
@@ -495,6 +500,8 @@ If you're familiar with the HTTP protocol, you'll know that +get+ is a type of r
 
 All of request types are methods that you can use, however, you'll probably end up using the first two more often than the others.
 
+NOTE: Functional tests do not verify whether the specified request type should be accepted by the action. Request types in this context exist to make your tests more descriptive.
+
 h4. The Four Hashes of the Apocalypse
 
 After a request has been made by using one of the 5 methods (+get+, +post+, etc.) and processed, you will have 4 Hash objects ready for use:
@@ -507,12 +514,12 @@ After a request has been made by using one of the 5 methods (+get+, +post+, etc.
 As is the case with normal Hash objects, you can access the values by referencing the keys by string. You can also reference them by symbol name, except for +assigns+. For example:
 
 <ruby>
-  flash["gordon"]               flash[:gordon]
-  session["shmession"]          session[:shmession]
-  cookies["are_good_for_u"]     cookies[:are_good_for_u]
+flash["gordon"]               flash[:gordon]
+session["shmession"]          session[:shmession]
+cookies["are_good_for_u"]     cookies[:are_good_for_u]
 
 # Because you can't use assigns[:something] for historical reasons:
-  assigns["something"]          assigns(:something)
+assigns["something"]          assigns(:something)
 </ruby>
 
 h4. Instance Variables Available
@@ -577,7 +584,7 @@ assert_select "ol" do
 end
 </ruby>
 
-The +assert_select+ assertion is quite powerful. For more advanced usage, refer to its "documentation":http://api.rubyonrails.org/classes/ActionController/Assertions/SelectorAssertions.html.
+The +assert_select+ assertion is quite powerful. For more advanced usage, refer to its "documentation":http://api.rubyonrails.org/classes/ActionDispatch/Assertions/SelectorAssertions.html.
 
 h5. Additional View-Based Assertions
 
@@ -614,7 +621,7 @@ Here's what a freshly-generated integration test looks like:
 <ruby>
 require 'test_helper'
 
-class UserFlowsTest < ActionController::IntegrationTest
+class UserFlowsTest < ActionDispatch::IntegrationTest
   fixtures :all
 
   # Replace this with your real tests.
@@ -624,7 +631,7 @@ class UserFlowsTest < ActionController::IntegrationTest
 end
 </ruby>
 
-Integration tests inherit from +ActionController::IntegrationTest+. This makes available some additional helpers to use in your integration tests. Also you need to explicitly include the fixtures to be made available to the test.
+Integration tests inherit from +ActionDispatch::IntegrationTest+. This makes available some additional helpers to use in your integration tests. Also you need to explicitly include the fixtures to be made available to the test.
 
 h4. Helpers Available for Integration Tests
 
@@ -650,7 +657,7 @@ A simple integration test that exercises multiple controllers:
 <ruby>
 require 'test_helper'
 
-class UserFlowsTest < ActionController::IntegrationTest
+class UserFlowsTest < ActionDispatch::IntegrationTest
   fixtures :users
 
   test "login and browse site" do
@@ -678,7 +685,7 @@ Here's an example of multiple sessions and custom DSL in an integration test
 <ruby>
 require 'test_helper'
 
-class UserFlowsTest < ActionController::IntegrationTest
+class UserFlowsTest < ActionDispatch::IntegrationTest
   fixtures :users
 
   test "login and browse site" do
@@ -735,7 +742,7 @@ You don't need to set up and run your tests by hand on a test-by-test basis. Rai
 |+rake test:plugins+             |Run all the plugin tests from +vendor/plugins/*/**/test+ (or specify with +PLUGIN=_name_+)|
 |+rake test:profile+             |Profile the performance tests|
 |+rake test:recent+              |Tests recent changes|
-|+rake test:uncommitted+         |Runs all the tests which are uncommitted. Only supports Subversion|
+|+rake test:uncommitted+         |Runs all the tests which are uncommitted. Supports Subversion and Git|
 |+rake test:units+               |Runs all the unit tests from +test/unit+|
 
 
@@ -934,15 +941,13 @@ h3. Other Testing Approaches
 The built-in +test/unit+ based testing is not the only way to test Rails applications. Rails developers have come up with a wide variety of other approaches and aids for testing, including:
 
 * "NullDB":http://avdi.org/projects/nulldb/, a way to speed up testing by avoiding database use.
-* "Factory Girl":http://github.com/thoughtbot/factory_girl/tree/master, as replacement for fixtures.
-* "Machinist":http://github.com/notahat/machinist/tree/master, another replacement for fixtures.
+* "Factory Girl":https://github.com/thoughtbot/factory_girl/tree/master, as replacement for fixtures.
+* "Machinist":https://github.com/notahat/machinist/tree/master, another replacement for fixtures.
 * "Shoulda":http://www.thoughtbot.com/projects/shoulda, an extension to +test/unit+ with additional helpers, macros, and assertions.
 * "RSpec":http://rspec.info/, a behavior-driven development framework
 
 h3. Changelog
 
-"Lighthouse ticket":http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/8
-
 * April 4, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com
 * November 13, 2008: Revised based on feedback from Pratik Naik by "Akshay Surve":credits.html#asurve (not yet approved for publication)
 * October 14, 2008: Edit and formatting pass by "Mike Gunderloy":credits.html#mgunderloy (not yet approved for publication)