Ticket #7802: dom_assertions_docs_updated.diff

actionpack/lib/action_controller/assertions/dom_assertions.rb

@@ -1 +1 @@
-module ActionController
-  module Assertions
+    # A suite of assertions for verifying the DOM structure of the provided markup.
+    # These are used for testing the structure of HTML or XML strings, usually
+    # views or HTML snippets generated by Rails.
-    module DomAssertions
-
+
+
+
+
-      #
-      # ==== Examples
+      #  # Asserts that a link generated by Rails to the Rails website is correct
+      #  assert_dom_equal "<a href=\"http://www.rubyonrails.com\">Rails</a>", link_to("Rails", "http://www.rubyonrails.com")
-      #
- # assert that the referenced method generates the appropriate HTML string
- assert_dom_equal '<a href="http://www.example.com">Apples</a>', link_to("Apples", "http://www.example.com")
+# Asserts that a link to an action is generated properly; gives a custom error message if it's not
+assert_dom_equal "<a href=\"account/login">Login</a>", link_to("Login", :action => 'login'), "Login link broken"
-      #
+      #  # Tests that a text area tag generated properly
+      #  assert_dom_equal "<textarea name=\"body\" id="body"></textarea>", text_area_tag("body")
+      #
+      #  # Asserts that a form tag is properly generated
+      #  assert_dom_equal " <form action=\"/posts\" method=\"post\"><div><input type=\"submit\" name=\"submit\" value=\"Save\" /></div></form>",
+      #     form_tag('/posts') { submit_tag 'Save' }
+      #
+      #  # Asserts that JavaScript files are included properly, even when given different paths
+      #  assert_dom_equal "<script type=\"text/javascript\" src=\"/javascripts/xhr.js\"></script>", javascript_include_tag "xhr"
+      #  assert_dom_equal """<script type="text/javascript" src="/javascripts/corners.js"></script>
+      #  <script type=\"text/javascript" src=\"/shared/common.js\"></script>""", javascript_include_tag("corners.js", "/shared/common")
+      #
+      #  # Tests for proper generation of an auto-discovery link for an action
+      #  assert_dom_equal "<link rel=\"alternate\" type=\"application/rss+xml\" title=\"RSS\" href=\"http://host.com/controller/feed\" />",
+      #      auto_discovery_link_tag(:rss, {:action => "feed"}, {:title => "RSS"})
+      #
+      #  # Asserts that a button to an action is generated correctly
+      #  assert_dom_equal """<form method=\"post\" action=\"/controller/visit/9\" class=\"button-to\">
+      #    <div><input value=\"Go\" type=\"submit\" /></div>
+      #  </form>""", button_to("Go", :action => "visit", :id => 9)
+      #
-      def assert_dom_equal(expected, actual, message = "")
-        clean_backtrace do
-          expected_dom = HTML::Document.new(expected).root
@@ -18 +47 @@
-        end
-      end
-      
-e negated form of +assert_dom_equivalent+
+is is a negated form of #assert_dom_equivalent; that is, it tests that the HTML and/or XML strings are not equal
-      #
-      # ==== Examples
+      #  # Asserts that the image path is picked up properly for an image tag
+      #  assert_dom_not_equal "<img src=\"images/my_assets/my_image.gif\">", image_tag("/my_assets/my_image.gif")
-      #
- # assert that the referenced method does not generate the specified HTML string
- assert_dom_not_equal '<a href="http://www.example.com">Apples</a>', link_to("Oranges", "http://www.example.com"
+# Asserts that a link to an action recognizes the route properly
+assert_dom_not_equal "<a href=\"/home/index\">", link_to(:controller => 'home', :action => 'index'
-      #
+      #  # Makes sure the custom path for a JavaScript link is correctly rendered
+      #  assert_dom_equal "<script type=\"text/javascript\" src=\"/javascripts/shared/nav.js\"></script>", javascript_include_tag "/shared/nav"
+      #  
+      #  # Tests that a custom route is recognized properly
+      #  assert_dom_not_equal "<a href=\"/user/home/1\">", link_to(:controller => 'user', :action => 'home', :id => 1)  
+      #  # => passes
+      #
+      #  assert_dom_equal "<a href=\"/user1\">", link_to(:controller => 'user', :action => 'home', :id => 1)            
+      #  # => passes
-      def assert_dom_not_equal(expected, actual, message = "")
-        clean_backtrace do
-          expected_dom = HTML::Document.new(expected).root