DOCSEARCHbyAlgolia
Submit Docs

Rails::Dom::Testing

repository·main·Indexed 41 days ago

https://github.com/rails/rails-dom-testing

A utility gem for Rails applications used to compare HTML DOMs and assert the presence or absence of specific DOM elements using CSS selectors. It provides assertions such as assert_dom_equal, assert_dom_not_equal, and assert_dom, with support for configuring HTML4 and HTML5 parser versions via Nokogiri.

Tokens
1.4K
Snippets
8
Records
8
Agent score
2%

What's inside Rails Dom Testing

  1. Install rails-dom-testing

    main

    To use rails-dom-testing in your Rails application, add the gem to your Gemfile and run bundle:

    gem 'rails-dom-testing'

    Alternatively, you can install it manually via the command line:

    gem install rails-dom-testing

    Note: This gem requires Rails 4.2 or above.

    gem 'rails-dom-testing'

  2. Configure the default HTML parser version

    main

    By default, assertions use Nokogiri's HTML4 parser. You can change the default parser version globally or per assertion.

    Global Configuration

    In a standalone environment, set: Rails::Dom::Testing.default_html_version = :html5

    In a Rails application, set the configuration in your application config: Rails.application.config.dom_testing_default_html_version = :html5

    Note: If the HTML5 parser is not available on your platform, setting this will raise a NotImplementedError.

    Per-assertion Override

    You can override the default version for a single call using the html_version: keyword argument:

    assert_dom_equal(expected, actual, html_version: :html5)
    # Example of per-assertion override
assert_dom_not_equal(expected, actual, html_version: :html4)

  3. Assert presence or absence of elements with selector assertions

    main

    The gem provides several methods to assert the existence or absence of elements using CSS selectors.

    • css_select(selector): Selects elements from the document_root_element and returns a Nokogiri::XML::NodeSet.
    • assert_dom(node, selector): Asserts that the specified selector exists within the provided node.
    • assert_not_dom(node, selector): Asserts that the specified selector does not exist within the provided node.
    • assert_dom_encoded(selector): Asserts that elements within CDATA encoded sections can be selected.
    • assert_dom_email(selector): Asserts that elements within an HTML email exist.
    # Implicitly selects from the document_root_element
css_select '.hello' # => Nokogiri::XML::NodeSet

# Select from a supplied node
assert_dom document_root_element.at('.hello'), '.goodbye'
assert_not_dom document_root_element.at('.hello'), '.goodbye'

# Specialized assertions
assert_dom_encoded '#out-of-your-element'
assert_dom_email '#you-got-mail'

  4. Compare HTML DOMs with assert_dom_equal and assert_dom_not_equal

    main

    Use these assertions to compare two HTML strings for equality or inequality.

    • assert_dom_equal(expected, actual): Asserts that the two DOMs are equal.
    • assert_dom_not_equal(expected, actual): Asserts that the two DOMs are not equal.

    You can optionally pass an html_version: keyword argument (e.g., html_version: :html5 or html_version: :html4) to override the default parser version for the comparison.

    assert_dom_equal '<h1>Lingua França</h1>', '<h1>Lingua França</h1>'

assert_dom_not_equal '<h1>Portuguese</h1>', '<h1>Danish</h1>'

# Using a specific HTML version
assert_dom_equal(expected, actual, html_version: :html5)

  5. Configure the default HTML version

    main

    You can set the global default HTML version used by Rails::Dom::Testing for parsing documents and fragments. The supported versions are :html4 and :html5. If :html5 is selected, the platform must have Nokogiri::HTML5 defined.

    Rails::Dom::Testing.default_html_version = :html5

  7. Create an HTML document

    main

    Use Rails::Dom::Testing.html_document(html_version: nil) to create a new Nokogiri document. If html_version is not provided, it defaults to the value set in Rails::Dom::Testing.default_html_version (which is :html4 by default).

    Supported versions: :html4, :html5.

    # Uses default (:html4)
doc = Rails::Dom::Testing.html_document

# Explicitly use HTML5
doc_html5 = Rails::Dom::Testing.html_document(html_version: :html5)

  8. Create an HTML document fragment

    main

    Use Rails::Dom::Testing.html_document_fragment(html_version: nil) to create a new Nokogiri document fragment. If html_version is not provided, it defaults to the value set in Rails::Dom::Testing.default_html_version (which is :html4 by default).

    Supported versions: :html4, :html5.

    # Uses default (:html4)
fragment = Rails::Dom::Testing.html_document_fragment

# Explicitly use HTML5
fragment_html5 = Rails::Dom::Testing.html_document_fragment(html_version: :html5)