= rspec_hpricot_matchers
 
A matcher similar to RSpec's +#have_tag+ sitting atop Hpricot rather than
wrapping +#assert_select+.
 
== Usage
 
Include RspecHpricotMatchers in your +spec_helper+:
 
    Spec::Runner.configure do |config|
      config.include RspecHpricotMatchers
    end
 
As its first argument, match_element() accepts any CSS or XPath selectors
which are supported by Hpricot.
 
    response.should match_element('form[@action*=session]')
    response.should match_element('ul > li + li')
 
Expectations can be placed upon the inner text of the matched element
by providing another argument, which should be either a String or a
Regexp:
 
    response.should match_element('h1', 'Welcome')
    response.should match_element('p', /a very important blurb/i)
 
Expectations can be placed upon the number of matched elements by
passing an options hash:
 
    response.should match_element('abbr', :count => 1)   # exactly one
    response.should match_element('dt',   :minimum => 4) # at least 4
    response.should match_element('dd',   :maximum => 4) # at most 4
    response.should match_element('a.outgoing', /rspec/i, :count => 2)
 
The :count key also accepts a Range, making the following equivalent:
 
    response.should match_element('tr',   :count => 3..5)
    response.should match_element('tr',   :minimum => 3,
                                 :maximum => 5)
 
 
A block can be passed to #match_element to search for elements within the
matched element:
 
    response.should match_element('thead') do |thead|
      thead.should match_element('th', :count => 5)
    end
 
This also allows arbitrary expectations to be applied from within
the block, such as:
 
    response.should match_element('dl dd.sha1') do |dd|
      dd.inner_text.length.should == 40
    end
 
== Notes
 
Currently, this implementation does not support substitution values
as assert_select did (by way of HTML::Selector):
 
    # Not yet supported:
    response.should match_element('li[class=?]', dom_class)
    response.should match_element('tr.person#?', /^person-\d+$/)
 
I personally rarely use these, and Hpricot's advanced selectors make
them mostly useless, as far as I can tell, so I am unlikely to
implement them myself.
 
This match_element() further differs from the assert_select-based
implementation in that the nested match_element() calls must *all* pass
on a single selected element in order to be true. This was a source
of confusion in RSpec ticket #316. There is a spec covering this
case if you need an example.