capybara 0.3.9 → 0.4.0.rc

data/lib/capybara/rails.rb

@@ -13,4 +13,5 @@ Capybara.app = Rack::Builder.new do
 end.to_app
 
 Capybara.asset_root = Rails.root.join('public')
+Capybara.save_and_open_page_path = Rails.root.join('tmp/capybara')
 

data/lib/capybara/selector.rb

@@ -0,0 +1,52 @@
+module Capybara
+  class Selector
+    attr_reader :name, :options, :block
+
+    class << self
+      def all
+        @selectors ||= {}
+      end
+
+      def add(name, options={}, &block)
+        all[name.to_sym] = Capybara::Selector.new(name.to_sym, options, &block)
+      end
+
+      def remove(name)
+        all.delete(name.to_sym)
+      end
+
+      def normalize(name_or_locator, locator=nil)
+        xpath = if locator
+          all[name_or_locator.to_sym].call(locator)
+        else
+          selector = all.values.find { |s| s.match?(name_or_locator) }
+          selector ||= all[Capybara.default_selector]
+          selector.call(name_or_locator)
+        end
+        if xpath.respond_to?(:to_xpaths)
+          xpath.to_xpaths
+        else
+          [xpath.to_s].flatten
+        end
+      end
+    end
+
+    def initialize(name, options={}, &block)
+      @name = name
+      @options = options
+      @block = block
+    end
+
+    def call(locator)
+      @block.call(locator)
+    end
+
+    def match?(locator)
+      @options[:for] and @options[:for] === locator
+    end
+  end
+end
+
+Capybara::Selector.add(:xpath) { |xpath| xpath }
+Capybara::Selector.add(:css) { |css| XPath.css(css) }
+Capybara::Selector.add(:id, :for => Symbol) { |id| XPath.descendant[XPath.attr(:id) == id.to_s] }

data/lib/capybara/server.rb

@@ -1,114 +1,95 @@
 require 'uri'
 require 'net/http'
 require 'rack'
+require 'capybara/util/timeout'
 
-class Capybara::Server
-  class Identify
-    def initialize(app)
-      @app = app
-    end
+module Capybara
+  class Server
+    class Identify
+      def initialize(app)
+        @app = app
+      end
 
-    def call(env)
-      if env["PATH_INFO"] == "/__identify__"
-        [200, {}, @app.object_id.to_s]
-      else
-        @app.call(env)
+      def call(env)
+        if env["PATH_INFO"] == "/__identify__"
+          [200, {}, @app.object_id.to_s]
+        else
+          @app.call(env)
+        end
       end
     end
-  end
 
-  attr_reader :app, :port
-
-  def initialize(app)
-    @app = app
-  end
+    class << self
+      def ports
+        @ports ||= {}
+      end
+    end
 
-  def host
-    "localhost" 
-  end
+    attr_reader :app, :port
 
-  def url(path)
-    if path =~ /^http/
-      path
-    else
-      (Capybara.app_host || "http://#{host}:#{port}") + path.to_s
+    def initialize(app)
+      @app = app
     end
-  end
 
-  def responsive?
-    is_running_on_port?(port)
-  end
+    def host
+      "127.0.0.1"
+    end
 
-  def handler
-    begin
-      require 'rack/handler/thin'
-      Rack::Handler::Thin
-    rescue LoadError
-      begin
-        require 'rack/handler/mongrel'
-        Rack::Handler::Mongrel
-      rescue LoadError
-        require 'rack/handler/webrick'
-        Rack::Handler::WEBrick
+    def url(path)
+      if path =~ /^http/
+        path
+      else
+        (Capybara.app_host || "http://#{host}:#{port}") + path.to_s
       end
     end
-  end
 
-  def boot
-    return self unless @app
-    find_available_port
-    Capybara.log "application has already booted" and return self if responsive?
-    Capybara.log "booting Rack applicartion on port #{port}"
+    def responsive?
+      res = Net::HTTP.start(host, @port) { |http| http.get('/__identify__') }
 
-    Thread.new do
-      handler.run(Identify.new(@app), :Port => port, :AccessLog => [])
+      if res.is_a?(Net::HTTPSuccess) or res.is_a?(Net::HTTPRedirection)
+        return res.body == @app.object_id.to_s
+      end
+    rescue Errno::ECONNREFUSED, Errno::EBADF
+      return false
     end
-    Capybara.log "checking if application has booted"
 
-    Capybara::WaitUntil.timeout(10) do
-      if responsive?
-        Capybara.log("application has booted")
-        true
-      else
-        sleep 0.5
-        false
+    def boot
+      if @app
+        @port = Capybara::Server.ports[@app.object_id]
+
+        if not @port or not responsive?
+          @port = Capybara.server_port || find_available_port
+          Capybara::Server.ports[@app.object_id] = @port
+
+          Thread.new do
+            begin
+              require 'rack/handler/thin'
+              Thin::Logging.silent = true
+              Rack::Handler::Thin.run(Identify.new(@app), :Port => @port)
+            rescue LoadError
+              require 'rack/handler/webrick'
+              Rack::Handler::WEBrick.run(Identify.new(@app), :Port => @port, :AccessLog => [], :Logger => WEBrick::Log::new(nil, 0))
+            end
+          end
+
+          Capybara.timeout(10) { if responsive? then true else sleep(0.5) and false end }
+        end
       end
+    rescue Timeout::Error
+      puts "Rack application timed out during boot"
+      exit
+    else
+      self
     end
-    self
-  rescue Timeout::Error
-    Capybara.log "Rack application timed out during boot"
-    exit
-  end
 
-private
+  private
 
-  def find_available_port
-    @port = 9887
-    @port += 1 while is_port_open?(@port) and not is_running_on_port?(@port)
-  end
-
-  def is_running_on_port?(tested_port)
-    res = Net::HTTP.start(host, tested_port) { |http| http.get('/__identify__') }
-
-    if res.is_a?(Net::HTTPSuccess) or res.is_a?(Net::HTTPRedirection)
-      return res.body == @app.object_id.to_s
+    def find_available_port
+      server = TCPServer.new('127.0.0.1', 0)
+      server.addr[1]
+    ensure
+      server.close if server
     end
-  rescue Errno::ECONNREFUSED, Errno::EBADF
-    return false
-  end
 
-  def is_port_open?(tested_port)
-    Timeout::timeout(1) do
-      begin
-        s = TCPSocket.new(host, tested_port)
-        s.close
-        return true
-      rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
-        return false
-      end
-    end
-  rescue Timeout::Error
-    return false
   end
-
 end

data/lib/capybara/session.rb

@@ -1,18 +1,38 @@
-require 'forwardable'
-require 'capybara/wait_until'
+require 'capybara/util/timeout'
 
 module Capybara
-  class Session
-    extend Forwardable
-    include Searchable
 
+  ##
+  #
+  # The Session class represents a single user's interaction with the system. The Session can use
+  # any of the underlying drivers. A session can be initialized manually like this:
+  #
+  #     session = Capybara::Session.new(:culerity, MyRackApp)
+  #
+  # The application given as the second argument is optional. When running Capybara against an external
+  # page, you might want to leave it out:
+  #
+  #     session = Capybara::Session.new(:culerity)
+  #     session.visit('http://www.google.com')
+  #
+  # Session provides a number of methods for controlling the navigation of the page, such as +visit+,
+  # +current_path, and so on. It also delegate a number of methods to a Capybara::Document, representing
+  # the current HTML document. This allows interaction:
+  #
+  #     session.fill_in('q', :with => 'Capybara')
+  #     session.click_button('Search')
+  #     session.should have_content('Capybara')
+  #
+  # When using capybara/dsl, the Session is initialized automatically for you.
+  #
+  class Session
     DSL_METHODS = [
-      :all, :attach_file, :body, :check, :choose, :click, :click_button, :click_link, :current_url, :drag, :evaluate_script,
+      :all, :attach_file, :body, :check, :choose, :click_link_or_button, :click_button, :click_link, :current_url, :drag, :evaluate_script,
       :field_labeled, :fill_in, :find, :find_button, :find_by_id, :find_field, :find_link, :has_content?, :has_css?,
       :has_no_content?, :has_no_css?, :has_no_xpath?, :has_xpath?, :locate, :save_and_open_page, :select, :source, :uncheck,
-      :visit, :wait_until, :within, :within_fieldset, :within_table, :within_frame, :has_link?, :has_no_link?, :has_button?,
-      :has_no_button?,    :has_field?, :has_no_field?, :has_checked_field?, :has_unchecked_field?, :has_no_table?, :has_table?,
-      :unselect, :has_select?, :has_no_select?, :current_path, :scope_to
+      :visit, :wait_until, :within, :within_fieldset, :within_table, :within_frame, :within_window, :has_link?, :has_no_link?, :has_button?,
+      :has_no_button?, :has_field?, :has_no_field?, :has_checked_field?, :has_unchecked_field?, :has_no_table?, :has_table?,
+      :unselect, :has_select?, :has_no_select?, :current_path, :scope_to, :click
     ]
 
     attr_reader :mode, :app
@@ -23,254 +43,248 @@ module Capybara
     end
 
     def driver
-      @driver ||= begin                    
-        string = mode.to_s
-        string.gsub!(%r{(^.)|(_.)}) { |m| m[m.length-1,1].upcase }
-        Capybara::Driver.const_get(string.to_sym).new(app)
-      rescue NameError
-        raise Capybara::DriverNotFoundError, "no driver called #{mode} was found"
+      @driver ||= begin
+        unless Capybara.drivers.has_key?(mode)
+          other_drivers = Capybara.drivers.keys.map { |key| key.inspect }
+          raise Capybara::DriverNotFoundError, "no driver called #{mode.inspect} was found, available drivers: #{other_drivers.join(', ')}"
+        end
+        Capybara.drivers[mode].call(app)
       end
     end
 
-    def_delegator :driver, :cleanup!
-    def_delegator :driver, :current_url
-    def_delegator :driver, :current_path
-    def_delegator :driver, :response_headers
-    def_delegator :driver, :status_code
-    def_delegator :driver, :visit
-    def_delegator :driver, :body
-    def_delegator :driver, :source
-
-    def click(locator)
-      msg = "no link or button '#{locator}' found"
-      locate(:xpath, XPath.link(locator).button(locator), msg).click
-    end
-
-    def click_link(locator)
-      msg = "no link with title, id or text '#{locator}' found"
-      locate(:xpath, XPath.link(locator), msg).click
-    end
-
-    def click_button(locator)
-      msg = "no button with value or id or text '#{locator}' found"
-      locate(:xpath, XPath.button(locator), msg).click
-    end
-
-    def drag(source_locator, target_locator)
-      source = locate(:xpath, source_locator, "drag source '#{source_locator}' not found on page")
-      target = locate(:xpath, target_locator, "drag target '#{target_locator}' not found on page")
-      source.drag_to(target)
-    end
-
-    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)
-      locate(:xpath, XPath.fillable_field(locator), msg).set(options[:with])
-    end
-
-    def choose(locator)
-      msg = "cannot choose field, no radio button with id, name, or label '#{locator}' found"
-      locate(:xpath, XPath.radio_button(locator), msg).set(true)
-    end
-
-    def check(locator)
-      msg = "cannot check field, no checkbox with id, name, or label '#{locator}' found"
-      locate(:xpath, XPath.checkbox(locator), msg).set(true)
-    end
-
-    def uncheck(locator)
-      msg = "cannot uncheck field, no checkbox with id, name, or label '#{locator}' found"
-      locate(:xpath, XPath.checkbox(locator), msg).set(false)
-    end
-
-    def select(value, options={})
-      msg = "cannot select option, no select box with id, name, or label '#{options[:from]}' found"
-      locate(:xpath, XPath.select(options[:from]), msg).select(value)
-    end
-
-    def unselect(value, options={})
-      msg = "cannot unselect option, no select box with id, name, or label '#{options[:from]}' found"
-      locate(:xpath, XPath.select(options[:from]), msg).unselect(value)
-    end
-
-    def attach_file(locator, path)
-      msg = "cannot attach file, no file field with id, name, or label '#{locator}' found"
-      locate(:xpath, XPath.file_field(locator), msg).set(path)
-    end
-
-    def within(kind, scope=nil)
-      kind, scope = Capybara.default_selector, kind unless scope
-      scope = XPath.from_css(scope) if kind == :css
-      locate(:xpath, scope, "scope '#{scope}' not found on page")
+    ##
+    #
+    # Reset the session, removing all cookies.
+    #
+    def reset!
+      driver.reset!
+    end
+    alias_method :cleanup!, :reset!
+
+    ##
+    #
+    # Returns a hash of response headers. Not supported by all drivers (e.g. Selenium)
+    #
+    # @return [Hash{String => String}] A hash of response headers.
+    #
+    def response_headers
+      driver.response_headers
+    end
+
+    ##
+    #
+    # Returns the current HTTP status code as an Integer. Not supported by all drivers (e.g. Selenium)
+    #
+    # @return [Integer] Current HTTP status code
+    #
+    def status_code
+      driver.status_code
+    end
+
+    ##
+    #
+    # @return [String] A snapshot of the HTML of the current document, as it looks right now
+    #
+    def body
+      driver.body
+    end
+
+    ##
+    #
+    # @return [String] HTML source of the document, before being modified by JavaScript.
+    #
+    def source
+      driver.source
+    end
+
+    ##
+    #
+    # @return [String] Path of the current page, without any domain information
+    #
+    def current_path
+      URI.parse(current_url).path
+    end
+
+    ##
+    #
+    # @return [String] Fully qualified URL of the current page
+    #
+    def current_url
+      driver.current_url
+    end
+
+    ##
+    #
+    # Navigate to the given URL. The URL can either be a relative URL or an absolute URL
+    # The behaviour of either depends on the driver.
+    #
+    #     session.visit('/foo')
+    #     session.visit('http://google.com')
+    #
+    # For drivers which can run against an external application, such as culerity and selenium
+    # giving an absolute URL will navigate to that page. This allows testing applications
+    # running on remote servers. For these drivers, setting Capybara.app_host will make the
+    # remote server the default. For example:
+    #
+    #     Capybara.app_host = 'http://google.com'
+    #     session.visit('/') # visits the google homepage
+    #
+    # @param [String] url     The URL to navigate to
+    #
+    def visit(url)
+      driver.visit(url)
+    end
+
+    ##
+    #
+    # Execute the given block for a particular scope on the page. Within will find the first
+    # element matching the given selector and execute the block scoped to that element:
+    #
+    #     within(:xpath, '//div[@id="delivery-address"]') do
+    #       fill_in('Street', :with => '12 Main Street')
+    #     end
+    #
+    # It is possible to omit the first parameter, in that case, the selector is assumed to be
+    # of the type set in Capybara.default_selector.
+    #
+    #     within('div#delivery-address') do
+    #       fill_in('Street', :with => '12 Main Street')
+    #     end
+    #
+    # @param [:css, :xpath, String] kind    The type of selector or the selector if the second argument is blank
+    # @param [String] selector              The selector within which to execute the given block
+    #
+    def within(kind, selector=nil)
+      new_scope = find(kind, selector, :message => "scope '#{selector || kind}' not found on page")
       begin
-        scopes.push(scope)
+        scopes.push(new_scope)
         yield
       ensure
         scopes.pop
       end
     end
 
+    ##
+    #
+    # Execute the given block within the a specific fieldset given the id or legend of that fieldset.
+    #
+    # @param [String] locator    Id or legend of the fieldset
+    #
     def within_fieldset(locator)
-      within :xpath, XPath.fieldset(locator) do
+      within :xpath, XPath::HTML.fieldset(locator) do
         yield
       end
     end
 
+    ##
+    #
+    # Execute the given block within the a specific table given the id or caption of that table.
+    #
+    # @param [String] locator    Id or caption of the table
+    #
     def within_table(locator)
-      within :xpath, XPath.table(locator) do
+      within :xpath, XPath::HTML.table(locator) do
         yield
       end
     end
 
+    ##
+    #
+    # Execute the given block within the given iframe given the id of that iframe. Only works on
+    # some drivers (e.g. Selenium)
+    #
+    # @param [String] locator    Id of the frame
+    #
     def within_frame(frame_id)
       driver.within_frame(frame_id) do
         yield
       end
     end
 
-    def scope_to(*locator)
-      scoped_session = self.clone
-      scoped_session.instance_eval do
-        @scopes = scopes + locator
-      end
-      scoped_session
-    end
-
-    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)
+    ##
+    #
+    # Execute the given block within the given window. Only works on
+    # some drivers (e.g. Selenium)
+    #
+    # @param [String] locator of the window
+    #
+    def within_window(handle, &blk)
+      driver.within_window(handle, &blk)
     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))
+    ##
+    #
+    # Retry executing the block until a truthy result is returned or the timeout time is exceeded
+    #
+    # @param [Integer] timeout   The amount of seconds to retry executing the given block
+    #
+    def wait_until(timeout = Capybara.default_wait_time)
+      Capybara.timeout(timeout,driver) { yield }
     end
 
-    def has_no_select?(locator, options={})
-      has_no_xpath?(XPath.select(locator, options))
+    ##
+    #
+    # Execute the given script, not returning a result. This is useful for scripts that return
+    # complex objects, such as jQuery statements. +execute_script+ should always be used over
+    # +evaluate_script+ whenever possible.
+    #
+    # @param [String] script   A string of JavaScript to execute
+    #
+    def execute_script(script)
+      driver.execute_script(script)
     end
 
-    def has_table?(locator, options={})
-      has_xpath?(XPath.table(locator, options))
+    ##
+    #
+    # Evaluate the given JavaScript and return the result. Be careful when using this with
+    # scripts that return complex objects, such as jQuery statements. +execute_script+ might
+    # be a better alternative.
+    #
+    # @param  [String] script   A string of JavaScript to evaluate
+    # @return [Object]          The result of the evaluated JavaScript (may be driver specific)
+    #
+    def evaluate_script(script)
+      driver.evaluate_script(script)
     end
 
-    def has_no_table?(locator, options={})
-      has_no_xpath?(XPath.table(locator, options))
+    ##
+    #
+    # @deprecated click is deprecated, please use {Capybara::Node::Actions#click_link_or_button} instead
+    #
+    def click(locator)
+      Capybara.deprecate("click", "click_link_or_button")
+      current_node.click_link_or_button(locator)
     end
 
+    ##
+    #
+    # Save a snapshot of the page and open it in a browser for inspection
+    #
     def save_and_open_page
-      require 'capybara/save_and_open_page'
-      Capybara::SaveAndOpenPage.save_and_open_page(body)
+      require 'capybara/util/save_and_open_page'
+      Capybara.save_and_open_page(body)
     end
 
-    #return node identified by locator or raise ElementNotFound(using desc)
-    def locate(kind_or_locator, locator=nil, fail_msg = nil)
-      node = wait_conditionally_until { find(kind_or_locator, locator) }
-    ensure
-      raise Capybara::ElementNotFound, fail_msg || "Unable to locate '#{locator || kind_or_locator}'" unless node
-      return node
+    def document
+      Capybara::Document.new(self, driver)
     end
 
-    def wait_until(timeout = Capybara.default_wait_time)
-      WaitUntil.timeout(timeout,driver) { yield }
+    def method_missing(*args)
+      current_node.send(*args)
     end
 
-    def execute_script(script)
-      driver.execute_script(script)
-    end
-
-    def evaluate_script(script)
-      driver.evaluate_script(script)
+    def respond_to?(method)
+      super || current_node.respond_to?(method)
     end
 
   private
 
-    def wait_conditionally_until
-      if driver.wait? then wait_until { yield } else yield end
-    end
-
-    def all_unfiltered(locator)
-      XPath.wrap(locator).scope(current_scope).paths.map do |path|
-        driver.find(path)
-      end.flatten
-    end
-
-    def current_scope
-      scopes.join('')
+    def current_node
+      scopes.last
     end
 
     def scopes
-      @scopes ||= []
+      @scopes ||= [document]
     end
   end
 end