7 days of WordPress plugins, themes & templates - for free!* Unlimited asset downloads! Start 7-Day Free Trial
  1. Code
  2. Ruby

Ruby for Newbies: Testing Web Apps with Capybara and Cucumber

Scroll to top
Read Time: 10 mins

Ruby is one of the most popular languages used on the web. We’re running a Session here on Nettuts+ that will introduce you to Ruby, as well as the great frameworks and tools that go along with Ruby development. In this episode, you'll learn about testing your Sinatra apps with Cucumber, Capybara, and Rspec.

In the previous tutorial in this series, we looked at Rspec, and how you can do test-driven development with it. I mentioned that, in the next episode, we’d look at using Rspec to test web apps. However, a couple of commenters mentioned they’d be interested in seeing testing with Cucumber, so that’s what we’ll use to test a very simple web app instead. Actually, we’ll be using part of Rspec to get the same matcher syntax as you saw last time, but the actual test setup is in Cucumber.

Prefer a Screencast?

Step 1: Building the App

We’re going to create an incredibly simple Sinatra app to test. For starters, let’s create a project folder and throw this in a Gemfile:

What? You don’t know Gemfiles? Get out from under that rock and catch up with episode 8

Now, run bundle install in that directory. With the gems installed, we’re ready to go! (Optionally—if you’re using RVM—you could install these gems for this project only by running rvm --rvmrc --create 1.9.2@cucumber_example; run this before bundle install)

So, open a file called myapp.rb; here’s our super simple app; it just simulates a site that might let you sign up for a newsletter.

If you’re not familiar with Sinatra, check out Dan Harper’s excellent sessions Singing with Sinatra; that’ll get you up and running with the basics in no time.

If you are familiar with Sinatra, you’ll see that we’re creating three paths here; on the home page (’/’), we just render the index.erb template (more on the templates in a minute). If we get a post request to the path /thankyou, we take the values of the name and email parameters and assign them to instance variables. Instance variables will be available inside whatever template we render, which happens to be thankyou.erb. Finally, at /form, we render the form.erb template.

Now, let’s build these templates. Sinatra will look inside a ‘views’ folder for the templates, so let’s put them there. As you saw in myapp.rb, we’re using ERB to render the templates, so they’ll, of course, be ERB templates. If we have a layout.erb template, it will wrap all our other templates. So, let’s do this:


That call to yield will be where the other templates are inserted. And those other templates are pretty simple:




So, there’s our app. To test it manually, you can put this in a config.ru file:

And then run shotgun in the terminal. This will start up a websever, probably on port 9393. You can now poke around and test our web app. But we want to automate this testing, right? Let’s do it!

Step 2: Setting our our Test Environment

Cucumber bills itself as “behaviour driven development with elegance and joy.” While joy seems a bit far-fetched to me, I think we’ll both agree that elegance, well, Cucumber’s got it.

Because behaviour driven development is partly about understanding what the client wants before you begin coding, Cucumber aims to make its tests readable by clients (AKA, non-programmers). So, you’ll see here that all your tests are written in what appears to be plain text (it’s actually Gherkin).

Remember how, with Rspec, we has separate spec files to describe different functionalities? In Cucumber-speak, those are features, and they all belong in a “features” folder. Inside that folder create two more folders called “support” and “step_definitions.”

Inside the “support” folder, open an env.rb. This code will set up our testing environment. Here’s what we need:

This requires the different libraries that we need, and uses include to load their methods into our environment. What’s this Capybara that we’re using? Basically, it’s the functionality that allows us to use our web app, so that we can test it. It’s important to set Capybara.app to our app. I should mention that, were we doing this with a Rails app, most of this setup would be done automatically for us.

(Note: in the screencast, I include RSpec::Expectations unneccessarily; leave it out.)

Okay, so, let’s write some tests!

Step 3 Writing the Tests

Let’s start with our home page. Open the file home_pages.feature (in the “features” folder) and start with this:

This is a common way to start a feature file starts; Doesn’t really look like code, does it? Well, it’s Gherkin, a domain-specific languages (DSL) that “lets you describe software’s behaviour without detailing how that behaviour is implemented.” What we’re written so far doesn’t run in any way, but it explains the purpose of the feature. Here’s the general structure:

You don’t have to follow that template: you can put whatever you want; the purpose is to describe the feature. However, this seems to be a common pattern.

Next comes a list of scenarios that describe the feature. Here’s the first:

Each scenario can have up to three parts: Givens, Whens, and Thens:

  • Given - Given lines describe what pre-condition should exist.
  • When - When lines describe the actions you take.
  • Then - Then lines describe the result.

There are also And lines, which do whatever the line above them does. For example:

In this case, the first And line acts as a Given line, and the second one acts as a Then line.

We’ll see a few When lines shortly. But right now, let’s run that test. To do that, run cucumber in the terminal. You’ll probably see something like this:

Cucumber feature files are written to be readable to non-programmers, so we have to “implement step definitions for undefined steps.” Thankfully, Cucumber gives us some snippets to start with.

Looking at these snippets, you can see how this will work. Each step is matched with a regular expression. Any quoted values will be captured and passed as a block parameter. Inside the block, we do whatever we expect to happen as a result of that step. This might be set-up code in Given steps, some calculations or actions in When steps, and a comparison in Then steps.

Cucumber will load any files in the folder “features/step_definitions” for steps, so let’s create “sinatra_steps.rb” file and add these two steps:

In this little snippet here, we’re using Cucumber, Rspec, and Capybara. Firstly, we’ve got the cucumber Given and Then method calls. Secondly, we’re using the Capybara methods visit (to visit a URL) and has_content?. But you don’t see the call to has_content? because we’ve loaded the RSpec matchers, so we can make our tests read as they would with Rspec. If we wanted to leave RSpec out, we would just write page.has_content? text.

Now, if you run cucumber again, you’ll see that our tests pass:

Let’s add two more Scenarios for our home page:

These require two more Then steps, as you’ll find if you try to run this. Add these to sinatra_steps.rb:

You should be able to tell what these are doing: the first looks for text within a certain element on the page. The second looks for a link with the given text (yes, you could have done Then I should see "Sign up ..." in the selector "a", but I wanted to should you another Capybara/Rspec method)

Again, run cucumber; you’ll see all our tests passing:

Let’s now open “features/form_page.feature”; throw this in there:

The first scenario here is pretty simple, although we need to write the Given step for is. You can probably figure out how to do that by now:

The second one is a little more in depth. For the first time, we’re using When steps (remember, the And steps that follow the When step are also When steps). It’s pretty obvious what those When steps should do, but how do we do that in the Ruby code? Thankfully, Capybara has a few handy methods to help up:

We’re using the fill_in method, which takes the name or id attribute of an element on the page. We’re also using click_on, which will click on the element with the given text, id, or value. There are also the more specific click_link and click_button. To see more, check out the Capybara Readme. Browse around the “DSL” section to see more of the methods that Capybara offers.

When you run cucumber now, you should get all our tests, passing:


Realize that what we’re testing here is the just UI, not the underlying code. If our code really signed you up for the newsletter, we’d also have to test the code that adds the name and email address to our database, etc. Just because we see what we’re supposed to see, doesn’t mean we’ll actually receive the newsletter, right? That should be tested separately.

And that’s testing web apps with Cucumber, Capybara, and Rspec matchers. As I mentioned, check out the Capybara docs for more!

Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Code tutorials. Never miss out on learning about the next big thing.
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.