doc: update documentation to include HTML parser selection

Author: flavorjones

README.md

@@ -33,6 +33,30 @@ assert_dom_email '#you-got-mail'
 
 The documentation in [selector_assertions.rb](https://github.com/rails/rails-dom-testing/blob/master/lib/rails/dom/testing/assertions/selector_assertions.rb) goes into a lot more detail of how selector assertions can be used.
 
+### HTML versions
+
+By default, assertions will use Nokogiri's HTML4 parser.
+
+If `Rails::Dom::Testing.default_html_version` is set to `:html5`, then the assertions will use
+Nokogiri's HTML5 parser. (If the HTML5 parser is not available on your platform, then a
+`NotImplementedError` will be raised.)
+
+When testing in a Rails application, the parser default can also be set by setting
+`Rails.application.config.dom_testing_default_html_version`.
+
+Some assertions support an `html_version:` keyword argument which can override the default for that
+assertion. For example:
+
+``` ruby
+# compare DOMs built with the HTML5 parser
+assert_dom_equal(expected, actual, html_version: :html5)
+
+# compare DOMs built with the HTML4 parser
+assert_dom_not_equal(expected, actual, html_version: :html4)
+```
+
+Please see documentation for individual assertions for more details.
+
 
 ## Installation
 

lib/rails/dom/testing/assertions/dom_assertions.rb

@@ -10,7 +10,30 @@ module DomAssertions
           # \Test two HTML strings for equivalency (e.g., equal even when attributes are in another order)
           #
           #   # 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")
+          #   assert_dom_equal(
+          #     '<a href="http://www.example.com">Apples</a>',
+          #     link_to("Apples", "http://www.example.com"),
+          #   )
+          #
+          # By default, the matcher will not pay attention to whitespace in text nodes (e.g., spaces
+          # and newlines). If you want stricter matching with exact matching for whitespace, pass
+          # <tt>strict: true</tt>:
+          #
+          #   # these assertions will both pass
+          #   assert_dom_equal     "<div>\nfoo\n\</div>", "<div>foo</div>", strict: false
+          #   assert_dom_not_equal "<div>\nfoo\n\</div>", "<div>foo</div>", strict: true
+          #
+          # The DOMs are created using an HTML parser specified by
+          # Rails::Dom::Testing.default_html_version (either :html4 or :html5).
+          #
+          # When testing in a Rails application, the parser default can also be set by setting
+          # +Rails.application.config.dom_testing_default_html_version+.
+          #
+          # If you want to specify the HTML parser just for a particular assertion, pass
+          # <tt>html_version: :html4</tt> or <tt>html_version: :html5</tt> keyword arguments:
+          #
+          #   assert_dom_equal expected, actual, html_version: :html5
+          #
           def assert_dom_equal(expected, actual, message = nil, strict: false, html_version: nil)
             expected_dom, actual_dom = fragment(expected, html_version: html_version), fragment(actual, html_version: html_version)
             message ||= "Expected: #{expected}\nActual: #{actual}"
@@ -20,7 +43,30 @@ def assert_dom_equal(expected, actual, message = nil, strict: false, html_versio
           # The negated form of +assert_dom_equal+.
           #
           #   # 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")
+          #   assert_dom_not_equal(
+          #     '<a href="http://www.example.com">Apples</a>',
+          #     link_to("Oranges", "http://www.example.com"),
+          #   )
+          #
+          # By default, the matcher will not pay attention to whitespace in text nodes (e.g., spaces
+          # and newlines). If you want stricter matching with exact matching for whitespace, pass
+          # <tt>strict: true</tt>:
+          #
+          #   # these assertions will both pass
+          #   assert_dom_equal     "<div>\nfoo\n\</div>", "<div>foo</div>", strict: false
+          #   assert_dom_not_equal "<div>\nfoo\n\</div>", "<div>foo</div>", strict: true
+          #
+          # The DOMs are created using an HTML parser specified by
+          # Rails::Dom::Testing.default_html_version (either :html4 or :html5).
+          #
+          # When testing in a Rails application, the parser default can also be set by setting
+          # +Rails.application.config.dom_testing_default_html_version+.
+          #
+          # If you want to specify the HTML parser just for a particular assertion, pass
+          # <tt>html_version: :html4</tt> or <tt>html_version: :html5</tt> keyword arguments:
+          #
+          #   assert_dom_not_equal expected, actual, html_version: :html5
+          #
           def assert_dom_not_equal(expected, actual, message = nil, strict: false, html_version: nil)
             expected_dom, actual_dom = fragment(expected, html_version: html_version), fragment(actual, html_version: html_version)
             message ||= "Expected: #{expected}\nActual: #{actual}"

lib/rails/dom/testing/assertions/selector_assertions.rb

@@ -213,6 +213,24 @@ def assert_dom(*args, &block)
           #       end
           #     end
           #   end
+          #
+          # The DOM is created using an HTML parser specified by
+          # Rails::Dom::Testing.default_html_version (either :html4 or :html5).
+          #
+          # When testing in a Rails application, the parser default can also be set by setting
+          # +Rails.application.config.dom_testing_default_html_version+.
+          #
+          # If you want to specify the HTML parser just for a particular assertion, pass
+          # <tt>html_version: :html4</tt> or <tt>html_version: :html5</tt> keyword arguments:
+          #
+          #   assert_dom "feed[xmlns='http://www.w3.org/2005/Atom']" do
+          #     assert_dom "entry>title" do
+          #       assert_dom_encoded(html_version: :html5) do
+          #         assert_dom "b"
+          #       end
+          #     end
+          #   end
+          #
           def assert_dom_encoded(element = nil, html_version: nil, &block)
             if !element && !@selected
               raise ArgumentError, "Element is required when called from a nonnested assert_dom"
@@ -240,16 +258,32 @@ def assert_dom_encoded(element = nil, html_version: nil, &block)
           # You must enable deliveries for this assertion to work, use:
           #   ActionMailer::Base.perform_deliveries = true
           #
-          #  assert_dom_email do
-          #    assert_dom "h1", "Email alert"
-          #  end
+          # Example usage:
+          #
+          #   assert_dom_email do
+          #     assert_dom "h1", "Email alert"
+          #   end
+          #
+          #   assert_dom_email do
+          #     items = assert_dom "ol>li"
+          #     items.each do
+          #        # Work with items here...
+          #     end
+          #   end
+          #
+          # The DOM is created using an HTML parser specified by
+          # Rails::Dom::Testing.default_html_version (either :html4 or :html5).
+          #
+          # When testing in a Rails application, the parser default can also be set by setting
+          # +Rails.application.config.dom_testing_default_html_version+.
+          #
+          # If you want to specify the HTML parser just for a particular assertion, pass
+          # <tt>html_version: :html4</tt> or <tt>html_version: :html5</tt> keyword arguments:
+          #
+          #   assert_dom_email(html_version: :html5) do
+          #     assert_dom "h1", "Email alert"
+          #   end
           #
-          #  assert_dom_email do
-          #    items = assert_dom "ol>li"
-          #    items.each do
-          #       # Work with items here...
-          #    end
-          #  end
           def assert_dom_email(html_version: nil, &block)
             deliveries = ActionMailer::Base.deliveries
             assert !deliveries.empty?, "No e-mail in delivery list"