Module: Capybara

Extended by:
DSL
Defined in:
lib/capybara.rb,
lib/capybara/dsl.rb,
lib/capybara/server.rb,
lib/capybara/version.rb,
lib/capybara/session.rb,
lib/capybara/selector.rb,
lib/capybara/node/base.rb,
lib/capybara/node/simple.rb,
lib/capybara/driver/node.rb,
lib/capybara/node/finders.rb,
lib/capybara/node/actions.rb,
lib/capybara/node/element.rb,
lib/capybara/util/timeout.rb,
lib/capybara/node/document.rb,
lib/capybara/node/matchers.rb,
lib/capybara/rspec/matchers.rb,
lib/capybara/rspec/features.rb,
lib/capybara/util/save_and_open_page.rb

Defined Under Namespace

Modules: DSL, Driver, Features, Node, RSpecMatchers, RackTest, Selenium Classes: CapybaraError, DriverNotFoundError, ElementNotFound, FileNotFound, InfiniteRedirectError, LocateHiddenElementError, NotSupportedByDriverError, Selector, Server, Session, TimeoutError, UnselectNotAllowed

Constant Summary

VERSION =
'1.0.0'

Class Attribute Summary collapse

Class Method Summary collapse

Methods included from DSL

page, using_session

Class Attribute Details

.appObject

Returns the value of attribute app



12
13
14
# File 'lib/capybara/dsl.rb', line 12

def app
  @app
end

.app_hostObject

Returns the value of attribute app_host



16
17
18
# File 'lib/capybara.rb', line 16

def app_host
  @app_host
end

.asset_rootObject

Returns the value of attribute asset_root



16
17
18
# File 'lib/capybara.rb', line 16

def asset_root
  @asset_root
end

.current_driverSymbol Also known as: mode



26
27
28
# File 'lib/capybara/dsl.rb', line 26

def current_driver
  @current_driver || default_driver
end

.default_driverSymbol



18
19
20
# File 'lib/capybara/dsl.rb', line 18

def default_driver
  @default_driver || :rack_test
end

.default_hostObject

Returns the value of attribute default_host



16
17
18
# File 'lib/capybara.rb', line 16

def default_host
  @default_host
end

.default_selectorObject

Returns the value of attribute default_selector



18
19
20
# File 'lib/capybara.rb', line 18

def default_selector
  @default_selector
end

.default_wait_timeObject

Returns the value of attribute default_wait_time



18
19
20
# File 'lib/capybara.rb', line 18

def default_wait_time
  @default_wait_time
end

.ignore_hidden_elementsObject

Returns the value of attribute ignore_hidden_elements



18
19
20
# File 'lib/capybara.rb', line 18

def ignore_hidden_elements
  @ignore_hidden_elements
end

.javascript_driverSymbol



35
36
37
# File 'lib/capybara/dsl.rb', line 35

def javascript_driver
  @javascript_driver || :selenium
end

.prefer_visible_elementsObject

Returns the value of attribute prefer_visible_elements



18
19
20
# File 'lib/capybara.rb', line 18

def prefer_visible_elements
  @prefer_visible_elements
end

.run_serverObject

Returns the value of attribute run_server



16
17
18
# File 'lib/capybara.rb', line 16

def run_server
  @run_server
end

.save_and_open_page_pathObject

Returns the value of attribute save_and_open_page_path



19
20
21
# File 'lib/capybara.rb', line 19

def save_and_open_page_path
  @save_and_open_page_path
end

.server_boot_timeoutObject

Returns the value of attribute server_boot_timeout



17
18
19
# File 'lib/capybara.rb', line 17

def server_boot_timeout
  @server_boot_timeout
end

.server_portObject

Returns the value of attribute server_port



17
18
19
# File 'lib/capybara.rb', line 17

def server_port
  @server_port
end

.session_nameSymbol

The current session name.



84
85
86
# File 'lib/capybara/dsl.rb', line 84

def session_name
  @session_name ||= :default
end

Class Method Details

.add_selector(name) { ... } ⇒ Object

Add a new selector to Capybara. Selectors can be used by various methods in Capybara to find certain elements on the page in a more convenient way. For example adding a selector to find certain table rows might look like this:

Capybara.add_selector(:row) do
  xpath { |num| ".//tbody/tr[#{num}]" }
end

This makes it possible to use this selector in a variety of ways:

find(:row, 3)
page.find('table#myTable').find(:row, 3).text
page.find('table#myTable').has_selector?(:row, 3)
within(:row, 3) { page.should have_content('$100.000') }

It might be convenient to specify that the selector is automatically chosen for certain values. This way you don't have to explicitly specify that you are looking for a row, or an id. Let's say we want Capybara to treat any Symbols sent into methods like find to be treated as though they were element ids. We could achieve this like so:

Capybara.add_selector(:id) do
  xpath { |id| XPath.descendant[XPath.attr(:id) == id.to_s] }
  match { |value| value.is_a?(Symbol) }
end

Now we can retrieve elements by id like this:

find(:post_123)

Note that this particular selector already ships with Capybara.

Yields:

  • A block executed in the context of the new Selector



104
105
106
# File 'lib/capybara.rb', line 104

def add_selector(name, &block)
  Capybara::Selector.add(name, &block)
end

.configure {|_self| ... } ⇒ Object

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)

prefer_visible_elements = Boolean

Whether to prefer visible elements over hidden elements (Default: true)

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)

Yields:

  • (_self)

Yield Parameters:

  • _self (Capybara)

    the object that the method was called on



47
48
49
# File 'lib/capybara.rb', line 47

def configure
  yield self
end

.current_sessionCapybara::Session

The current Capybara::Session base on what is set as Capybara.app and Capybara.current_driver



64
65
66
# File 'lib/capybara/dsl.rb', line 64

def current_session
  session_pool["#{current_driver}:#{session_name}:#{app.object_id}"] ||= Capybara::Session.new(current_driver, app)
end

.deprecate(method, alternate_method) ⇒ Object



180
181
182
# File 'lib/capybara.rb', line 180

def deprecate(method, alternate_method)
  warn "DEPRECATED: ##{method} is deprecated, please use ##{alternate_method} instead"
end

.driversObject



108
109
110
# File 'lib/capybara.rb', line 108

def drivers
  @drivers ||= {}
end

.included(base) ⇒ Object



4
5
6
7
# File 'lib/capybara/dsl.rb', line 4

def self.included(base)
  base.send(:include, Capybara::DSL)
  warn "`include Capybara` is deprecated please use `include Capybara::DSL` instead."
end

.register_driver(name) {|app| ... } ⇒ Object

Register a new driver for Capybara.

Capybara.register_driver :rack_test do |app|
  Capybara::Driver::RackTest.new(app)
end

Yields:

  • (app)

    This block takes a rack app and returns a Capybara driver

Yield Parameters:

  • app (<Rack>)

    The rack application that this driver runs agains. May be nil.

Yield Returns:



64
65
66
# File 'lib/capybara.rb', line 64

def register_driver(name, &block)
  drivers[name] = block
end

.reset_sessions!Object Also known as: reset!

Reset sessions, cleaning out the pool of sessions. This will remove any session information such as cookies.



73
74
75
# File 'lib/capybara/dsl.rb', line 73

def reset_sessions!
  session_pool.each { |mode, session| session.reset! }
end

.run_default_server(app, port) ⇒ Object

Runs Capybara's default server for the given application and port under most circumstances you should not have to call this method manually.



169
170
171
172
173
174
175
176
177
178
# File 'lib/capybara.rb', line 169

def run_default_server(app, port)
  begin
    require 'rack/handler/thin'
    Thin::Logging.silent = true
    Rack::Handler::Thin.run(app, :Port => port)
  rescue LoadError
    require 'rack/handler/webrick'
    Rack::Handler::WEBrick.run(app, :Port => port, :AccessLog => [], :Logger => WEBrick::Log::new(nil, 0))
  end
end

.save_and_open_page(html, file_name = nil) ⇒ Object



18
19
20
# File 'lib/capybara/util/save_and_open_page.rb', line 18

def save_and_open_page(html, file_name=nil)
  open_in_browser save_page(html, file_name)
end

.save_page(html, file_name = nil) ⇒ Object



3
4
5
6
7
8
9
10
11
12
13
14
15
16
# File 'lib/capybara/util/save_and_open_page.rb', line 3

def save_page(html, file_name=nil)
  file_name ||= "capybara-#{Time.new.strftime("%Y%m%d%H%M%S")}#{rand(10**10)}.html"
  name = File.join(*[Capybara.save_and_open_page_path, file_name].compact)

  unless Capybara.save_and_open_page_path.nil? || File.directory?(Capybara.save_and_open_page_path )
    FileUtils.mkdir_p(Capybara.save_and_open_page_path)
  end
  FileUtils.touch(name) unless File.exist?(name)

  tempfile = File.new(name,'w')
  tempfile.write(rewrite_css_and_image_references(html))
  tempfile.close
  tempfile.path
end

.server {|app, port| ... } ⇒ Object

Register a proc that Capybara will call to run the Rack application.

Capybara.server do |app, port|
  require 'rack/handler/mongrel'
  Rack::Handler::Mongrel.run(app, :Port => port)
end

By default, Capybara will try to run thin, falling back to webrick.

Yields:

  • (app, port)

    This block recieves a rack app and port and should run a Rack handler



125
126
127
128
129
130
131
# File 'lib/capybara.rb', line 125

def server(&block)
  if block_given?
    @server = block
  else
    @server
  end
end

.string(html) ⇒ Capybara::Node::Simple

Wraps the given string, which should contain an HTML document or fragment in a Capybara::Node::Simple which exposes all Capybara::Node::Matchers and Capybara::Node::Finders. This allows you to query any string containing HTML in the exact same way you would query the current document in a Capybara session. For example:

node = Capybara.string <<-HTML
  <ul>
    <li id="home">Home</li>
    <li id="projects">Projects</li>
  </ul>
HTML

node.find('#projects').text # => 'Projects'
node.has_selector?('li#home', :text => 'Home')
node.has_selector?(:projects)
node.find('ul').find('li').text # => 'Home'


156
157
158
# File 'lib/capybara.rb', line 156

def string(html)
  Capybara::Node::Simple.new(html)
end

.timeout(seconds = 1, driver = nil, error_message = nil, &block) ⇒ Object

Provides timeout similar to standard library Timeout, but avoids threads



7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# File 'lib/capybara/util/timeout.rb', line 7

def timeout(seconds = 1, driver = nil, error_message = nil, &block)
  start_time = Time.now

  result = nil

  until result
    return result if result = yield

    delay = seconds - (Time.now - start_time)
    if delay <= 0
      raise TimeoutError, error_message || "timed out"
    end

    driver && driver.wait_until(delay)

    sleep(0.05)
  end
end

.use_default_driverObject

Use the default driver as the current driver



43
44
45
# File 'lib/capybara/dsl.rb', line 43

def use_default_driver
  @current_driver = nil
end

.using_driver(driver) ⇒ Object

Yield a block using a specific driver



51
52
53
54
55
56
# File 'lib/capybara/dsl.rb', line 51

def using_driver(driver)
  Capybara.current_driver = driver
  yield
ensure
  Capybara.use_default_driver
end

.using_session(name) ⇒ Object

Yield a block using a specific session name.



92
93
94
95
96
97
# File 'lib/capybara/dsl.rb', line 92

def using_session(name)
  self.session_name = name
  yield
ensure
  self.session_name = :default
end