Testing: Set up shoulda matchers + VCR cassettes

The more I progress into my career as a software engineer, the more I realize the importance of test coverage. I don’t do TDD but find a lot of value to a decent test coverage. When you push a feature branch to Github and your continuous integration tool (in my current case Semaphore) tells you that tests fail, it is much faster and reliable to fix your logic or your test right away, rather than encountering a bug later on.

I plan to do some posts on testing, beginning with how to set up shoulda matchers and VCR cassettes (with Rails and RSpec).

Shoulda matchers

Shoulda matchers is a gem by Thoughtbot that provides quick helper phrases to test common functionality of Rails. In the Bedrocket API, we use shoulda matchers mostly to to test model validations and associations, but the library also has some Action Controller matchers.

– Example:

# item.rb
class Item
  validates       :name, presence: true
  belongs_to   :category
end

# item_spec.rb
describe Item do
  it { should validate_presence_of(:name) }
  it { should belong_to(:category) }
end

Installing shoulda-matchers

Personally I’ve ran into an error while installing gem shoulda-matchers:

Failure/Error: it { should validate_presence_of(:email) }
NoMethodError:
undefined method `validate_presence_of' for #RSpec::Core::ExampleGroup::Nested_1:0x105aa4938
# ./spec/models/user_spec.rb:4

I’ve searched and found out a way to avoid this error:
– Gemfile: Put shoulda matchers only in group test, with require: false param.

group :test do
  gem 'shoulda-matchers', '~> 2.8.0', :require => false
  gem 'fabrication'
end

– spec_helper: Require shoulda matchers

require 'rspec/rails'
require 'shoulda-matchers'

 

VCR Cassettes

VCR Cassettes records HTTP responses in yml files and “replay” them later for faster testing. It needs to be used with a HTTP stubbing tool, in this case webmock.

– Setting up:
+ Require the gems in group test:

group :test do
  gem 'webmock'
  gem 'vcr'
end

+ Configure VCR in spec/spec_helper.rb:

VCR.configure do |c|
  c.cassette_library_dir = 'spec/vcr'
  c.hook_into :webmock
  c.configure_rspec_metadata!
end

cassette_library_dir is the folder where the responses are saved.

+ The controller spec is like so:

describe 'AnalyticsController', vcr: { match_requests_on: [ :host ] } do
  describe 'write analytics' do
    # contexts and expectations
  end
end

– How it works:
+ match_requests_on parameter tells your spec when to use VCR pre-recorded responses for the result of the test. In this case, I simply want to match all requests of a certain host. But VCR also allow you to match requests by HTTP method, specific URI, URI path, URI query string, request body and headers (request matching doc).

+ Record mode: The default mode is record: once. This means VCR records the HTTP response when there are no yml files present for that request. When the spec is run subsequently, VCR will use the recorded response instead of making the request again.

+ See all record modes. To change record mode, simply add it as an argument:

describe 'AnalyticsController', vcr: { match_requests_on: [ :host ], record: new_episodes } do
end

+ When using the record once mode, simply delete the yml files to re-record responses. You should remember to re-record when code is changed to make sure that the spec still works correctly.

Advertisements

Safely plug a Rails app into an existing database

rails deploymentTraditionally there’re a few ways to set up your Rails database using rake tasks:
rake db:create db:migrate
Create a new database and run migrations
rake db:schema:load
Drop database if it exists and create tables according to your schema.
rake db:setup
Will run both rake db:schema:load and rake db:seed

db:schema:load is problematic. It is suggested in Rails schema.rb file that this is an efficient way (compared to db:migrate) to set up your database. However, it assumes that a) you have a database dedicated to the Rails app, b) have no existing data. But what if you want to create tables for your Rails app in an existing database with other important data?

Here’s a guide I’ve come up with on how to forgo migrations and integrate your Rails app into an existing database:

 1. Create tables in your production database
Feel free to namespace them like this: myproject_users instead of just users.

2. Edit database.yml
Specify the name of your database and the user/password that has access to it under the corresponding environment setting (development or production).

3. Void migration files
Under db/migrate, either comment out the files’ content or change their extension to .txt.

4. Schema dump
db/schema.rb is auto generated by running migrations. Since you don’t plan to run them, rake db:schema:dump will update schema.rb and allow it to be used with ActiveRecord.

5. Set custom table names for models
If the name of the tables are different from ActiveRecord convention (e.g.: you namespace the tables), add this to the model self.table_name = "[custom table name]". This will help Rails find the tables and avoid error.

Hope that was somewhat helpful. I’m also looking into deploying with Capistrano and submitting a pull request that would give a warning when you try to run rake db:schema:load.

The Absolute Beginner’s Guide to Capybara/RSpec

Sometimes the biggest challenge of using a new tool is not the syntax (there are always many examples for that) but getting set up. This is especially true and sometimes challenging for Rails, which is a convention-over-configuration kind of framework.

The situation

I need to write functional (aka integration or end-to-end) tests for a one-page app that relies entirely on AJAX to interact with a REST API.

Picking the tool

At the beginning I considered Cucumber. But I started seeing a lot of documentation for using Capybara in conjunction with RSpec, which I’m somewhat familiar with. It’s said to have an [intuitive API](http://rubydoc.info/github/jnicklas/capybara) and uses an easy to understand DSL (domain-specific language). So I decided on using Capybara/RSpec.

Running into problems

It was rather challenging to figure out how to configure the two gems and where to put the tests inside the ‘/spec’ folder. After about 2 hours and running ‘rspec’ unsuccessfully 30 times, I narrowed down the *key* steps in setting up Capybara test framework in a Rails app:

1. Gemfile

group :development, :test do
  gem 'rspec-rails'
  gem 'capybara'
end

2. spec/spec_helper.rb

require 'rspec/rails'
require 'rspec/autorun'
require 'capybara/rails'
require 'capybara/rspec'
require 'capybara/dsl'

The first two lines are automatically generated when you do ‘rails g rspec:install’. However, you need to require the capybara pieces manually.

3. Config the gems in spec/spec_helper.rb

Apparently selenium is the default driver for Capybara but I set it explicitly to be safe (actually I was trying everything I could get my hands on).
Capybara.default_driver = :selenium

You also need to include Capybara::DSL module so you can use phrases like ‘visit ‘/’ ‘, ‘fill_in’, ‘click_button’ in the tests.
RSpec.configure do |config|
  config.include Capybara::DSL
end

4. Where to put spec files

For RSpec, tests go under ‘spec/lib’. However, with Capybara, I have seen tests being put both under ‘spec/features’ and ‘spec/integration’. I went with the latter: ‘spec/integration/name_spec.rb’

5. Require spec_helper

At the top of each of your test file, put ‘require ‘spec_helper’ ‘

6. Test syntax

According to documentation I have come across, you can write tests either with RSpec or Capybara conventions:

describe 'log in process' do
  it 'lets user log in' do
   # Test goes in here
  end
end

I went with the Capybara way:
feature 'log in process', :js => true do
  scenario 'lets user log in' do
    # Test goes in here
  end
end

`:js => true` is supposed to help you switch to the Capybara.javascript_driver (instead of the selenium default). However, my app ended needing to use selenium web driver.

7. Capybara DSL syntax

feature 'log in process', :js => true do
  scenario 'lets user log in' do
    visit '/sessions/new'
    fill_in 'Email', :with => 'user@example.com'
    fill_in 'Password', :with => 'password'
    click_button 'Sign in'
    expect(page).to have_content 'Success'
  end
end

8. Capybara selectors

For ‘click_link’ you can select the element by id or text. But for ‘click_button’ or ‘fill_in’, you have to select by the button value or input placeholder value.
click_link('id-of-link')
click_link('Link Text')
click_button('Save')
click_on('Link Text') # clicks on either links or buttons
click_on('Button Value')

You can also find element by its id or html tag:
find_field('First Name').value
find_link('Hello').visible?
find_button('Send').click
find("#overlay").find("h1").click

9. Web driver!

Last but not least, after I set up everything else correctly and was able to run rspec without getting `undefined method` error for Capybara, my terminal told me I was missing this gem:
gem 'selenium-webdriver'

Success

As promised, when you successfully execute Capybara, the test will open up a browser and fill out username and password in the field you told it to and decide whether it fails or succeeds.

This blog post barely touches the surface of testing with Capybara. But getting to this point was a great accomplishment for me, and writing the rest promises to be easier with the help of documentation.