Clarified use of assert_select with blocks in testing guide and rdoc text

2 files changed, 32 insertions, 10 deletions

diff --git a/actionpack/lib/action_controller/assertions/selector_assertions.rb b/actionpack/lib/action_controller/assertions/selector_assertions.rb
index 7f8fe9ab19..0d56ea5ef7 100644
--- a/actionpack/lib/action_controller/assertions/selector_assertions.rb
+++ b/actionpack/lib/action_controller/assertions/selector_assertions.rb
@@ -109,20 +109,27 @@ module ActionController
       # starting from (and including) that element and all its children in
       # depth-first order.
       #
-      # If no element if specified, calling +assert_select+ will select from the
-      # response HTML. Calling #assert_select inside an +assert_select+ block will
-      # run the assertion for each element selected by the enclosing assertion.
+      # If no element if specified, calling +assert_select+ selects from the
+      # response HTML unless +assert_select+ is called from within an +assert_select+ block.
+      #
+      # When called with a block +assert_select+ passes an array of selected elements
+      # to the block. Calling +assert_select+ from the block, with no element specified,
+      # runs the assertion on the complete set of elements selected by the enclosing assertion.
+      # Alternatively the array may be iterated through so that +assert_select+ can be called
+      # separately for each element.
+      #
       #
       # ==== Example
-      #   assert_select "ol>li" do |elements|
+      # If the response contains two ordered lists, each with four list elements then:
+      #   assert_select "ol" do |elements|
       #     elements.each do |element|
-      #       assert_select element, "li"
+      #       assert_select element, "li", 4
       #     end
       #   end
       #
-      # Or for short:
-      #   assert_select "ol>li" do
-      #     assert_select "li"
+      # will pass, as will:
+      #   assert_select "ol" do
+      #     assert_select "li", 8
       #   end
       #
       # The selector may be a CSS selector expression (String), an expression
diff --git a/railties/doc/guides/source/testing_rails_applications.txt b/railties/doc/guides/source/testing_rails_applications.txt
index d29988485a..054260e276 100644
--- a/railties/doc/guides/source/testing_rails_applications.txt
+++ b/railties/doc/guides/source/testing_rails_applications.txt
@@ -592,7 +592,7 @@ For example, you could verify the contents on the title element in your response
 assert_select 'title', "Welcome to Rails Testing Guide"
 --------------------------------------------------
 
-You can also use nested +assert_select+ blocks. In this case the inner +assert_select+ will run the assertion on each element selected by the outer `assert_select` block:
+You can also use nested +assert_select+ blocks. In this case the inner +assert_select+ runs the assertion on the complete collection of elements selected by the outer `assert_select` block:
 
 [source,ruby]
 --------------------------------------------------
@@ -601,7 +601,22 @@ assert_select 'ul.navigation' do
 end
 --------------------------------------------------
 
-The +assert_select+ assertion is quite powerful. For more advanced usage, refer to its link:http://api.rubyonrails.com/classes/ActionController/Assertions/SelectorAssertions.html#M000749[documentation].
+Alternatively the collection of elements selected by the outer +assert_select+ may be iterated through so that +assert_select+ may be called separately for each element. Suppose for example that the response contains two ordered lists, each with four list elements then the following tests will both pass.
+
+[source,ruby]
+--------------------------------------------------
+assert_select "ol" do |elements|
+  elements.each do |element|
+    assert_select element, "li", 4
+  end
+end
+
+assert_select "ol" do
+  assert_select "li", 8
+end
+--------------------------------------------------
+
+The +assert_select+ assertion is quite powerful. For more advanced usage, refer to its link:http://api.rubyonrails.com/classes/ActionController/Assertions/SelectorAssertions.html[documentation].
 
 ==== Additional View-based Assertions ====