Module: ActionController::Assertions::SelectorAssertions
- Defined in:
- lib/action_controller/assertions/selector_assertions.rb
Overview
Adds the assert_select
method for use in Rails functional test cases, which can be used to make assertions on the response HTML of a controller action. You can also call assert_select
within another assert_select
to make assertions on elements selected by the enclosing assertion.
Use css_select
to select elements without making an assertions, either from the response HTML or elements selected by the enclosing assertion.
In addition to HTML responses, you can make the following assertions:
-
assert_select_email
- Assertions on the HTML body of an e-mail.
Also see HTML::Selector to learn how to use selectors.
Instance Method Summary collapse
-
#assert_select(*args, &block) ⇒ Object
:call-seq: assert_select(selector, equality?, message?) assert_select(element, selector, equality?, message?).
-
#assert_select_email(&block) ⇒ Object
:call-seq: assert_select_email { }.
-
#assert_select_encoded(element = nil, &block) ⇒ Object
:call-seq: assert_select_encoded(element?) { |elements| … }.
-
#count_description(min, max) ⇒ Object
:nodoc:.
-
#css_select(*args) ⇒ Object
:call-seq: css_select(selector) => array css_select(element, selector) => array.
Instance Method Details
#assert_select(*args, &block) ⇒ Object
:call-seq:
assert_select(selector, equality?, )
assert_select(element, selector, equality?, )
An assertion that selects elements and makes one or more equality tests.
If the first argument is an element, selects all matching elements starting from (and including) that element and all its children in depth-first order.
If no element if specified, calling assert_select
will select from the response HTML. Calling #assert_select inside an assert_select
block will run the assertion for each element selected by the enclosing assertion.
Example
assert_select "ol>li" do |elements|
elements.each do |element|
assert_select element, "li"
end
end
Or for short:
assert_select "ol>li" do
assert_select "li"
end
The selector may be a CSS selector expression (String), an expression with substitution values, or an HTML::Selector object.
Equality Tests
The equality test may be one of the following:
-
true
- Assertion is true if at least one element selected. -
false
- Assertion is true if no element selected. -
String/Regexp
- Assertion is true if the text value of at least one element matches the string or regular expression. -
Integer
- Assertion is true if exactly that number of elements are selected. -
Range
- Assertion is true if the number of selected elements fit the range.
If no equality test specified, the assertion is true if at least one element selected.
To perform more than one equality tests, use a hash with the following keys:
-
:text
- Narrow the selection to elements that have this text value (string or regexp). -
:html
- Narrow the selection to elements that have this HTML content (string or regexp). -
:count
- Assertion is true if the number of selected elements is equal to this value. -
:minimum
- Assertion is true if the number of selected elements is at least this value. -
:maximum
- Assertion is true if the number of selected elements is at most this value.
If the method is called with a block, once all equality tests are evaluated the block is called with an array of all matched elements.
Examples
# At least one form element
assert_select "form"
# Form element includes four input fields
assert_select "form input", 4
# Page title is "Welcome"
assert_select "title", "Welcome"
# Page title is "Welcome" and there is only one title element
assert_select "title", {:count=>1, :text=>"Welcome"},
"Wrong title or more than one title element"
# Page contains no forms
assert_select "form", false, "This page must contain no forms"
# Test the content and style
assert_select "body div.header ul.menu"
# Use substitution values
assert_select "ol>li#?", /item-\d+/
# All input fields in the form have a name
assert_select "form input" do
assert_select "[name=?]", /.+/ # Not empty
end
189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 |
# File 'lib/action_controller/assertions/selector_assertions.rb', line 189 def assert_select(*args, &block) # Start with optional element followed by mandatory selector. arg = args.shift if arg.is_a?(HTML::Node) # First argument is a node (tag or text, but also HTML root), # so we know what we're selecting from. root = arg arg = args.shift elsif arg == nil # This usually happens when passing a node/element that # happens to be nil. raise ArgumentError, "First argument is either selector or element to select, but nil found. Perhaps you called assert_select with an element that does not exist?" elsif @selected root = HTML::Node.new(nil) root.children.concat @selected else # Otherwise just operate on the response document. root = response_from_page end # First or second argument is the selector: string and we pass # all remaining arguments. Array and we pass the argument. Also # accepts selector itself. case arg when String selector = HTML::Selector.new(arg, args) when Array selector = HTML::Selector.new(*arg) when HTML::Selector selector = arg else raise ArgumentError, "Expecting a selector as the first argument" end # Next argument is used for equality tests. equals = {} case arg = args.shift when Hash equals = arg when String, Regexp equals[:text] = arg when Integer equals[:count] = arg when Range equals[:minimum] = arg.begin equals[:maximum] = arg.end when FalseClass equals[:count] = 0 when NilClass, TrueClass equals[:minimum] = 1 else raise ArgumentError, "I don't understand what you're trying to match" end # By default we're looking for at least one match. if equals[:count] equals[:minimum] = equals[:maximum] = equals[:count] else equals[:minimum] = 1 unless equals[:minimum] end # Last argument is the message we use if the assertion fails. = args.shift #- message = "No match made with selector #{selector.inspect}" unless message if args.shift raise ArgumentError, "Not expecting that last argument, you either have too many arguments, or they're the wrong type" end matches = selector.select(root) # If text/html, narrow down to those elements that match it. content_mismatch = nil if match_with = equals[:text] matches.delete_if do |match| text = "" text.force_encoding(match_with.encoding) if text.respond_to?(:force_encoding) stack = match.children.reverse while node = stack.pop if node.tag? stack.concat node.children.reverse else content = node.content content.force_encoding(match_with.encoding) if content.respond_to?(:force_encoding) text << content end end text.strip! unless NO_STRIP.include?(match.name) unless match_with.is_a?(Regexp) ? (text =~ match_with) : (text == match_with.to_s) content_mismatch ||= (, "<?> expected but was\n<?>.", match_with, text) true end end elsif match_with = equals[:html] matches.delete_if do |match| html = match.children.map(&:to_s).join html.strip! unless NO_STRIP.include?(match.name) unless match_with.is_a?(Regexp) ? (html =~ match_with) : (html == match_with.to_s) content_mismatch ||= (, "<?> expected but was\n<?>.", match_with, html) true end end end # Expecting foo found bar element only if found zero, not if # found one but expecting two. ||= content_mismatch if matches.empty? # Test minimum/maximum occurrence. min, max = equals[:minimum], equals[:maximum] = || %(Expected #{count_description(min, max)} matching "#{selector.to_s}", found #{matches.size}.) assert matches.size >= min, if min assert matches.size <= max, if max # If a block is given call that block. Set @selected to allow # nested assert_select, which can be nested several levels deep. if block_given? && !matches.empty? begin in_scope, @selected = @selected, matches yield matches ensure @selected = in_scope end end # Returns all matches elements. matches end |
#assert_select_email(&block) ⇒ Object
:call-seq:
assert_select_email { }
Extracts the body of an email and runs nested assertions on it.
You must enable deliveries for this assertion to work, use:
ActionMailer::Base.perform_deliveries = true
Examples
assert_select_email do
assert_select "h1", "Email alert"
end
assert_select_email do
items = assert_select "ol>li"
items.each do
# Work with items here...
end
end
416 417 418 419 420 421 422 423 424 425 426 427 428 |
# File 'lib/action_controller/assertions/selector_assertions.rb', line 416 def assert_select_email(&block) deliveries = ActionMailer::Base.deliveries assert !deliveries.empty?, "No e-mail in delivery list" for delivery in deliveries for part in delivery.parts if part["Content-Type"].to_s =~ /^text\/html\W/ root = HTML::Document.new(part.body).root assert_select root, ":root", &block end end end end |
#assert_select_encoded(element = nil, &block) ⇒ Object
:call-seq:
assert_select_encoded(element?) { |elements| ... }
Extracts the content of an element, treats it as encoded HTML and runs nested assertion on it.
You typically call this method within another assertion to operate on all currently selected elements. You can also pass an element or array of elements.
The content of each element is un-encoded, and wrapped in the root element encoded
. It then calls the block with all un-encoded elements.
Examples
# Selects all bold tags from within the title of an ATOM feed's entries (perhaps to nab a section name prefix)
assert_select_feed :atom, 1.0 do
# Select each entry item and then the title item
assert_select "entry>title" do
# Run assertions on the encoded title elements
assert_select_encoded do
assert_select "b"
end
end
end
# Selects all paragraph tags from within the description of an RSS feed
assert_select_feed :rss, 2.0 do
# Select description element of each feed item.
assert_select "channel>item>description" do
# Run assertions on the encoded elements.
assert_select_encoded do
assert_select "p"
end
end
end
362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 |
# File 'lib/action_controller/assertions/selector_assertions.rb', line 362 def assert_select_encoded(element = nil, &block) case element when Array elements = element when HTML::Node elements = [element] when nil unless elements = @selected raise ArgumentError, "First argument is optional, but must be called from a nested assert_select" end else raise ArgumentError, "Argument is optional, and may be node or array of nodes" end fix_content = lambda do |node| # Gets around a bug in the Rails 1.1 HTML parser. node.content.gsub(/<!\[CDATA\[(.*)(\]\]>)?/m) { CGI.escapeHTML($1) } end selected = elements.map do |element| text = element.children.select{ |c| not c.tag? }.map{ |c| fix_content[c] }.join root = HTML::Document.new(CGI.unescapeHTML("<encoded>#{text}</encoded>")).root css_select(root, "encoded:root", &block)[0] end begin old_selected, @selected = @selected, selected assert_select ":root", &block ensure @selected = old_selected end end |
#count_description(min, max) ⇒ Object
:nodoc:
313 314 315 316 317 318 319 320 321 322 323 |
# File 'lib/action_controller/assertions/selector_assertions.rb', line 313 def count_description(min, max) #:nodoc: pluralize = lambda {|word, quantity| word << (quantity == 1 ? '' : 's')} if min && max && (max != min) "between #{min} and #{max} elements" elsif min && !(min == 1 && max == 1) "at least #{min} #{pluralize['element', min]}" elsif max "at most #{max} #{pluralize['element', max]}" end end |
#css_select(*args) ⇒ Object
:call-seq:
css_select(selector) => array
css_select(element, selector) => array
Select and return all matching elements.
If called with a single argument, uses that argument as a selector to match all elements of the current page. Returns an empty array if no match is found.
If called with two arguments, uses the first argument as the base element and the second argument as the selector. Attempts to match the base element and any of its children. Returns an empty array if no match is found.
The selector may be a CSS selector expression (String), an expression with substitution values (Array) or an HTML::Selector object.
Examples
# Selects all div tags
divs = css_select("div")
# Selects all paragraph tags and does something interesting
pars = css_select("p")
pars.each do |par|
# Do something fun with paragraphs here...
end
# Selects all list items in unordered lists
items = css_select("ul>li")
# Selects all form tags and then all inputs inside the form
forms = css_select("form")
forms.each do |form|
inputs = css_select(form, "input")
...
end
66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 |
# File 'lib/action_controller/assertions/selector_assertions.rb', line 66 def css_select(*args) # See assert_select to understand what's going on here. arg = args.shift if arg.is_a?(HTML::Node) root = arg arg = args.shift elsif arg == nil raise ArgumentError, "First argument is either selector or element to select, but nil found. Perhaps you called assert_select with an element that does not exist?" elsif @selected matches = [] @selected.each do |selected| subset = css_select(selected, HTML::Selector.new(arg.dup, args.dup)) subset.each do |match| matches << match unless matches.any? { |m| m.equal?(match) } end end return matches else root = response_from_page end case arg when String selector = HTML::Selector.new(arg, args) when Array selector = HTML::Selector.new(*arg) when HTML::Selector selector = arg else raise ArgumentError, "Expecting a selector as the first argument" end selector.select(root) end |