testing guide: revises explanation of the test macro

1 files changed, 15 insertions, 9 deletions

diff --git a/railties/guides/source/testing.textile b/railties/guides/source/testing.textile
index c9109a0ddf..d7088dc04c 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_the_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 underscores with spaces. 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
@@ -380,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.|
@@ -388,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+.|