capybara 0.3.9 → 0.4.0.rc

data/History.txt

@@ -1,6 +1,48 @@
+# Version 0.4.0.rc
+
+Release date:
+
+### Changed
+
+* within and find/locate now follow the XPath spec in that //foo finds all nodes in the document, instead of
+  only for the context node. See this post for details: http://groups.google.com/group/ruby-capybara/browse_thread/thread/b129067979df21b3
+* within now executes within the first found instance of the selector, not in all of them
+* find now waits for AJAX requests and raises an exception when the element is not found (same as locate used to do)
+* The default selector is now CSS, not XPath
+
+### Deprecated
+
+* Session#click has been renamed click_link_or_button and the old click has been deprecated
+* Node#node has been renamed native
+* Node#locate is deprecated in favor of Node#find, which now behaves identically
+* Session#drag is deprecated, please use Node#drag_to(other_node) instead
+
+### Added
+
+* Pretty much everything is properly documented now
+* It's now possible to call all session methods on nodes, like `find('#foo').fill_in(...)`
+* Custom selectors can be added with Capybara::Selector.add
+* The :id selector is added by default, use it lile `find(:id, 'foo')` or `find(:foo)`
+* Added Node#has_selector? so any kind of selector can be queried.
+* Added Capybara.configure for less wordy configuration
+* Added within_window to switch between different windows (currently Selenium only)
+* Capybara.server_port to provide a fixed port if wanted (defaults to automatic selection)
+
+### Fixed
+
+* CSS selectors with multiple selectors, such as "h1, h2" now work correctly
+* Port is automatically assigned instead of guessing
+* Strip encodings in rack-test, no more warnings!
+* RackTest no longer submits disabled fields
+* Servers no longer output annoying debug information when started
+* TCP port selection is left to Ruby to decide, no more port guessing
+* Select boxes now return option value instead of text if present
+* The default has been changed from localhost to 127.0.0.1, should fix some obscure selenium bugs
+* RackTest now supports complex field names, such as foo[bar][][baz]
+
 # Version 0.3.9
 
-Release data: 2010-07-03
+Release date: 2010-07-03
 
 ### Added
 

data/README.rdoc

@@ -1,16 +1,19 @@
-= capybara
+= Capybara
 
 * http://github.com/jnicklas/capybara
 
 == Description:
 
 Capybara aims to simplify the process of integration testing Rack applications,
-such as Rails, Sinatra or Merb. It is inspired by and aims to replace Webrat as
-a DSL for interacting with a webapplication. It is agnostic about the driver
-running your tests and currently comes bundled with rack-test, Culerity,
-Celerity and Selenium support built in. env.js support is available as the
+such as Rails, Sinatra or Merb. Capybara simulates how a real user would
+interact with a web application. It is agnostic about the driver running your
+tests and currently comes bundled with rack-test, Culerity, Celerity and Selenium
+support built in. env.js support is available as the
 {capybara-envjs gem}[http://github.com/smparkes/capybara-envjs].
 
+Online documentation is availbable
+{at rdoc.info}[http://rdoc.info/projects/jnicklas/capybara].
+
 == Install:
 
 Install as a gem:
@@ -31,18 +34,22 @@ Pull requests are very welcome! Make sure your patches are well tested, Capybara
 a testing tool after all. Please create a topic branch for every separate change
 you make.
 
+Capybara uses bundler in development. To set up a development environment, simply do:
+
+    gem install bundler --pre
+    bundle install
+
 == Using Capybara with Cucumber
 
-Capybara is built to work nicely with Cucumber. The API is very similar to
-Webrat, so if you know Webrat you should feel right at home. Support for
-Capybara is built into cucumber-rails 0.2. In your Rails app, just run:
+Capybara is built to work nicely with Cucumber. Support for Capybara is built into
+cucumber-rails. In your Rails app, just run:
 
-    script/generate cucumber --capybara
+    rails generate cucumber:install --capybara
 
 And everything should be set up and ready to go.
 
 If you want to use Capybara with Cucumber outside Rails (for example with Merb
-or Sinatra), you'll need require capybara and set the Rack app manually:
+or Sinatra), you'll need to require Capybara and set the Rack app manually:
 
     require 'capybara/cucumber'
     Capybara.app = MyRackApp
@@ -50,16 +57,13 @@ or Sinatra), you'll need require capybara and set the Rack app manually:
 Now you can use it in your steps:
 
     When /I sign in/ do
-      within("//form[@id='session']") do
+      within("#session") do
         fill_in 'Login', :with => 'user@example.com'
         fill_in 'Password', :with => 'password'
       end
       click_link 'Sign in'
     end
 
-Please note that while Capybara uses XPath selectors by default, Cucumber explicitly
-changes this to CSS in `env.rb`.  See "XPath and CSS" below.
-
 == Default and current driver
 
 You can set up a default driver for your features. For example if you'd prefer
@@ -103,11 +107,6 @@ At the moment, Capybara supports Webdriver, also called Selenium 2.0, *not*
 Selenium RC. Provided Firefox is installed, everything is set up for you, and
 you should be able to start using Selenium right away.
 
-If desired, you can change Selenium browser to :chrome or :ie:
-
-   require "selenium-webdriver"
-   Selenium::WebDriver.for :chrome
-
 == Celerity
 
 Celerity only runs on JRuby, so you'll need to install the celerity gem under
@@ -115,10 +114,6 @@ JRuby:
 
    jruby -S gem install celerity
 
-Note that some specs currently fail on celerity 0.7.5, due to a bug in recent
-versions of HTMLUnit. It is recommended you use celerity 0.7.4 for the time
-being.
-
 == Culerity
 
 Install celerity as noted above, make sure JRuby is in your path. Note that
@@ -130,7 +125,9 @@ The {capybara-envjs driver}[http://github.com/smparkes/capybara-envjs]
 uses the envjs gem ({GitHub}[http://github.com/smparkes/env-js],
 {rubygems.org}[http://rubygems.org/gems/envjs]) to interpret
 JavaScript outside the browser. The driver is installed by installing the capybara-envjs gem:
+
   gem install capybara-envjs
+
 More info about the driver and env.js are available through the links above. The envjs gem only supports
 Ruby 1.8.7 at this time.
 
@@ -164,8 +161,8 @@ automatically follows any redirects, and submits forms associated with buttons.
     click_link('id-of-link')
     click_link('Link Text')
     click_button('Save')
-    click('Link Text') # Click either a link or a button
-    click('Button Value')
+    click_link_or_button('Link Text')
+    click_link_or_button('Button Value')
 
 === Interacting with forms
 
@@ -181,57 +178,24 @@ with the various form elements:
     attach_file('Image', '/path/to/image.jpg')
     select('Option', :from => 'Select Box')
 
-=== Scoping
-
-Capybara makes it possible to restrict certain actions, such as interacting with
-forms or clicking links and buttons, to within a specific area of the page. For
-this purpose you can use the generic <tt>within</tt> method. Optionally you can
-specify which kind of selector (CSS or XPath to use).
-
-    within("//li[@id='employee']") do
-      fill_in 'Name', :with => 'Jimmy'
-    end
-
-    within(:css, "li#employee") do
-      fill_in 'Name', :with => 'Jimmy'
-    end
-
-You can choose which kind of selector Capybara uses by default, by setting
-<tt>Capybara.default_selector</tt>.
-
-There are special methods for restricting the scope to a specific fieldset,
-identified by either an id or the text of the fieldet's legend tag, and to a
-specific table, identified by either id or text of the table's caption tag.
-
-    within_fieldset('Employee') do
-      fill_in 'Name', :with => 'Jimmy'
-    end
-
-    within_table('Employee') do
-      fill_in 'Name', :with => 'Jimmy'
-    end
-
-You can also specify a scope to be used for future searches with the <tt>scope_to</tt>.
-It returns a handle to the session scoped to the provided selector.
-
-    scope = page.scope_to("//div[@id='foo']")
-    scope.has_xpath("//a[@class='bar']")
-
-You can also chain scopes by calling <tt>scope_to</tt> on an existing scope.
-
-    more_scope = scope.scope_to("//p")
-    more_scope.has_xpath("//a[@class='baz']")
-
 === Querying
 
 Capybara has a rich set of options for querying the page for the existence of
 certain elements, and working with and manipulating those elements.
 
+    page.has_selector?('table tr')
+    page.has_selector?(:xpath, '//table/tr')
+    page.has_no_selector?(:content)
+
     page.has_xpath?('//table/tr')
     page.has_css?('table tr.foo')
     page.has_content?('foo')
 
-You can use with RSpecs magic matchers:
+You can these use with RSpec's magic matchers:
+
+    page.should have_selector('table tr')
+    page.should have_selector(:xpath, '//table/tr')
+    page.should have_no_selector(:content)
 
     page.should have_xpath('//table/tr')
     page.should have_css('table tr.foo')
@@ -242,16 +206,54 @@ Note that <tt>page.should have_no_xpath</tt> is preferred over
 <tt>page.should_not have_xpath</tt>. Read the section on asynchronous JavaScript
 for an explanation.
 
+=== Finding
+
 You can also find specific elements, in order to manipulate them:
 
     find_field('First Name').value
     find_link('Hello').visible?
     find_button('Send').click
 
-    find('//table/tr').click
-    locate("//*[@id='overlay'").find("//h1").click
+    find(:xpath, "//table/tr").click
+    find("#overlay").find("h1").click
     all('a').each { |a| a[:href] }
 
+Note that <tt>find</tt> will wait for an element to appear on the page, as explained in the
+AJAX section. If the element does not appear it will raise an error.
+
+These elements all have all the Capybara DSL methods available, so you can restrict them
+to specific parts of the page:
+
+    find('#navigation').click_link('Home')
+    find('#navigation').should have_button('Sign out')
+
+=== Scoping
+
+Capybara makes it possible to restrict certain actions, such as interacting with
+forms or clicking links and buttons, to within a specific area of the page. For
+this purpose you can use the generic <tt>within</tt> method. Optionally you can
+specify which kind of selector to use.
+
+    within("li#employee") do
+      fill_in 'Name', :with => 'Jimmy'
+    end
+
+    within(:xpath, "//li[@id='employee']") do
+      fill_in 'Name', :with => 'Jimmy'
+    end
+
+There are special methods for restricting the scope to a specific fieldset,
+identified by either an id or the text of the fieldet's legend tag, and to a
+specific table, identified by either id or text of the table's caption tag.
+
+    within_fieldset('Employee') do
+      fill_in 'Name', :with => 'Jimmy'
+    end
+
+    within_table('Employee') do
+      fill_in 'Name', :with => 'Jimmy'
+    end
+
 === Scripting
 
 In drivers which support it, you can easily execute JavaScript:
@@ -297,8 +299,8 @@ is (the default is 2 seconds):
 Be aware that because of this behaviour, the following two statements are *not*
 equivalent, and you should *always* use the latter!
 
-    page.should_not have_xpath('//a')
-    page.should have_no_xpath('//a')
+    page.should_not have_xpath('a')
+    page.should have_no_xpath('a')
 
 The former would incorrectly wait for the content to appear, since the
 asynchronous process has not yet removed the element from the page, it would
@@ -329,18 +331,23 @@ examples. Just load the DSL and include it anywhere:
 
 == Calling remote servers
 
-Normally Capybara expects to be testing an in-process Rack application, but you can also use it to talk to a web server running anywhere on the internets, by setting app_host:
+Normally Capybara expects to be testing an in-process Rack application, but you
+can also use it to talk to a web server running anywhere on the internets, by
+setting app_host:
 
     Capybara.current_driver = :selenium
     Capybara.app_host = 'http://www.google.com'
-    ... 
+    ...
     visit('/')
 
-Note that rack-test does not support running against a remote server. With drivers that support it, you can also visit any URL directly:
+Note that rack-test does not support running against a remote server. With
+drivers that support it, you can also visit any URL directly:
 
     visit('http://www.google.com')
 
-By default Capybara will try to boot a rack application automatically. You might want to switch off Capybara's rack server if you are running against a remote application:
+By default Capybara will try to boot a rack application automatically. You
+might want to switch off Capybara's rack server if you are running against a
+remote application:
 
     Capybara.run_server = false
 
@@ -357,42 +364,105 @@ For ultimate control, you can instantiate and use a session manually.
     end
     session.click_link 'Sign in'
 
-== XPath and CSS
+== XPath, CSS and selectors
 
 Capybara does not try to guess what kind of selector you are going to give it,
-if you want to use CSS with your 'within' declarations for example, you'll need
+if you want to use XPath with your 'within' declarations for example, you'll need
 to do:
 
-    within(:css, 'ul li') { ... }
-    find(:css, 'ul li').text
-    locate(:css, 'input#name').value
+    within(:xpath, '//ul/li') { ... }
+    find(:xpath, '//ul/li').text
+    find(:xpath, '//li[contains(.//a[@href = "#"]/text(), "foo")]').value
 
-Alternatively you can set the default selector to CSS, which may help if you are
-moving from Webrat and used CSS a lot, or simply generally prefer CSS:
+Alternatively you can set the default selector to XPath:
 
-    Capybara.default_selector = :css
-    within('ul li') { ... }
-    find('ul li').text
-    locate('input#name').value
+    Capybara.default_selector = :xpath
+    find('//ul/li').text
 
-== Gotchas:
+Capybara allows you to add custom selectors, which can be very useful if you
+find yourself using the same kinds of selectors very often:
+
+    Capybara::Selector.add(:id) { |id| XPath.descendant[XPath.attr(:id) == id.to_s] }
+    Capybara::Selector.add(:row) { |num| ".//tbody/tr[#{num}]" }
+
+These must always return an XPath expression as a String, or an XPath expression
+generated through the XPath gem. You can now use these selectors like this:
+
+    find(:id, 'post_123')
+    find(:row, 3)
 
-* Domain names (including subdomains) don't work under rack-test. Since it's a
-  pain to set up subdomains for the other drivers anyway, you should consider an
-  alternate solution. You might use
-  {default_url_options}[https://gist.github.com/643a758320a2926bd2ed] in Rails
-  for example.
+You can specify an optional :for option which will automatically use the
+selector if it matches the argument to find using ===:
+
+    Capybara::Selector.add(:id, :for => Symbol) { |id| XPath.descendant[XPath.attr(:id) == id.to_s] }
+
+Now use it like this:
+
+    find(:post_123)
+
+This :id selector is already built into Capybara by default, so you don't
+need to add it yourself.
+
+== Beware the XPath // trap
+
+In XPath the expression // means something very specific, and it might not be what
+you think. Contrary to common belief, // means "anywhere in the document" not "anywhere
+in the current context". As an example:
+
+    page.find(:xpath, '//body').all(:xpath, '//script')
+
+You might expect this to find all script tags in the body, but actually, it finds all
+script tags in the entire document, not only those in the body! What you're looking
+for is the .// expression which means "any descendant of the current node":
+
+    page.find(:xpath, '//body').all(:xpath, './/script')
+
+The same thing goes for within:
+
+    within(:xpath, '//body') do
+      page.find(:xpath, './/script')
+      within(:xpath, './/table/tbody') do
+        ...
+      end
+    end
+
+== Configuring and adding drivers
+
+Capybara makes it convenient to switch between different drivers. It also exposes
+an API to tweak those drivers with whatever settings you want, or to add your own
+drivers. This is how to switch the selenium driver to use chrome:
+
+    Capybara.register_driver :selenium do |app|
+      Capybara::Driver::Selenium.new(app, :browser => :chrome)
+    end
+
+However, it's also possible to give this a different name, so tests can switch
+between using different browsers effortlessly:
+
+    Capybara.register_driver :selenium_chrome do |app|
+      Capybara::Driver::Selenium.new(app, :browser => :chrome)
+    end
+
+Whatever is returned from the block should conform to the API described by
+Capybara::Driver::Base, it does not however have to inherit from this class.
+Gems can use this API to add their own drivers to Capybara.
+
+== Gotchas:
 
-* Access to session, request and response from the test is not possible. Maybe
-  we'll do response headers at some point in the future, but the others really
-  shouldn't be touched in an integration test anyway.
+* Access to session and request is not possible from the test, Access to
+  response is limited. Some drivers allow access to response headers and HTTP
+  status code, but this kind of functionality is not provided by some drivers,
+  such as Selenium.
 
 * Access to Rails specific stuff (such as <tt>controller</tt>) is unavailable,
   since we're not using Rails' integration testing.
 
-* <tt><a href="#"></tt> Will cause problems under rack-test, please do
-  <tt><a href="/same/url#"></tt> instead. You can achieve this in Rails with
-  <tt>link_to('foo', :anchor => '')</tt>
+* Freezing time: It's common practice to mock out the Time so that features
+  that depend on the current Date work as expected. This can be problematic,
+  since Capybara's AJAX timing uses the system time, resulting in Capybara
+  never timing out and just hanging when a failure occurs. It's still possible to
+  use plugins which allow you to travel in time, rather than freeze time.
+  One such plugin is {Timecop}[http://github.com/jtrupiano/timecop].
 
 == License:
 

data/lib/capybara.rb

@@ -1,11 +1,11 @@
 require 'timeout'
 require 'nokogiri'
+require 'xpath'
 
 module Capybara
   class CapybaraError < StandardError; end
   class DriverNotFoundError < CapybaraError; end
   class ElementNotFound < CapybaraError; end
-  class OptionNotFound < ElementNotFound; end
   class UnselectNotAllowed < CapybaraError; end
   class NotSupportedByDriverError < CapybaraError; end
   class TimeoutError < CapybaraError; end
@@ -13,33 +13,77 @@ module Capybara
   class InfiniteRedirectError < TimeoutError; end
 
   class << self
-    attr_accessor :debug, :asset_root, :app_host, :run_server, :default_host
+    attr_accessor :asset_root, :app_host, :run_server, :default_host
+    attr_accessor :server_port
     attr_accessor :default_selector, :default_wait_time, :ignore_hidden_elements
     attr_accessor :save_and_open_page_path
 
-    def default_selector
-      @default_selector ||= :xpath
+    ##
+    #
+    # Configure Capybara to suit your needs.
+    #
+    #     Capybara.configure do |config|
+    #       config.run_server = false
+    #       config.app_host   = 'http://www.google.com'
+    #     end
+    #
+    # === Configurable options
+    #
+    # [asset_root = String]               Where static assets are located, used by save_and_open_page
+    # [app_host = String]                 The default host to use when giving a relative URL to visit
+    # [run_server = Boolean]              Whether to start a Rack server for the given Rack app (Default: true)
+    # [default_selector = :css/:xpath]    Methods which take a selector use the given type by default (Default: CSS)
+    # [default_wait_time = Integer]       The number of seconds to wait for asynchronous processes to finish (Default: 2)
+    # [ignore_hidden_elements = Boolean]  Whether to ignore hidden elements on the page (Default: false)
+    #
+    # === DSL Options
+    #
+    # when using capybara/dsl, the following options are also available:
+    #
+    # [default_driver = Symbol]           The name of the driver to use by default. (Default: :rack_test)
+    # [javascript_driver = Symbol]        The name of a driver to use for JavaScript enabled tests. (Default: :selenium)
+    #
+    def configure
+      yield self
     end
 
-    def default_wait_time
-      @default_wait_time ||= 2
+    ##
+    #
+    # Register a new driver for Capybara.
+    #
+    #     Capybara.register_driver :rack_test do |app|
+    #       Capybara::Driver::RackTest.new(app)
+    #     end
+    #
+    # @param [Symbol] name                    The name of the new driver
+    # @yield [app]                            This block takes a rack app and returns a Capybara driver
+    # @yieldparam [<Rack>] app                The rack application that this driver runs agains. May be nil.
+    # @yieldreturn [Capybara::Driver::Base]   A Capybara driver instance
+    #
+    def register_driver(name, &block)
+      drivers[name] = block
     end
 
-    def log(message)
-      puts "[capybara] #{message}" if debug
-      true
+    def drivers
+      @drivers ||= {}
+    end
+
+    def deprecate(method, alternate_method)
+      warn "DEPRECATED: ##{method} is deprecated, please use ##{alternate_method} instead"
     end
   end
 
   autoload :Server,     'capybara/server'
   autoload :Session,    'capybara/session'
   autoload :Node,       'capybara/node'
-  autoload :XPath,      'capybara/xpath'
-  autoload :Searchable, 'capybara/searchable'
+  autoload :Document,   'capybara/node'
+  autoload :Element,    'capybara/node'
+  autoload :Selector,   'capybara/selector'
   autoload :VERSION,    'capybara/version'
 
   module Driver
     autoload :Base,     'capybara/driver/base'
+    autoload :Node,     'capybara/driver/node'
     autoload :RackTest, 'capybara/driver/rack_test_driver'
     autoload :Celerity, 'capybara/driver/celerity_driver'
     autoload :Culerity, 'capybara/driver/culerity_driver'
@@ -47,7 +91,25 @@ module Capybara
   end
 end
 
-Capybara.run_server = true
-Capybara.default_selector = :xpath
-Capybara.default_wait_time = 2
-Capybara.ignore_hidden_elements = false
+Capybara.configure do |config|
+  config.run_server = true
+  config.default_selector = :css
+  config.default_wait_time = 2
+  config.ignore_hidden_elements = false
+end
+
+Capybara.register_driver :rack_test do |app|
+  Capybara::Driver::RackTest.new(app)
+end
+
+Capybara.register_driver :celerity do |app|
+  Capybara::Driver::Culerity.new(app)
+end
+
+Capybara.register_driver :culerity do |app|
+  Capybara::Driver::Culerity.new(app)
+end
+
+Capybara.register_driver :selenium do |app|
+  Capybara::Driver::Selenium.new(app)
+end