vendor/rails/actionpack/lib/action_controller/assertions/tag_assertions.rb

   1 require 'rexml/document'
   2 require 'html/document'
   3
   4 module ActionController
   5   module Assertions
   6     module TagAssertions
   7       # Asserts that there is a tag/node/element in the body of the response
   8       # that meets all of the given conditions. The +conditions+ parameter must
   9       # be a hash of any of the following keys (all are optional):
  10       #
  11       # * <tt>:tag</tt>: the node type must match the corresponding value
  12       # * <tt>:attributes</tt>: a hash. The node's attributes must match the
  13       #   corresponding values in the hash.
  14       # * <tt>:parent</tt>: a hash. The node's parent must match the
  15       #   corresponding hash.
  16       # * <tt>:child</tt>: a hash. At least one of the node's immediate children
  17       #   must meet the criteria described by the hash.
  18       # * <tt>:ancestor</tt>: a hash. At least one of the node's ancestors must
  19       #   meet the criteria described by the hash.
  20       # * <tt>:descendant</tt>: a hash. At least one of the node's descendants
  21       #   must meet the criteria described by the hash.
  22       # * <tt>:sibling</tt>: a hash. At least one of the node's siblings must
  23       #   meet the criteria described by the hash.
  24       # * <tt>:after</tt>: a hash. The node must be after any sibling meeting
  25       #   the criteria described by the hash, and at least one sibling must match.
  26       # * <tt>:before</tt>: a hash. The node must be before any sibling meeting
  27       #   the criteria described by the hash, and at least one sibling must match.
  28       # * <tt>:children</tt>: a hash, for counting children of a node. Accepts
  29       #   the keys:
  30       #   * <tt>:count</tt>: either a number or a range which must equal (or
  31       #     include) the number of children that match.
  32       #   * <tt>:less_than</tt>: the number of matching children must be less
  33       #     than this number.
  34       #   * <tt>:greater_than</tt>: the number of matching children must be
  35       #     greater than this number.
  36       #   * <tt>:only</tt>: another hash consisting of the keys to use
  37       #     to match on the children, and only matching children will be
  38       #     counted.
  39       # * <tt>:content</tt>: the textual content of the node must match the
  40       #   given value. This will not match HTML tags in the body of a
  41       #   tag--only text.
  42       #
  43       # Conditions are matched using the following algorithm:
  44       #
  45       # * if the condition is a string, it must be a substring of the value.
  46       # * if the condition is a regexp, it must match the value.
  47       # * if the condition is a number, the value must match number.to_s.
  48       # * if the condition is +true+, the value must not be +nil+.
  49       # * if the condition is +false+ or +nil+, the value must be +nil+.
  50       #
  51       # Usage:
  52       #
  53       #   # assert that there is a "span" tag
  54       #   assert_tag :tag => "span"
  55       #
  56       #   # assert that there is a "span" tag with id="x"
  57       #   assert_tag :tag => "span", :attributes => { :id => "x" }
  58       #
  59       #   # assert that there is a "span" tag using the short-hand
  60       #   assert_tag :span
  61       #
  62       #   # assert that there is a "span" tag with id="x" using the short-hand
  63       #   assert_tag :span, :attributes => { :id => "x" }
  64       #
  65       #   # assert that there is a "span" inside of a "div"
  66       #   assert_tag :tag => "span", :parent => { :tag => "div" }
  67       #
  68       #   # assert that there is a "span" somewhere inside a table
  69       #   assert_tag :tag => "span", :ancestor => { :tag => "table" }
  70       #
  71       #   # assert that there is a "span" with at least one "em" child
  72       #   assert_tag :tag => "span", :child => { :tag => "em" }
  73       #
  74       #   # assert that there is a "span" containing a (possibly nested)
  75       #   # "strong" tag.
  76       #   assert_tag :tag => "span", :descendant => { :tag => "strong" }
  77       #
  78       #   # assert that there is a "span" containing between 2 and 4 "em" tags
  79       #   # as immediate children
  80       #   assert_tag :tag => "span",
  81       #              :children => { :count => 2..4, :only => { :tag => "em" } }
  82       #
  83       #   # get funky: assert that there is a "div", with an "ul" ancestor
  84       #   # and an "li" parent (with "class" = "enum"), and containing a
  85       #   # "span" descendant that contains text matching /hello world/
  86       #   assert_tag :tag => "div",
  87       #              :ancestor => { :tag => "ul" },
  88       #              :parent => { :tag => "li",
  89       #                           :attributes => { :class => "enum" } },
  90       #              :descendant => { :tag => "span",
  91       #                               :child => /hello world/ }
  92       #
  93       # <b>Please note</b>: #assert_tag and #assert_no_tag only work
  94       # with well-formed XHTML. They recognize a few tags as implicitly self-closing
  95       # (like br and hr and such) but will not work correctly with tags
  96       # that allow optional closing tags (p, li, td). <em>You must explicitly
  97       # close all of your tags to use these assertions.</em>
  98       def assert_tag(*opts)
  99         clean_backtrace do
 100           opts = opts.size > 1 ? opts.last.merge({ :tag => opts.first.to_s }) : opts.first
 101           tag = find_tag(opts)
 102           assert tag, "expected tag, but no tag found matching #{opts.inspect} in:\n#{@response.body.inspect}"
 103         end
 104       end
 105
 106       # Identical to #assert_tag, but asserts that a matching tag does _not_
 107       # exist. (See #assert_tag for a full discussion of the syntax.)
 108       def assert_no_tag(*opts)
 109         clean_backtrace do
 110           opts = opts.size > 1 ? opts.last.merge({ :tag => opts.first.to_s }) : opts.first
 111           tag = find_tag(opts)
 112           assert !tag, "expected no tag, but found tag matching #{opts.inspect} in:\n#{@response.body.inspect}"
 113         end
 114       end
 115     end
 116   end
 117 end