Category Archives: Capybara

How I test JavaScript-heavy Rails applications

A common question I get is how to test JavaScript in Rails applications. My approach is almost radically simple and unsophisticated.

My Rails + JavaScript testing approach

I think of the fact that the application uses JavaScript like an inconsequential and irrelevant implementation detail. I test JavaScript-heavy applications using just RSpec + Capybara integration tests, the same exact way I’d test an application that has very little JavaScript or no JavaScript at all.

I don’t really have anything more to say about it since I literally don’t do anything different from my regular RSpec + Capybara tests.

Single-page applications

What about single-page applications? I still use the same approach. When I used to build Angular + Rails SPAs, I would add a before(:all) RSpec hook that would kick off a build of my Angular application before the test suite ran. After that point my RSpec + Capybara tests could interact with my SPA just as easily as if the application were a “traditional” Rails application.

I’ve tried testing single-page applications using tools like Protractor or Cypress and I don’t like it. It’s awkward and cumbersome to try to drive the Rails app from that end. How do you spin up test data? In my experience, it’s very tedious. Much easier to drive testing from the Rails end and treat the client-side JavaScript application as an implementation detail.

Side note/rant: despite the popularity of single-page applications, “traditional” Rails applications are 100% fine. Using Rails with React/Vue/Angular/etc. isn’t “modern” and using Rails without any of those isn’t “outdated”. For most regular old boring business applications, Rails by itself without a front-end framework is not only a sufficient approach but a superior approach to an SPA because the complexity of development with plain Rails and only “JavaScript sprinkles” tends to be far lower than Rails with a JavaScript framework.

Testing JavaScript directly

Despite my typical approach of treating JavaScript as a detail, there are times when I want to have a little tighter control and test my JavaScript directly. In those cases I use Jasmine to test my JavaScript.

But it’s my goal to use such little JavaScript that I never get above that threshold of complexity where I feel the need to test my JavaScript directly with Jasmine. I’ve found that if I really try, I can get away with very little JavaScript in most applications without sacrificing any UI richness.

The difference between RSpec, Capybara and Cucumber

If you’re new to Rails testing you’ve probably come across the terms RSpec, Capybara and Cucumber.

All three are testing tools. What are they for? Do you need all of them? Here are some answers.


RSpec is a testing framework. It’s what allows you to write and run your tests.

An analogous tool would be MiniTest. In my experience, most commercial Rails projects use RSpec and most open-source Ruby projects use MiniTest. At any Rails job you’re more likely to be using RSpec than MiniTest. (I’m not sure why this is the way it is.)


Some Rails tests operate at a “low level”, meaning no browser interaction is involved. Other “high level” tests do actually spin up a browser and click links, fill out form fields, etc.

Low-level tests can be executed with just RSpec and nothing more. But for tests that use the browser, something more is needed.

This is where Capybara comes into the picture. Capybara provides helper methods like fill_in to fill in a form field, click_on to click a button, etc.

Please note that Capybara does NOT have to be used in conjunction with Cucumber. It’s completely possible to write integration tests in Rails with just RSpec and Capybara.


Cucumber is a tool for writing test cases in something close to English. Here’s an example from Wikipedia:

Scenario: Eric wants to withdraw money from his bank account at an ATM
    Given Eric has a valid Credit or Debit card
    And his account balance is $100
    When he inserts his card
    And withdraws $45
    Then the ATM should return $45
    And his account balance is $55

Cucumber can be connected with RSpec and Capybara and used to write integration tests.

My personal take on Cucumber is that while the English-like syntax might appear clearer at first glance, it’s actually less clear than bare RSpec/Capybara syntax. (Would a Ruby class be more understandable if it were English instead of Ruby?)

Cucumber adds both a layer of mental overhead and a layer of maintenance overhead on top of the RSpec + Capybara combination. I always try as hard as I can to try to steer new testers away from Cucumber.

“So, what should I use to test my Rails apps?”

My advice is to use the combination of RSpec + Capybara and forget about Cucumber. What if you don’t know where to start with writing RSpec/Capybara tests? If that’s the case, you might like to check out my guide to RSpec + Capybara testing, which includes a tutorial.

Logging the user in before Capybara feature specs/system specs

Logging in

If you’re building an app that has user login functionality, you’ll at some point need to write some tests that log the user in before performing the test steps.

One approach I’ve seen is to have Capybara actually navigate to the sign in page, fill_in the email and password fields, and hit submit. This works but, if you’re using Devise, it’s a little more complicated than necessary. There’s a better way.

The Devise docs have a pretty good solution. Just add this to spec/rails_helper:

RSpec.configure do |config|
  config.include Warden::Test::Helpers

Then, any place you need to log in, you can do login_as(FactoryBot.create(:user)).

Log in before each test or log in once before all tests?

One of my readers, Justin K, wrote me with the following question:

If you use Capybara to do system tests, how do you handle authentication? Do you do the login step on each test or do you log in once and then just try and run all of your system level tests?

The answer is that I log in individually for each test.

The reason is that some of my tests require the user to be logged in, some of my tests require that the user is not logged in, and other tests require that some specific type of user (e.g. an admin user) is logged in.

I do often put my login_as call in a before block at the top of a test file to reduce duplication, but that doesn’t mean only once for that set of files. A common misconception is that a before block will give a performance benefit by only running the code in the before block once. This is not the case. before is shorthand for before(:each) and any code inside it will get run before each individual it block. I never use before(:all) inside of individual tests because I want each test case to be as isolated as possible.