Ninja Topics

16 min read

(For more resources related to this topic, see here.)

Using Capybara outside of Cucumber

Capybara is by no means coupled to Cucumber, and can be used in any setting you wish, within Test::Unit, RSpec, or just from vanilla Ruby code. In fact, if you are using Cucumber but want to abstract some logic out of your step definitions and into Page Objects, then you will still need to consider how to use Capybara outside of Cucumber’s world (https://github.com/cucumber/cucumber/wiki/A-Whole-New-World).

Including the modules

The first option you have for using Capybara outside of Cucumber is to include the DSL modules into your own modules or classes:

require 'capybara/dsl'
require 'rspec/expectations'
Capybara.default_driver = :selenium
module MyModule
  include Capybara::DSL
  include RSpec::Matchers

  def play_song
    visit 'http://localhost/html/html5.html'
    click_on 'Play'
    find('#log').should have_text 'playing'
  end
end
class Runner
  include MyModule
  def run
    play_song
  end
end
Runner.new.run

It is important to require the Capybara DSL file, as this contains all the Capybara methods that need to be “mixed in”. In this example, we have our own Ruby module and crucially within this, the relevant Capybara module Capybara::DSL is included. In addition, the RSpec::Matchers module has also been included, which allows us to utilize standard RSpec Matchers (obviously you do not have to use RSpec; you could choose a different way to assert behavior). If you follow this pattern in your own code, you can now mix in any of the standard Capybara methods into your own module or class methods.

It is worth remembering that if you include modules in a base class, then all subclasses will inherit the ability to use those module methods. This would come in handy, for example, if you were using a Page Object pattern, where the only class that would have to include the DSL module would be the base page.

Using the session directly

The other option for mixing Capybara into your code is to use the session directly, that is to say, you instantiate a new instance of the session object and then call the DSL methods on it.

The following example implements the same test as before, but this time by using a session instance and raising a simple exception if the expected content is not found:

require 'capybara'
session = Capybara::Session.new :selenium
session.visit('http://localhost/html/html5.html')
session.click_on 'Play'
raise 'song not playing' unless session.find('#log') == 'playing'

If you are using an object-oriented model for building your tests, you will need to pass the session instance around or find an appropriate strategy to deal with this, as you do not have the benefit of the modules mixing in the DSL methods globally.

Capybara and popular test frameworks

Capybara provides out of the box integration with a number of popular test frameworks; this is not a subject we will cover in depth, simply because they are covered very well in the Capybara README, which can be found at https://github.com/jniklas/capybara.

Cucumber

Throughout this article, examples have been set in the context of Cucumber, so you should be happy with how to implement Capybara’s API in step definitions and do some simple setup in the env.rb file, such as setting the default driver. There are a couple of additional pieces of functionality that Capybara adds when using in conjunction with Cucumber, which are worth examining.

The first is that Capybara hooks into Cucumber’s Before do block as follows:

Before do Capybara.reset_sessions! Capybara.use_default_driver end

Apart from setting the default driver, this crucially makes a call to reset_sessions!, and this in turn will invoke some code in the underlying driver. In the case of Selenium, this deletes all cookies to ensure that you start each scenario with no pollution from the previous one. For Rack::Test, this will destroy the browser instance, so a new one gets created each time; for any other drivers, you will need to check the implementation of the reset! method to see what they do.

Finally, Capybara also hooks into any Cucumber scenarios you have tagged with @javascript and automatically switches you to the driver you have set up to handle JavaScript. For example, you may use Rack::Test as your default driver, but have set the following in your env.rb file:

Capybara.javascript_dirver = :selenium

In this case, any scenarios tagged with @javascript will result in Capybara starting a browser using Selenium as the driver.

RSpec

Outside of Cucumber, RSpec is one of the most popular Ruby test frameworks, lending itself well to unit, integration, and acceptance tests, and used inside and outside of Rails.

Capybara adds the following features to RSpec:

Lets you mix in the DSL to your specs by adding require ‘capybara/rspec’ into your spec_helper.rb file
Lets you use :js => true to invoke the JavaScript driver
Adds a DSL for writing descriptive “feature style” acceptance tests using RSpec

For more details on these features, check out the README, which is available at https://github.com/jniklas/capybara.

Test::Unit

If you are using Ruby’s basic unit test library outside of Rails, then using Capybara simply means mixing in the DSL module via include Capybara::DSL, as you saw earlier.

As noted in the README, it makes a lot of sense to reset the browser session in your teardown method, for example:

  def teardown
    Capybara.reset_sessions!
    Capybara.use_default_driver
  end

If you are using Rails, then there will be other considerations, such as turning off transactional fixtures, as these will not work with Selenium; again, the Capybara README details this behavior fully.

MiniTest::Spec

MiniTest is a new unit test framework introduced in Ruby 1.9, which also has the ability to support BDD style tests.

Capybara does not have built-in support for MiniTest, because MiniTest does not use RSpec but rather uses its own matchers. There is another gem named capybara_minitest_spec (https://github.com/ordinaryzelig/capybara_minitest_spec), which adds support for these matchers to Capybara.

Advanced interactions and accessing the driver directly

Although we have covered a great deal of Capybara’s API, there are still a few interactions that we have not addressed, for example, hovering over an element or dragging elements around.

Capybara does provide support for a lot of these more advanced interactions; for example, a recent addition (Capybara 2.1) to methods you can call on an element is hover:

find('#box1').hover

In Selenium, this results in a call to the mouse.move_to method and works for both elements using CSS’s hover property or JavaScript’s mouseenter / mouseleave methods. Other drivers may implement this differently, and obviously in some it may not be supported at all, either where JavaScript support is non-existent (Rack::Test) or rudimentary (Celerity).

You can also emulate drag-and-drop using the following line of code:

find('#mydiv').drag_to '#droplocation'

Again, driver support is likely to be patchy, but of course this will work fine in Selenium WebDriver.

Despite all the bells and whistles offered by Capybara, there may still be occasions where you need to access the API that exists in the underlying driver, but that has not been mapped in Capybara. In this instance, you have two options:

Call Capybara’s native method on any Caybara::Element, and then call the driver method
Use page.driver.browser.manage to call the driver methods that are not called on elements

Using the native method

If you wish to call a method in the underlying driver, and that method is one that is called on a retrieved DOM element, then you can use the native method.

A good example is retrieving a computed CSS style value. Elements in the DOM can obtain CSS properties in a couple of ways; firstly, there is the inline style:

<p style="font-weight:bold;">Bold Paragraph Text</p>

This information could be easily retrieved by accessing the style attribute via the methods. The other way in which an element obtains CSS properties is via style elements or stylesheets that are referenced via link tags in the page. When the browser loads the stylesheets and applies styles to the specified DOM elements, these are known as computed styles.

Capybara has no direct API for retrieving the computed style of an element, which was most likely a deliberate design decision as only a few drivers would ever support this. However, Selenium WebDriver does have this capability, and it is possible that you would want to access this information.

Consider the following code, where we apply a CSS hover property to a div element, so that when the user hovers over the element, it changes color.

<html>
  <head>
    <title>Hover Examples</title>
    <style>
      .box {
        height: 200px;
        width: 200px;
        margin: 10px;
        background-color: blue;
      }
      .box:hover {
        background-color: green;
      }
    </style>
  </head>
  <body>
    <div id="main">
      <div id="box1" class="box">
      </div>
    </div>
  </body>
</html>

The Cucumber step definitions that follow use Capybara and Selenium WebDriver to assert that the color has changed:

When(/^I hover over an element whose color changes on hover using CSS$/) do
  visit 'http://capybara.local/html/chapter5/hover.html'
  find('#box1').hover 
end
Then(/^I see the color change$/) do
  find('#box1').native.style('background-color').should == '
rgba(0, 128, 0, 1)'
end

Here, the style method within Selenium WebDriver is accessed via Capybara’s native method, and the value can then be validated.

Accessing driver methods using browser.manage

The other use case is when we wish to access functionality provided in the underlying driver that is neither mapped by Capybara nor related to a specific element on the page.

A good example of this is accessing cookie information. There has been a long running debate on the Capybara forums and GitHub issue tracker, about whether Capybara should expose an API for cookie getters and setters, but the overriding feeling has always been that this should not be exposed (arguably, you should not set cookies in your tests, as this is changing the state of the application as a user never would).

Nevertheless, it is something you may well need to do, and given that Selenium WebDriver and a number of other drivers support this functionality, you will need to access the driver methods directly.

Consider this page that sets a cookie using JavaScript:

<html>
  <head>
    <title>Cookie Examples</title>
    <script>
      document.cookie = 'mycookie=foobar';
    </script>
  </head>
  <body></body>
</html>

The following steps simply visits the page and then outputs to the console all the cookies that are available on the current page:

When(/^I visit a page that sets a Cookie$/) do
  visit 'http://localhost/html/cookie.html'
end
Then(/^I can access the cookie using Selenium$/) do
  puts page.driver.browser.manage.all_cookies
end

We can access any method in the underlying driver by using page.driver.browser.manage, and then the method we wish to call; in this instance, we call Selenium WebDriver’s all_cookies method, and the output will be as follows:

 [{:name=>"mycookie", :value=>"foobar", :path=>"/html/chapter5",
  
:domain=>"localhost", :expires=>nil, :secure=>false}]

Selenium WebDriver exposes a full API for accessing and setting cookies. The documentation can be found at http://rubydoc.info/gems/selenium-webdriver/0.0.28/Selenium/WebDriver/Driver.

Advanced driver configuration

So far, we have only set the default driver or the JavaScript driver using a symbol:

Capybara.default_driver = :selenium

It is quite likely that you will need to fine-tune the configuration of your driver or register multiple configurations, which you can select from at run time.

An example of this might be that you are running tests from your office, and the corporate network sits behind an HTTP Proxy (the bane of a tester’s life). If you are using Selenium WebDriver with Firefox, you could register a custom driver configuration in Capybara as follows:

Capybara.register_driver :selenium_proxy do |app|
  profile = Selenium::WebDriver::Firefox::Profile.new
  profile["network.proxy.type"] = 1
  profile["network.proxy.no_proxies_on"] = "capybara.local"
  profile["network.proxy.http"] = "cache-mycompany.com"
  profile["network.proxy.ssl"] = 'securecache-mycompany.com'
  profile["network.proxy.http_port"] = 9999
  profile["network.proxy.ssl_port"] = 9999
  profile.native_events = true
  Capybara::Selenium::Driver.new(app, :browser => 
:firefox, :profile => profile)
end
Capybara.default_driver = :selenium_proxy

This configuration uses the Selenium WebDriver API to construct a custom Firefox profile, set the proxy details programmatically, register the driver with the name :selenium-proxy, and then make it the default driver.

Obviously the possibilities here are endless, and in browsers such as Firefox and Chrome, the amount of options you can customize runs into hundreds, so knowing how to set these is important. For example, you could use this technique to create profiles with JavaScript disabled or Cookies disabled to ensure your application behaves correctly in these cases.

The driver ecosystem

Capybara bundles two drivers, which as you know are Rack::Test and Selenium WebDriver. However, Capybara is architected in such a way to make it easy for developers to implement other drivers, and indeed, there is a healthy ecosystem of pluggable drivers, which offer interesting alternatives to the two built-in options.

Capybara-WebKit

Pretty much every developer I know who is passionate about test automation is desperate for one thing—a headless browser with great JavaScript support. A headless browser is one that runs without a UI. Headless browsers typically run tests faster than opening a real browser, and make it easy to run in Continuous Integration (CI) environments, where often, a windowing environment (either MS Windows or X11 on Linux) may not be available.

You can refer to the following links to find out more about Capybara-WebKit:

Capybara-WebKit is a driver that wraps QtWebKit and is maintained by the guys at Thoughtbot. The Qt project provides a cross-platform framework for building native GUI applications, and as part of this, it provides a WebKit browser implementation that lends itself to headless implementations.

There is a slight catch with this particular implantation of QtWebKit; you will need to install the Qt system libraries separately, and there is still a reliance on X11 being present on Linux distributions despite the browser being headless.

Poltergeist

Poltergeist is another driver, which, in the background, will use QtWebKit. The difference here is that it wraps PhantomJS, which brings a couple of potential advantages over Capybara-WebKit.

You can refer to the following links to find out more about Poltergeist:

You will still need to install PhantomJS as a system dependency, but the PhantomJS project has tackled some of the issues around making QtWebKit purely headless, so you will not need X11, and you will not need to install the entire Qt framework, because PhantomJS bundles this for you.

Capybara-Mechanize

Mechanize is a headless browser implemented purely in Ruby, and has long been a stalwart for the Ruby community; it uses Nokogiri at its core to provide DOM access, and then builds browser capabilities around this.

You can refer to the following links to find out more about Capybara-Mechanize:

Capybara-Mechanize is a driver that allows you to use Mechanize to run your tests. It is a very powerful option, but there are some important aspects to consider, such as:

No JavaScript support: Mechanize does not contain a JavaScript engine; therefore, none of the JavaScript on any of your pages will be run
No rendering engine: Mechanize does not contain a rendering engine; therefore, no computed styles will be evaluated
Fast: Because it’s not attempting to evaluate JavaScript and do graphical rendering, it will be super fast

The benefits of using Mechanize may not be obvious at first sight, and a lot will depend on how your site is implemented. For sites whose functionality is wholly dependent on JavaScript, this option is clearly not feasible; however, if your site follows the principles of “progressive enhancement”, where JavaScript is simply used to enrich the user’s experience, Mechanize is a great option. You can implement all the core functional tests using Mechanize, which will be ensure they run with minimal latency and will be far less fragile than using Selenium, and then just implement a sprinkling of Selenium or WebKit tests to test the JavaScript dependent features.

Capybara-Celerity

The final driver that is worth considering is Capybara-Celerity, which wraps the Ruby library Celerity. This is especially worth a look if you are running your test code on JRuby (Ruby running on the JVM) as Celerity itself wraps the Java library HtmlUnit.

You can refer to the following links to find out more about Capybara-Celerity:

Going back a few years, HtmlUnit would have been a serious consideration for anybody wanting a headless browser, indeed it was the default headless browser for the Selenium WebDriver project. HtmlUnit is a pure Java implementation of a browser and uses Rhino (https://developer.mozilla.org/en/docs/Rhino) to run JavaScript. Unfortunately, you may find that the JavaScript support still fails when attempting to evaluate heavy-weight JS libraries, as the project is not actively maintained, and keeping pace with the demands of modern browsers is unrealistic for a small project.

If you are looking for a headless alternative to Mechanize, Celerity is worth a look, but don’t rely on it for JavaScript support.

Summary

This article has taken you from confidently implementing Capybara tests against your application to being a Capybara ninja. By understanding how to use Capybara outside the comfort zone of Cucumber, you can now use it in almost any setting and even write your own custom framework.

This is important even if you use Cucumber, because as your Cucumber tests grow, you will probably want to implement some Page Objects and mix Capybara::DSL into these.

Another important aspect of writing effective tests is being able to configure the underlying driver and access it directly when required; there is nothing magical about this, and it means you can harness the full power of your chosen driver.

Finally, we introduced some alternative drivers that should whet your appetite and prove why Capybara is such a powerful framework. You write your tests once and then run them in multitude of compatible drivers. Win!