Capybara is one of those open source testing tools that, when you get to use it, is really nice. However, it’s new enough (or, at least, changing enough) that good documentation on it is a bit sparse when your goal is simply to get started and you don’t have a lot of supporting frameworks in place. Case in point: what if I want to test against a browser that’s displaying my web application? I’m not using Rails. I have no other automated test frameworks in place. I just need to get started as quick as possible to determine if this tool will do what I need.

I’ll show you how I started out here.

My goal here will not be to show you how to set up the most effective testing structure in Capybara. Right now my goal is just to get you using it right away, with as little cognitive friction as possible, and to point you to some references that will help you continue to investigate on your own.

If you go to the Capybara page on Github, you’ll see it says: “Capybara aims to simplify the process of integration testing Rack applications.” Rack applications are then mentioned to be those like Rails, Sinatra or Merb. Rack is the common Ruby web infrastructure powering just about every framework that you’ll come across in Ruby that has something to do with web applications. Yet, at its heart, Rack aims to provide a minimal API for connecting web servers and web frameworks. That points the way towards why Capybara is a good choice for testing web sites and web applications. On that Github page, the more important point to get is: “Capybara simulates how a real user would interact with a web application.”

This means you can fully script Capybara like you would a browser. In this way, Capybara is not really all that different from libraries like Watir or Selenium. As I alluded to, however, one of the major differences is that you won’t find as much material out there yet about Capybara; or at least, not material that isn’t written in some obtuse fashion.

So let’s go through a simple example here.

Here I first require Capybara. (Which means you do have to have the Capybara gem installed.) You’ll often see more complicated sets of require statements in some online examples. Right now I’m just doing the bare minimum to get going.

I create a session variable. One thing to understand about Capybara is that it has the concept of a class called Document. Instances of this class represents an HTML page (or “document”, if you prefer). An instance of the Session class in Capybara is something that exposes all the methods that are defined for an HTML document. The session methods allow you to set and query the current state of our “browser.” You can read about these under the Session area of the API documentation. Rather than worrying about all of that right now, just read the above like this: “Create a session to interact with a browser and store that session in a variable so that I can do things with pages that show up in the browser.”

One thing Capybara needs to know is the driver you want to use to execute your actions. By default Capybara assumes you want a driver known as Rack::Test. Other drivers you can use include Selenium, Culerity and Celerity. In this case, I’m telling Capybara that I want Selenium to be the driver.

The visit method is fairly simple: you just pass it the address you want to load and the driver will fetch the page. Notice that I’m calling the visit method on the session variable I just created. The session handles browser-level action as well as page-level actions. We’ll get to page-level actions in a bit.

There’s a few simple things we can do here. First, add the following to your script:

The current_url method returns the URL that was actually visited. You could use this to test if your application took you to the right place based on some actions. The current_path method returns the path without the protocol, domain server, and port. This is more useful for checking that you arrive on a certain page after a previous action took place. I also scan the text that was returned by the body method to see if some specific HTML was found.

NOTE: In reality, you would probably have the above statements used as parts of assertions rather than just output.

Now let’s get into the page-level actions and do something on the page:

You can click on any link or button by using click_on method and a locator. The locator in this case can be the id of the element, the text of the element or the value of the element. The click_on method will check all three for a match. I could have also used the following statement instead:

The click_on method I used originally would also check for buttons as well as links. The click_link method will only check links.

Now let’s do a few checks to make sure we’re at the place we need to be:

Here I’m using some Capybara matchers. The has_css and has_xpath methods are used to check if the particular elements I specified were found on the page. You can read more about this at the Matchers area of the API documentation.

Let’s interact with a few more fields. Add this to your script:

You can fill in text fields or text areas by using the fill_in method with a CSS selector and the :with => option to send in the data that you want to put in the field. The fill_in method will check for elements on the page that have the id, name, or label that you specify.

Let’s do a few more things:

Here I’m interacting with some check boxes, radio buttons, and a select list. As with the fill_in method, the check and choose methods will look for elements on the page that have an id, name, or label that matches what you passed in. The select method takes in the literal text of whatever you want to select and then a :from clause tells Capybara exactly which select box it should look at. As with the others, the select box will be searched for based on id, name or label.

You can check out all the actions that are available to you by looking at the Actions part of the API documentation.

This is about the most minimal structure that you can use to get Capybara working for you: essentially by directly controlling the session. I’ve found that this is an effective and efficient way to play around with Capybara and see what it’s capable of. You can use the references I provided above to check out specific areas of the API documentation. Capybara is commented quite well in its source code so I recommend using that as a resource, even if that’s not your normal inclination.

I’ll have follow up posts as I explore more about Capybara myself but the above minimalist approach really got me going in terms of learning how the library worked. Hopefully it does the same for you and saves you a bit of investigation time as well.