yannp-capybara 0.3.9

data/lib/capybara/dsl.rb

@@ -0,0 +1,98 @@
+require 'capybara'
+
+module Capybara
+  class << self
+    attr_writer :default_driver, :current_driver, :javascript_driver
+
+    attr_accessor :app
+
+    ##
+    #
+    # @return [Symbol]    The name of the driver to use by default
+    #
+    def default_driver
+      @default_driver || :rack_test
+    end
+
+    ##
+    #
+    # @return [Symbol]    The name of the driver currently in use
+    #
+    def current_driver
+      @current_driver || default_driver
+    end
+    alias_method :mode, :current_driver
+
+    ##
+    #
+    # @return [Symbol]    The name of the driver used when JavaScript is needed
+    #
+    def javascript_driver
+      @javascript_driver || :selenium
+    end
+
+    ##
+    #
+    # Use the default driver as the current driver
+    #
+    def use_default_driver
+      @current_driver = nil
+    end
+
+    ##
+    #
+    # The current Capybara::Session base on what is set as Capybara.app and Capybara.current_driver
+    #
+    # @return [Capybara::Session]     The currently used session
+    #
+    def current_session
+      session_pool["#{current_driver}#{app.object_id}"] ||= Capybara::Session.new(current_driver, app)
+    end
+
+    ##
+    #
+    # Reset sessions, cleaning out the pool of sessions. This will remove any session information such
+    # as cookies.
+    #
+    def reset_sessions!
+      session_pool.each { |mode, session| session.cleanup! }
+      @session_pool = nil
+    end
+
+  private
+
+    def session_pool
+      @session_pool ||= {}
+    end
+  end
+
+  extend(self)
+
+  ##
+  #
+  # Shortcut to accessing the current session. This is useful when Capybara is included in a
+  # class or module.
+  #
+  #     class MyClass
+  #       include Capybara
+  #
+  #       def has_header?
+  #         page.has_css?('h1')
+  #       end
+  #     end
+  #
+  # @return [Capybara::Session] The current session object
+  #
+  def page
+    Capybara.current_session
+  end
+
+  Session::DSL_METHODS.each do |method|
+    class_eval <<-RUBY, __FILE__, __LINE__+1
+      def #{method}(*args, &block)
+        page.#{method}(*args, &block)
+      end
+    RUBY
+  end
+
+end

data/lib/capybara/node/actions.rb

@@ -0,0 +1,156 @@
+module Capybara
+  class Node
+    module Actions
+
+      ##
+      #
+      # Finds a button or link by id, text or value and clicks it. Also looks at image
+      # alt text inside the link.
+      #
+      # @param [String] locator      Text, id or value of link or button
+      #
+      def click_link_or_button(locator)
+        msg = "no link or button '#{locator}' found"
+        find(:xpath, XPath.link(locator).button(locator), :message => msg).click
+      end
+
+      ##
+      #
+      # Finds a link by id or text and clicks it. Also looks at image
+      # alt text inside the link.
+      #
+      # @param [String] locator      Text, id or text of link
+      #
+      def click_link(locator)
+        msg = "no link with title, id or text '#{locator}' found"
+        find(:xpath, XPath.link(locator), :message => msg).click
+      end
+
+      ##
+      #
+      # Finds a button by id, text or value and clicks it.
+      #
+      # @param [String] locator      Text, id or value of button
+      #
+      def click_button(locator)
+        msg = "no button with value or id or text '#{locator}' found"
+        find(:xpath, XPath.button(locator), :message => msg).click
+      end
+
+      ##
+      #
+      # Locate a text field or text area and fill it in with the given text
+      # The field can be found via its name, id or label text.
+      #
+      #     page.fill_in 'Name', :with => 'Bob'
+      #
+      # @param [String] locator           Which field to fill in
+      # @param [Hash{:with => String}]    The value to fill in
+      #
+      def fill_in(locator, options={})
+        msg = "cannot fill in, no text field, text area or password field with id, name, or label '#{locator}' found"
+        raise "Must pass a hash containing 'with'" if not options.is_a?(Hash) or not options.has_key?(:with)
+        find(:xpath, XPath.fillable_field(locator), :message => msg).set(options[:with])
+      end
+
+      ##
+      #
+      # Find a radio button and mark it as checked. The radio button can be found
+      # via name, id or label text.
+      #
+      #     page.choose('Male')
+      #
+      # @param [String] locator           Which radio button to choose
+      #
+      def choose(locator)
+        msg = "cannot choose field, no radio button with id, name, or label '#{locator}' found"
+        find(:xpath, XPath.radio_button(locator), :message => msg).set(true)
+      end
+
+      ##
+      #
+      # Find a check box and mark it as checked. The check box can be found
+      # via name, id or label text.
+      #
+      #     page.check('German')
+      #
+      # @param [String] locator           Which check box to check
+      #
+      def check(locator)
+        msg = "cannot check field, no checkbox with id, name, or label '#{locator}' found"
+        find(:xpath, XPath.checkbox(locator), :message => msg).set(true)
+      end
+
+      ##
+      #
+      # Find a check box and mark uncheck it. The check box can be found
+      # via name, id or label text.
+      #
+      #     page.uncheck('German')
+      #
+      # @param [String] locator           Which check box to uncheck
+      #
+      def uncheck(locator)
+        msg = "cannot uncheck field, no checkbox with id, name, or label '#{locator}' found"
+        find(:xpath, XPath.checkbox(locator), :message => msg).set(false)
+      end
+
+      ##
+      #
+      # Find a select box on the page and select a particular option from it. If the select
+      # box is a multiple select, +select+ can be called multiple times to select more than
+      # one option. The select box can be found via its name, id or label text.
+      #
+      #     page.uncheck('German')
+      #
+      # @param [String] locator           Which check box to uncheck
+      #
+      def select(value, options={})
+        msg = "cannot select option, no select box with id, name, or label '#{options[:from]}' found"
+        find(:xpath, XPath.select(options[:from]), :message => msg).select_option(value)
+      end
+
+      ##
+      #
+      # Find a select box on the page and select a particular option from it. If the select
+      # box is a multiple select, +select+ can be called multiple times to select more than
+      # one option. The select box can be found via its name, id or label text.
+      #
+      #     page.uncheck('German')
+      #
+      # @param [String] locator           Which check box to uncheck
+      #
+      def unselect(value, options={})
+        msg = "cannot unselect option, no select box with id, name, or label '#{options[:from]}' found"
+        find(:xpath, XPath.select(options[:from]), :message => msg).unselect_option(value)
+      end
+
+      ##
+      #
+      # Find a file field on the page and attach a file given its path. The file field can
+      # be found via its name, id or label text.
+      #
+      #     page.attach_file(locator, '/path/to/file.png')
+      #
+      # @param [String] locator       Which field to attach the file to
+      # @param [String] path          The path of the file that will be attached
+      #
+      def attach_file(locator, path)
+        msg = "cannot attach file, no file field with id, name, or label '#{locator}' found"
+        find(:xpath, XPath.file_field(locator), :message => msg).set(path)
+      end
+
+      ##
+      #
+      # Drag one element to another
+      #
+      # @deprecated    Use Capybara::Element#drag_to instead.
+      #
+      def drag(source_locator, target_locator)
+        source = find(:xpath, source_locator, :message => "drag source '#{source_locator}' not found on page")
+        target = find(:xpath, target_locator, :message => "drag target '#{target_locator}' not found on page")
+        source.drag_to(target)
+      end
+    end
+  end
+end

data/lib/capybara/node/finders.rb

@@ -0,0 +1,155 @@
+module Capybara
+  class Node
+    module Finders
+
+      ##
+      #
+      # Find an Element based on the given arguments. +find+ will raise an error if the element
+      # is not found. The error message can be customized through the +:message+ option.
+      #
+      # If the driver is capable of executing JavaScript, +find+ will wait for a set amount of time
+      # and continuously retry finding the element until either the element is found or the time
+      # expires. The length of time +find+ will wait is controlled through Capybara.default_wait_time
+      # and defaults to 2 seconds.
+      #
+      # +find+ takes the same options as +all+.
+      #
+      #     page.find('#foo').find('.bar')
+      #     page.find(:xpath, '//div[contains("bar")]')
+      #     page.find('li', :text => 'Quox').click_link('Delete')
+      #
+      # @param (see Capybara::Node::Finders#all)
+      # @return [Capybara::Element]           The found element
+      # @raise  [Capybara::ElementNotFound]   If the element can't be found before time expires
+      #
+      def find(*args)
+        node = wait_conditionally_until { all(*args).first }
+      ensure
+        options = if args.last.is_a?(Hash) then args.last else {} end
+        raise Capybara::ElementNotFound, options[:message] || "Unable to find '#{args[1] || args[0]}'" unless node
+        return node
+      end
+
+      ##
+      #
+      # @deprecated {#find} now behaves like locate used to. Use {#find} instead.
+      #
+      def locate(*args)
+        warn "DEPRECATED: Please use #find instead of #locate"
+        find(*args)
+      end
+
+      ##
+      #
+      # Find a form field on the page. The field can be found by its name, id or label text.
+      #
+      # @param [String] locator       Which field to find
+      # @return [Capybara::Element]   The found element
+      #
+      def find_field(locator)
+        find(:xpath, XPath.field(locator))
+      end
+      alias_method :field_labeled, :find_field
+
+      ##
+      #
+      # Find a link on the page. The link can be found by its id or text.
+      #
+      # @param [String] locator       Which link to find
+      # @return [Capybara::Element]   The found element
+      #
+      def find_link(locator)
+        find(:xpath, XPath.link(locator))
+      end
+
+      ##
+      #
+      # Find a button on the page. The link can be found by its id, name or value.
+      #
+      # @param [String] locator       Which button to find
+      # @return [Capybara::Element]   The found element
+      #
+      def find_button(locator)
+        find(:xpath, XPath.button(locator))
+      end
+
+      ##
+      #
+      # Find a element on the page, given its id.
+      #
+      # @param [String] locator       Which element to find
+      # @return [Capybara::Element]   The found element
+      #
+      def find_by_id(id)
+        find(:css, "##{id}")
+      end
+
+      ##
+      #
+      # Find all elements on the page matching the given selector
+      # and options.
+      #
+      # Both XPath and CSS expressions are supported, but Capybara
+      # does not try to automatically distinguish between them. The
+      # following statements are equivalent:
+      #
+      #     page.all(:css, 'a#person_123')
+      #     page.all(:xpath, '//a[@id="person_123"]')
+      #
+      #
+      # If the type of selector is left out, Capybara uses
+      # Capybara.default_selector. It's set to :css by default.
+      #
+      #     page.all("a#person_123")
+      #
+      #     Capybara.default_selector = :xpath
+      #     page.all('//a[@id="person_123"]')
+      #
+      # The set of found elements can further be restricted by specifying
+      # options. It's possible to select elements by their text or visibility:
+      #
+      #     page.all('a', :text => 'Home')
+      #     page.all('#menu li', :visible => true)
+      #
+      # @param [:css, :xpath, String] kind_or_locator     Either the kind of selector or the selector itself
+      # @param [String] locator                           The selector
+      # @param [Hash{Symbol => Object}] options           Additional options
+      # @option options [String] text                     Only find elements which contain this text
+      # @option options [Boolean] visible                 Only find elements that are visible on the page
+      # @return [Capybara::Element]                       The found elements
+      #
+      def all(*args)
+        options = if args.last.is_a?(Hash) then args.pop else {} end
+
+        results = XPath.wrap(normalize_locator(*args)).paths.map do |path|
+          base.find(path)
+        end.flatten
+
+        if text = options[:text]
+          text = Regexp.escape(text) unless text.kind_of?(Regexp)
+
+          results = results.select { |node| node.text.match(text) }
+        end
+
+        if options[:visible] or Capybara.ignore_hidden_elements
+          results = results.select { |node| node.visible? }
+        end
+
+        results.map { |n| Capybara::Element.new(session, n) }
+      end
+
+    protected
+
+      def normalize_locator(kind, locator=nil)
+        kind, locator = Capybara.default_selector, kind if locator.nil?
+        locator = XPath.from_css(locator) if kind == :css
+        locator
+      end
+
+      def wait_conditionally_until
+        if driver.wait? then session.wait_until { yield } else yield end
+      end
+
+    end
+  end
+end

data/lib/capybara/node/matchers.rb

@@ -0,0 +1,97 @@
+module Capybara
+  class Node
+    module Matchers
+      def has_xpath?(path, options={})
+        wait_conditionally_until do
+          results = all(:xpath, path, options)
+
+          if options[:count]
+            results.size == options[:count]
+          else
+            results.size > 0
+          end
+        end
+      rescue Capybara::TimeoutError
+        return false
+      end
+
+      def has_no_xpath?(path, options={})
+        wait_conditionally_until do
+          results = all(:xpath, path, options)
+
+          if options[:count]
+            results.size != options[:count]
+          else
+            results.empty?
+          end
+        end
+      rescue Capybara::TimeoutError
+        return false
+      end
+
+      def has_css?(path, options={})
+        has_xpath?(XPath.from_css(path), options)
+      end
+
+      def has_no_css?(path, options={})
+        has_no_xpath?(XPath.from_css(path), options)
+      end
+
+      def has_content?(content)
+        has_xpath?(XPath.content(content))
+      end
+
+      def has_no_content?(content)
+        has_no_xpath?(XPath.content(content))
+      end
+
+      def has_link?(locator)
+        has_xpath?(XPath.link(locator))
+      end
+
+      def has_no_link?(locator)
+        has_no_xpath?(XPath.link(locator))
+      end
+
+      def has_button?(locator)
+        has_xpath?(XPath.button(locator))
+      end
+
+      def has_no_button?(locator)
+        has_no_xpath?(XPath.button(locator))
+      end
+
+      def has_field?(locator, options={})
+        has_xpath?(XPath.field(locator, options))
+      end
+
+      def has_no_field?(locator, options={})
+        has_no_xpath?(XPath.field(locator, options))
+      end
+
+      def has_checked_field?(locator)
+        has_xpath?(XPath.field(locator, :checked => true))
+      end
+
+      def has_unchecked_field?(locator)
+        has_xpath?(XPath.field(locator, :unchecked => true))
+      end
+
+      def has_select?(locator, options={})
+        has_xpath?(XPath.select(locator, options))
+      end
+
+      def has_no_select?(locator, options={})
+        has_no_xpath?(XPath.select(locator, options))
+      end
+
+      def has_table?(locator, options={})
+        has_xpath?(XPath.table(locator, options))
+      end
+
+      def has_no_table?(locator, options={})
+        has_no_xpath?(XPath.table(locator, options))
+      end
+    end
+  end
+end

data/lib/capybara/node.rb

@@ -0,0 +1,209 @@
+require 'capybara/node/finders'
+require 'capybara/node/actions'
+require 'capybara/node/matchers'
+
+module Capybara
+
+  ##
+  #
+  # A Capybara::Node represents either an element on a page through the subclass
+  # Capybara::Element or a document through Capybara::Document.
+  #
+  # Both types of Node share the same methods, used for interacting with the
+  # elements on the page. These methods are divided into three categories,
+  # finders, actions and matchers. These are found in the modules
+  # Capybara::Node::Finders, Capybara::Node::Actions and Capybara::Node::Matchers
+  # respectively.
+  #
+  # A Capybara::Session exposes all methods from Capybara::Document directly:
+  #
+  #     session = Capybara::Session.new(:rack_test, my_app)
+  #     session.visit('/')
+  #     session.fill_in('Foo', :with => 'Bar')    # from Capybara::Node::Actions
+  #     bar = session.find('#bar')              # from Capybara::Node::Finders
+  #     bar.select('Baz', :from => 'Quox')        # from Capybara::Node::Actions
+  #     session.has_css?('#foobar')               # from Capybara::Node::Matchers
+  #
+  class Node
+    attr_reader :session, :base
+
+    include Capybara::Node::Finders
+    include Capybara::Node::Actions
+    include Capybara::Node::Matchers
+
+    def initialize(session, base)
+      @session = session
+      @base = base
+    end
+
+  protected
+
+    def driver
+      session.driver
+    end
+  end
+
+  ##
+  #
+  # A Capybara::Element represents a single element on the page. It is possible
+  # to interact with the contents of this element the same as with a document:
+  #
+  #     session = Capybara::Session.new(:rack_test, my_app)
+  #
+  #     bar = session.find('#bar')              # from Capybara::Node::Finders
+  #     bar.select('Baz', :from => 'Quox')        # from Capybara::Node::Actions
+  #
+  # Elements also have access to HTML attributes and other properties of the
+  # element:
+  #
+  #      bar.value
+  #      bar.text
+  #      bar[:title]
+  #
+  # @see Capybara::Node
+  #
+  class Element < Node
+
+    ##
+    #
+    # @return [Object]    The native element from the driver, this allows access to driver specific methods
+    #
+    def native
+      base.native
+    end
+
+    ##
+    #
+    # @return [String]    The text of the element
+    #
+    def text
+      base.text
+    end
+
+    ##
+    #
+    # Retrieve the given attribute
+    #
+    #     element[:title] # => HTML title attribute
+    #
+    # @param  [Symbol] attribute     The attribute to retrieve
+    # @return [String]               The value of the attribute
+    #
+    def [](attribute)
+      base[attribute]
+    end
+
+    ##
+    #
+    # @return [String]    The value of the form element
+    #
+    def value
+      base.value
+    end
+
+    ##
+    #
+    # Set the value of the form element to the given value.
+    #
+    # @param [String] value    The new value
+    #
+    def set(value)
+      base.set(value)
+    end
+
+    ##
+    #
+    # Select the given option if the element is a select box
+    #
+    # @param [String] option    The option to select
+    #
+    def select_option(option)
+      base.select_option(option)
+    end
+
+    ##
+    #
+    # Unselect the given option if the element is a select box
+    #
+    # @param [String] option    The option to unselect
+    #
+    def unselect_option(option)
+      base.unselect_option(option)
+    end
+
+    ##
+    #
+    # Click the Element
+    #
+    def click
+      base.click
+    end
+
+    ##
+    #
+    # @return [String]      The tag name of the element
+    #
+    def tag_name
+      base.tag_name
+    end
+
+    ##
+    #
+    # Whether or not the element is visible. Not all drivers support CSS, so
+    # the result may be inaccurate.
+    #
+    # @return [Boolean]     Whether the element is visible
+    #
+    def visible?
+      base.visible?
+    end
+
+    ##
+    #
+    # An XPath expression describing where on the page the element can be found
+    #
+    # @return [String]      An XPath expression
+    #
+    def path
+      base.path
+    end
+
+    ##
+    #
+    # Trigger any event on the current element, for example mouseover or focus
+    # events. Does not work in Selenium.
+    #
+    # @param [String] event       The name of the event to trigger
+    #
+    def trigger(event)
+      base.trigger(event)
+    end
+
+    ##
+    #
+    # Drag the element to the given other element.
+    #
+    #     source = page.find('#foo')
+    #     target = page.find('#bar')
+    #     source.drag_to(target)
+    #
+    # @param [Capybara::Element] node     The element to drag to
+    #
+    def drag_to(node)
+      base.drag_to(node.base)
+    end
+
+    def inspect
+      %(#<Capybara::Element tag="#{tag_name}" path="#{path}">)
+    rescue NotSupportedByDriverError
+      %(#<Capybara::Element tag="#{tag_name}">)
+    end
+
+  end
+
+  class Document < Node
+    def inspect
+      %(#<Capybara::Document>)
+    end
+  end
+end