Feature specs are integral to a good test suite. Whenever we add new features to a web application, we want to make sure they work as expected and that they still work even when we do changes to underlying code or libraries. One good way to test for this is with feature specs since they can control the browser to simulate a user who could be navigating through the app. In this post, we are going to learn how to set up a Rails app to do feature specs on Chrome both locally and on CircleCI.
To do this, we need:
- Ruby and Rails installed in our development machine.
- A GitHub repo for this app.
- rspec and apparition to run our tests and connect to Chrome, respectively. We are installing them as part of the setup, so do not worry about them now.
Building the app up
First, we need to create a new Rails app.
rails new feature-spec-demo -T --skip-active-record
-T flag tells Rails not to add a testing framework for us. We want to setup
rspec for ourselves. The
--skip-active-record flag does just that. We want to skip it since we will not need a database for this app.
Once our app is bootstrapped, we
cd into it and open the
Gemfile. There should be a
development group. We need to add
rspec in there, so it looks something like this:
group :development do gem 'rspec-rails' gem 'apparition' # ... the rest of the gems in the group. end
Once we have those gems in the
Gemfile, we run:
Next, we use the helpers provided by
rspec-rails to initialize our test suite:
rails generate rspec:install
This would create all the dirs required, along with
spec/rails_helper.rb as the setup hook for our tests.
Connecting to Chrome
For our next step, we need to tell
rspec to use
apparition in order to connect to Chrome whenever we run a feature spec. We do that by adding the next code at the end of
This will register
apparition as a driver which we can use to run feature specs. Note that we are using an environment variable in the
headless option. It will come in handy if we want to see the browser running the specs. We are also passing
skip_image_loading: true, so when running in headless mode, the browser doesn't bother to load images since they will not be visible anyway. Feel free to change any of this in order to suit your project’s needs.
Adding our first feature spec
Now we are ready to create our first feature spec. Go ahead and create it by using these commands:
mkdir -p spec/features touch spec/features/first_feature_spec.rb
The file contents should be something like this:
require 'rails_helper' feature 'First feature of this app', js: true do scenario 'Visiting the Rails example homepage' do visit root_path expect(page).to have_text "Yay, You're on Rails" end end
This simple feature spec will visit the default Rails root page and check that the text "Yay, You're on Rails" is in the page. Please note that in order to run this on Chrome we need to pass
js: true at the top of the spec.
Finally, we can run the spec by running:
bundle exec rspec
If we want to see Chrome executing the spec, we can take advantage of the environment variable we set up before:
OPEN_BROWSER=1 bundle exec rspec
This should run the spec on a visible Chrome window.
Pushing our app to GitHub and setting up CircleCI
Ok, we got to a point where we can run our feature spec locally. Now we need to push everything to GitHub and set CircleCI up to run our test suite on every code push.
Let's do a first big commit with everything we have done so far:
git add . git commit -m "setup rails app with a feature spec"
Next, we need to add the CircleCI config file. This is how CircleCI knows how to build our project and run our tests.
mkdir .circleci touch .circleci/config.yml
The file contents should look like this:
version: 2 # use CircleCI 2.0 config file syntax jobs: build: docker: # run the steps inside a Docker container. More info about it on https://www.docker.com - image: circleci/ruby:2.6.1-node-browsers # we need the -browsers variant so it includes Chrome environment: # environment variables for our app RAILS_ENV: test working_directory: ~/repo steps: - checkout # special step to check out source code to working directory - run: gem install bundler # installs bundler - run: bundle install # installs project dependencies - run: bundle exec rspec # runs our tests
Once we have the file ready, let's commit it into the project:
git add .circleci git commit -m "add circleci config"
We can now push our app to GitHub by using the following commands:
git remote add origin https://github.com/username/repo # You can this URL from the repo you created for this app. git push origin master
If everything went well, you should see your app code if you visit the repo URL.
For the last step, we need to tell CircleCI to start pulling our code and running our tests. Here's how to do it:
- Head over to https://circleci.com/dashboard. Login with your GitHub account if required. Once in the Dashboard, click on the Add projects button in the sidebar menu.
- Look for your project and click the Setup project button.
- Set the specifics to build your project. Then click on Start building.
If done correctly, you should see your project in the CircleCI dashboard, and your first build job should finish successfully in a couple of seconds.
So, that's how you do it. Easy peasy, isn't it? If you have any questions, issues, or something to share with us, please write them down in the comments section below.