Module: Capybara

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

Defined Under Namespace

Modules: Driver, Node Classes: CapybaraError, DriverNotFoundError, ElementNotFound, InfiniteRedirectError, LocateHiddenElementError, NotSupportedByDriverError, Selector, Server, Session, TimeoutError, UnselectNotAllowed

Constant Summary collapse

VERSION = 
'0.4.1.1'

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Class Attribute Details

.app ⇒ Object

Returns the value of attribute app.



7
8
9
 
# File 'lib/capybara/dsl.rb', line 7

def app
  @app
end

.app_host ⇒ Object

Returns the value of attribute app_host.



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

def app_host
  @app_host
end

.asset_root ⇒ Object

Returns the value of attribute asset_root.



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

def asset_root
  @asset_root
end

.current_driver ⇒ Symbol Also known as: mode 



21
22
23
 
# File 'lib/capybara/dsl.rb', line 21

def current_driver
  @current_driver || default_driver
end

.default_driver ⇒ Symbol 



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

def default_driver
  @default_driver || :rack_test
end

.default_host ⇒ Object

Returns the value of attribute default_host.



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

def default_host
  @default_host
end

.default_selector ⇒ Object

Returns the value of attribute default_selector.



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

def default_selector
  @default_selector
end

.default_wait_time ⇒ Object

Returns the value of attribute default_wait_time.



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

def default_wait_time
  @default_wait_time
end

.ignore_hidden_elements ⇒ Object

Returns the value of attribute ignore_hidden_elements.



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

def ignore_hidden_elements
  @ignore_hidden_elements
end

.javascript_driver ⇒ Symbol 



30
31
32
 
# File 'lib/capybara/dsl.rb', line 30

def javascript_driver
  @javascript_driver || :selenium
end

.run_server ⇒ Object

Returns the value of attribute run_server.



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

def run_server
  @run_server
end

.save_and_open_page_path ⇒ Object

Returns the value of attribute save_and_open_page_path.



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

def save_and_open_page_path
  @save_and_open_page_path
end

.server_boot_timeout ⇒ Object

Returns the value of attribute server_boot_timeout.



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

def server_boot_timeout
  @server_boot_timeout
end

.server_port ⇒ Object

Returns the value of attribute server_port.



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

def server_port
  @server_port
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 explicitely 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



102
103
104
 
# File 'lib/capybara.rb', line 102

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)

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



45
46
47
 
# File 'lib/capybara.rb', line 45

def configure
  yield self
end

.current_session ⇒ Capybara::Session

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



59
60
61
 
# File 'lib/capybara/dsl.rb', line 59

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

.deprecate(method, alternate_method) ⇒ Object 



178
179
180
 
# File 'lib/capybara.rb', line 178

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

.drivers ⇒ Object 



106
107
108
 
# File 'lib/capybara.rb', line 106

def drivers
  @drivers ||= {}
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:



62
63
64
 
# File 'lib/capybara.rb', line 62

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.



68
69
70
 
# File 'lib/capybara/dsl.rb', line 68

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.



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

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) ⇒ 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_and_open_page(html)
  name = File.join(*[Capybara.save_and_open_page_path, "capybara-#{Time.new.strftime("%Y%m%d%H%M%S")}.html"].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

  open_in_browser(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



123
124
125
126
127
128
129
 
# File 'lib/capybara.rb', line 123

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 "  <ul>\n    <li id=\"home\">Home</li>\n    <li id=\"projects\">Projects</li>\n  </ul>\n"

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



154
155
156
 
# File 'lib/capybara.rb', line 154

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

.timeout(seconds = 1, driver = 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, &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
    end

    driver && driver.wait_until(delay)

    sleep(0.05)
  end
end

.use_default_driver ⇒ Object

Use the default driver as the current driver



38
39
40
 
# File 'lib/capybara/dsl.rb', line 38

def use_default_driver
  @current_driver = nil
end

.using_driver(driver) ⇒ Object

Yield a block using a specific driver



46
47
48
49
50
51
 
# File 'lib/capybara/dsl.rb', line 46

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

Instance Method Details

#page ⇒ Capybara::Session

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



97
98
99
 
# File 'lib/capybara/dsl.rb', line 97

def page
  Capybara.current_session
end