Configuring and Adding Drivers

Let’s understand 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 override the selenium driver configuration to use chrome:

Capybara.register_driver :selenium do |app|

Capybara::Selenium::Driver.new(app, :browser => :chrome)

End

However, it’s also possible to give this configuration a different name.

Capybara.register_driver :selenium_chrome do |app|

Capybara::Selenium::Driver.new(app, :browser => :chrome)

End

Then tests can switch between using different browsers effortlessly: ruby Capybara.current_driver = :selenium_chrome

Whatever returns 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.

The Selenium wiki has additional info about how the underlying driver can be configured.

Gotchas

Firstly, 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.
Secondly, access to Rails specific stuff (such as controller) is unavailable, since we’re not using Rails’ integration testing.
Thirdly, 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 on ruby/platform combinations that don’t support access to a monotonic process clock, since Capybara’s Ajax timing uses the system time, resulting in Capybara never timing out and just hanging when a failure occurs.
Subsequently, when using Rack::Test, beware if attempting to visit absolute URLs.
Lastly, server errors will only be raised in the session that initiates the server thread. If you are testing for specific server errors and using multiple sessions make sure to test for the errors using the initial session (usually :default)