@@ -1,71 +1,73 @@ = rspec_hpricot_matchers -An implementation of have_tag(), as in rspec_on_rails, but sitting atop -Hpricot rather than merely wrapping assert_select(). - +A matcher similar to RSpec's +#have_tag+ sitting atop Hpricot rather than +wrapping +#assert_select+. == Usage -As its first argument, have_tag() accepts any CSS or XPath selectors +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. - body.should have_tag('form[@action*=session]') - body.should have_tag('ul > li + li') + 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: - body.should have_tag('h1', 'Welcome') - body.should have_tag('p', /a very important blurb/i) + 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: - body.should have_tag('abbr', :count => 1) # exactly one - body.should have_tag('dt', :minimum => 4) # at least 4 - body.should have_tag('dd', :maximum => 4) # at most 4 - body.should have_tag('a.outgoing', /rspec/i, :count => 2) + 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: - body.should have_tag('tr', :count => 3..5) - body.should have_tag('tr', :minimum => 3, + response.should match_element('tr', :count => 3..5) + response.should match_element('tr', :minimum => 3, :maximum => 5) -The usage of with_tag(), however, is no longer supported. Instead, a -block passed to have_tag() will have each matched element successively -yielded to it. If none of the blocks return without raising an -ExpectationNotMetError, the outer have_tag() is treated as having failed: +A block can be passed to #match_element to search for elements within the +matched element: - body.should have_tag('thead') do |thead| - thead.should have_tag('th', :count => 5) + 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: - body.should have_tag('dl dd.sha1') do |dd| + 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: - body.should have_tag('li[class=?]', dom_class) - body.should have_tag('tr.person#?', /^person-\d+$/) + 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 have_tag() further differs from the assert_select-based -implementation in that the nested have_tag() calls must *all* pass +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. README 9b0f079e4e8ac22a6cc68a27798e990f522fc627 Brandon Keepers brandon@collectiveidea.com http://github.com/collectiveidea/rspec_hpricot_matchers/commit/e0f5cbc59d57f5ac8a4a0323824c17f42fd9be31 e0f5cbc59d57f5ac8a4a0323824c17f42fd9be31 2008-12-04T14:57:59-08:00 2008-12-04T14:57:59-08:00 updated the README to account for renamed matcher 1200ba5b5950b566369c54750adffffb0d56c637 Brandon Keepers brandon@collectiveidea.com