rspec-html-matchers

RSpec matchers for testing your html (for RSpec 2 use 0.5.x version).

Goals

• designed for testing complex html output. If you plan to perform simple matching, consider using:
  • assert_select
  • matchers provided out of the box in rspec-rails
  • matchers provided by capybara
• developer-friendly output in error messages
• built on top of nokogiri
• has support for capybara, see below
• syntax is similar to have_tag matcher from rspec-rails 1.x, but with own syntactic sugar
• framework agnostic, as input should be String (or capybara's page, see below)

Install

Add to your Gemfile in the :test group:

gem 'rspec-html-matchers'

Include it in your RSpec configuration:

RSpec.configure do |config|
  config.include RSpecHtmlMatchers
end

or just in your spec(s):

describe "my view spec" do
  include RSpecHtmlMatchers

  it "has tags" do
    expect(rendered).to have_tag('div')
  end
end

Cucumber configuration:

World RSpecHtmlMatchers

as this gem requires nokogiri, here are instructions for installing it.

Usage

so perhaps your code produces following output:

<h1>Simple Form</h1>
<form action="/users" method="post">
<p>
  <input type="email" name="user[email]" />
</p>
<p>
  <input type="submit" id="special_submit" />
</p>
</form>

so you test it with the following:

expect(rendered).to have_tag('form', :with => { :action => '/users', :method => 'post' }) do
  with_tag "input", :with => { :name => "user[email]", :type => 'email' }
  with_tag "input#special_submit", :count => 1
  without_tag "h1", :text => 'unneeded tag'
  without_tag "p",  :text => /content/i
end

Example above should be self-descriptive, if not, please refer to the have_tag documentation

Input can be any html string. Let's take a look at these examples:

• matching tags by css:

  # simple examples:
  expect('<p class="qwe rty" id="qwerty">Paragraph</p>').to have_tag('p')
  expect('<p class="qwe rty" id="qwerty">Paragraph</p>').to have_tag(:p)
  expect('<p class="qwe rty" id="qwerty">Paragraph</p>').to have_tag('p#qwerty')
  expect('<p class="qwe rty" id="qwerty">Paragraph</p>').to have_tag('p.qwe.rty')
  # more complicated examples:
  expect('<p class="qwe rty" id="qwerty"><strong>Para</strong>graph</p>').to have_tag('p strong')
  expect('<p class="qwe rty" id="qwerty"><strong>Para</strong>graph</p>').to have_tag('p#qwerty strong')
  expect('<p class="qwe rty" id="qwerty"><strong>Para</strong>graph</p>').to have_tag('p.qwe.rty strong')
  # or you can use another syntax for examples above
  expect('<p class="qwe rty" id="qwerty"><strong>Para</strong>graph</p>').to have_tag('p') do
    with_tag('strong')
  end
  expect('<p class="qwe rty" id="qwerty"><strong>Para</strong>graph</p>').to have_tag('p#qwerty') do
    with_tag('strong')
  end
  expect('<p class="qwe rty" id="qwerty"><strong>Para</strong>graph</p>').to have_tag('p.qwe.rty') do
    with_tag('strong')
  end

• special case for classes matching:

  # all of this are equivalent:
  expect('<p class="qwe rty" id="qwerty">Paragraph</p>').to have_tag('p', :with => { :class => 'qwe rty' })
  expect('<p class="qwe rty" id="qwerty">Paragraph</p>').to have_tag('p', :with => { :class => 'rty qwe' })
  expect('<p class="qwe rty" id="qwerty">Paragraph</p>').to have_tag('p', :with => { :class => ['rty', 'qwe'] })
  expect('<p class="qwe rty" id="qwerty">Paragraph</p>').to have_tag('p', :with => { :class => ['qwe', 'rty'] })

  The same works with :without:

  # all of this are equivalent:
  expect('<p class="qwe rty" id="qwerty">Paragraph</p>').to have_tag('p', :without => { :class => 'qwe rty' })
  expect('<p class="qwe rty" id="qwerty">Paragraph</p>').to have_tag('p', :without => { :class => 'rty qwe' })
  expect('<p class="qwe rty" id="qwerty">Paragraph</p>').to have_tag('p', :without => { :class => ['rty', 'qwe'] })
  expect('<p class="qwe rty" id="qwerty">Paragraph</p>').to have_tag('p', :without => { :class => ['qwe', 'rty'] })

• content matching:

  expect('<p> Some content&nbsphere</p>').to have_tag('p', :text => ' Some content here')
  # or
  expect('<p> Some content&nbsphere</p>').to have_tag('p') do
    with_text ' Some content here'
  end
  
  expect('<p> Some content&nbsphere</p>').to have_tag('p', :text => /Some content here/)
  # or
  expect('<p> Some content&nbsphere</p>').to have_tag('p') do
    with_text /Some content here/
  end
  
  # mymock.text == 'Some content here'
  expect('<p> Some content&nbsphere</p>').to have_tag('p', :text => mymock.text)
  # or
  expect('<p> Some content&nbsphere</p>').to have_tag('p') do
    with_text mymock.text
  end
  
  # matching text content as it's seen by user:
  rendered = <<HTML
  <p>
     content with ignored spaces around
  </p>
  HTML
  expect(rendered).to have_tag('p', :seen => 'content with ignored spaces around')

• usage with capybara and cucumber:

  expect(page).to have_tag( ... )

where page is an instance of Capybara::Session

• also included shorthand matchers for form inputs:

  • have_form
  • with_checkbox
  • with_email_field
  • with_file_field
  • with_hidden_field
  • with_option
  • with_password_field
  • with_radio_button
  • with_button
  • with_select
  • with_submit
  • with_text_area
  • with_text_field
  • with_url_field
  • with_number_field
  • with_range_field
  • with_date_field

and of course you can use the without_ matchers, for more info take a look at documentation

rspec 1 partial backwards compatibility:

you can match:

expect(response).to have_tag('div', 'expected content')
expect(response).to have_tag('div', /regexp matching expected content/)

RSpec 1 have_tag documentation

Matching Tag Attributes

You can also match the content of attributes by using selectors. For example, to ensure an img tag has an alt attribute, you can match:

expect(index).to have_tag("img[alt!='']")

More info

You can find more on documentation

Also, please read CHANGELOG and issues, might be helpful.

Contribution

1. Fork the repository
2. Add tests for your feature
3. Write the code
4. Add documentation for your contribution
5. Send a pull request

Contributors

• Kelly Felkins
• Ryan Wilcox
• Simon Schoeters
• Felix Tjandrawibawa
• Szymon Przybył
• Manuel Meurer
• Andreas Riemer