Document assert_selector and assert_no_selector

lib/capybara/node/base.rb

@@ -68,6 +68,7 @@ module Capybara
       #
       # @param [Integer] seconds          Number of seconds to retry this block
       # @return [Object]                  The result of the given block
+      # @raise [Capybara::FrozenInTime]   If the rerurn value of {Time.now} appears stuck
       #
       def synchronize(seconds=Capybara.default_wait_time)
         start_time = Time.now

lib/capybara/node/matchers.rb

@@ -25,8 +25,7 @@ module Capybara
       # has_selector? can also accept XPath expressions generated by the
       # XPath gem:
       #
-      #     xpath = XPath.generate { |x| x.descendant(:p) }
-      #     page.has_selector?(:xpath, xpath)
+      #     page.has_selector?(:xpath, XPath.descendant(:p))
       #
       # @param (see Capybara::Node::Finders#all)
       # @option options [Integer] :count (nil)    Number of times the expression should occur
@@ -38,6 +37,35 @@ module Capybara
         return false
       end
 
+      ##
+      #
+      # Asserts that a given selector is on the page or current node.
+      #
+      #     page.assert_selector('p#foo')
+      #     page.assert_selector(:xpath, './/p[@id="foo"]')
+      #     page.assert_selector(:foo)
+      #
+      # By default it will check if the expression occurs at least once,
+      # but a different number can be specified.
+      #
+      #     page.assert_selector('p#foo', :count => 4)
+      #
+      # This will check if the expression occurs exactly 4 times.
+      #
+      # It also accepts all options that {Capybara::Node::Finders#all} accepts,
+      # such as :text and :visible.
+      #
+      #     page.assert_selector('li', :text => 'Horse', :visible => true)
+      #
+      # {assert_selector} can also accept XPath expressions generated by the
+      # XPath gem:
+      #
+      #     page.assert_selector(:xpath, XPath.descendant(:p))
+      #
+      # @param (see Capybara::Node::Finders#all)
+      # @option options [Integer] :count (nil)    Number of times the expression should occur
+      # @raise [Capybara::ExpectationNotMet]      If the selector does not exist
+      #
       def assert_selector(*args)
         synchronize do
           result = all(*args)
@@ -60,6 +88,14 @@ module Capybara
         return false
       end
 
+      ##
+      #
+      # Asserts that a given selector is not on the page or current node.
+      # Usage is identical to Capybara::Node::Matchers#assert_selector
+      #
+      # @param (see Capybara::Node::Finders#assert_selector)
+      # @raise [Capybara::ExpectationNotMet]      If the selector exists
+      #
       def assert_no_selector(*args)
         synchronize do
           result = all(*args)