This article will get you setup with the bare-minimum environment to run Selenium tests with RSpec, for automated, full-stack testing of Rails apps. Once that's done, we'll work on polishing it for a nicer experience. In this post you find amalgamations of mostly outdated articles from around the internet updated to work with a modern rails system.
It's written on a clean environment courtesy of rvm
, so you may have some of the gems already setup.
A new Rails app, RSpec, and rspec-rails
First off, we'll start with a new rails project:
gem install rails --no-ri --no-rdoc
gem install rspec
gem install rspec-rails
Edit config/environment.rb and add:
config.gem "rspec", :lib => false, :version => ">= 1.2.9"
config.gem "rspec-rails", :lib => false, :version => ">= 1.2.9"
This sets up all the required files for RSpec to get off the ground, but we need to integrate it into Rails:
That will add the rake tasks, create the appropriate directories, and basic files. Now let's get Selenium up and running!
We'll need to create a separate selenium database. in config/database.yml, let's add:
To get Selenium running under our RSpec stories, we'll need the Selenium gem (note the capital "S" — it's case-sensitive). Let's also make sure we have the sqlite3 gem installed, and then prepare an appropriate environment for our selenium tests:
gem install Selenium
gem install sqlite3-ruby
cp config/environments/test.rb config/environments/selenium.rb
Open config/environments/selenium.rb and remove the last line that reads:
config.gem 'rspec-rails', :version => '>= 1.3.2', :lib => false unless File.directory?(File.join(Rails.root, 'vendor/plugins/rspec-rails'))
Sauce RC and Selenium RC
Sauce RC will broker all communication between rails and any browsers you might be driving. Get it from our downloads
page for Windows or Mac, or use Selenium RC
for Linux, and start it up so we can run our tests.
We'll need some fodder to test. Use the RSpec generator, then create and migrate the database:
script/generate rspec_scaffold person name:string age:string language:string
rake RAILS_ENV=selenium db:create
rake RAILS_ENV=selenium db:migrate
Startup our test server
Rails tests do not normally bind to a webserver, so there is no way for Selenium to access the frontend. As a temporary workaround, we'll manually invoke a Rails server using the selenium environment:
script/server -e selenium
Our spec helper
We will be using the Selenium gem, so let's add it to the spec helper:
We'll gloss over which types of tests should include selenium front-end testing for now, and just say it belongs in integration tests. Let's run an example story that will fail the first time through, and we'll then fix it.
Put the following in spec/integration/people_spec.rb:
describe "People" do
@verification_errors = 
@browser = Selenium::Client::Driver.new(
:host => "localhost",
:port => 4444,
:browser => "*firefox"
:url => "http://localhost:3000",
:timeout_in_second => 90)
@verification_errors.should == 
it "should create a new Person with valid input" do
@browser.click "link=New person"
@browser.type "person_name", "Jason Huggins"
@browser.type "person_age", "26"
@browser.type "person_language", "Albanian"
Let's try it out:
1) 'People should create a new Person with valid input' FAILED
expected false to be true
Finished in 7.443904 seconds
1 example, 1 failure
... and try our test again:
Finished in 7.079062 seconds
1 example, 0 failures
Looks good! We finally have a working rails project with rspec runners and Selenium.
Although we've got Rails, RSpec, and Selenium all working together, the relationship is not harmonious.
Automated tests in rails are not meant to serve the outside world, and as such they don't bind to a webserver/port. Tests are run within the same process, which makes them quite fast, but prevents us from using browser-based frontend tools such as Selenium. To get around that, we manually fired up a rails server instance with the selenium environment, but this is messy for a number of reasons:
- We have to manually start/stop the test server that selenium wants to access
- We have to manually create the selenium environment's database
- We have to manually migrate the selenium environment each time there's a schema change
- Worse, we have to manually reset the database after each run
- Running Selenium tests in serial is slow
We‘ve developed a plugin to automate some of these issues, called SpecStorm
. We'll go over installing it to get the most out of your tests (including running them in parallel) in the next post.
Selenium matchers are case-sensitive: @browser.click "link=New Person" won't match a link with "New person"