Rails Testing guidelines

Here's a few general guidelines to walk you through your Rails testing journey:

  • Test the app you're building, not the framework or library. There's no need to test if ActiveRecord validations work for example, when ActiveRecord itself already has tests for those.

  • TDD is not required, but tested code is. While some popular testing methodologies tell you to write tests first, this doesn't matter much in practice. What matters is that your code has useful tests.

  • Code coverage doesn't mean anything. You can never know all the edge cases.

  • Code should be easy to test. If it's hard to test, change your code.

  • Fast tests are happy tests.


Avoid the should syntax

The should syntax is dead. Use the expect syntax. This also means no shoulda.

# ✗ Avoid
user.name.should eq "Davy Jones"

# ✓ OK
expect(user.name).to eq "Davy Jones"

Running specific examples

You can run specific examples by providing their line number when you run your tests.

rspec spec/models/user_spec.rb:11

Add a base .rspec config

Prefer to run specs with the --color or -c and the --format=doc or -f d options. Store it in an .rspec file in the repo so it becomes the default.

# .rspec

Find slow tests with profiling

Running specs with the --profile or -p option will display the top ten slowest examples. It also accepts a number argument. Run this in your CI, but don't place it in .rspec.

# Displays the 5 slowest examples
rspec spec/models/user_spec.rb -p 5

Use shared_examples

When faced with repetitive test code, consider refactoring them to use RSpec.shared_examples.

shared_examples "some example" do |param|

describe "my tests" do
  include_examples "some_example", "param1"


Consider examples as the project's documentation.

Use proper descriptions

Describe your methods properly and accurately. If you change what the code does, do NOT forget to update the test's description.

Top level blocks

Your top level describe block should indicate the class under test.

# This is actually a smoke test
describe Venue do

Avoid instance variables

Use let or let! instead of using @instance_variables. If in doubt, use let!.

Move your befores up top

before, around, after and let blocks should come right after a describe block and before the next describe or context block.

Use correct method prefixes

Prefix your methods with # if it's an instance method and . if it's a class method or model scope.

describe "#instance_method"
describe ".class_method"


Use context for branching code. Prefer using with and without or when.

describe "#has_comments?" do
  context "in a post with comments" do
    let!(:comment) { create :comment, post: post }
    it "returns true" do
      expect(post.has_comments?).to eq true

  context "in a post without comments" do
    it "returns false" do
      expect(post.has_comments?).to eq false


One expectation per block

Prefer to only have one expectation per it block.

Be explicit with descriptions

Say what the code does, not what it should do. (aka: avoid starting descriptions with "should".)

# ✓ OK
it "returns true"
it "sends the email"

# ✗ Avoid
it "should be true"
it "should send the email"

Use eq, not be

Prefer to use eq over be and magic matchers.

# ✓ OK
expect(user.admin?).to eq true
expect(user.age).to eq 12

# ✗ Avoid
expect(user).to be_admin
expect(user.age).to be 12

Multiline blocks

Prefer multiline blocks over one liners. If you must use one liners, use is_expected. Again, avoid using the shoulda gem.

Pending tests

Mark incomplete tests with pending.

it "publishes the event" do
  pending "because reasons"
  expect(event.published?).to eq true

For methods that don't have tests yet (but should), use an it with no block. Don't use pending.

# ✗ Avoid
describe "#untested_method" do
  pending "because reasons"

# ✓ OK
it "#untested_method"

describe "#untested_method" do
  it "succeeds with valid data"
  it "returns nil when given invalid options"

Metaprogramming tests



  • Follow the rspec-rails directory structure and naming conventions.

  • cucumber can be cucumbersome. Use RSpec features specs with capybara instead.

  • Delegate routing and view specs to features specs.

  • Only write controller specs for actions that cannot be covered by features specs. Otherwise, write features specs.

  • Use requests or api specs for testing API requests.

  • Do not forget to test helpers and rake tasks.

  • Prefer spec_helper over rails_helper. Only require rails_helper for tests that need Rails to work.

  • Always include the database_cleaner gem or it's faster cousin, database_rewinder.

  • Use factorybotrails over fixtures.

  • In your rails_helper, always set config.use_transactional_fixtures to false. This isn't necessary if you're using database_rewinder.

  • External HTTP requests are slow. Always mock them or use gems like vcr and WebMock.

  • When mocking/stubbing, never mock/stub the unit you are testing.

    # ✗ Avoid
    allow(User).to receive(:count).and_return(2)
    expect(User.count).to eq 2

Model specs

  • No mocking. Test the actual models.

  • Skip association tests.

  • Test validations. Presence validation specs are optional.

    # Validations
    expect(valid_project.errors.full_messages).to eq []
    expect(invalid_project.errors.full_messages).to include "Video url is not a valid Youtube/Vimeo url"
  • Test scopes for both inclusion and exclusion.

    # Scopes
    expect(Project.published).to include published_project
    expect(Project.published).to_not include unpublished_project
  • Callbacks testing can be done in a couple of ways.

    # Assumes an `#ensure_default_role` callback that sets the default role if not provided
    # You can use a proc
    user.role = nil
    expect { user.save }.to change(user, :role).to("default")
    # or test the effect
    user.role = "admin"
    expect(user.reload.role).to eq "admin"
    # or test for the just the call
    expect_any_instance_of(User).to receive(:ensure_default_role)
    # then test the functionality
    user.send :ensure_default_role
    expect(user.role).to eq "default"
  • Testing private methods can be optional, but only if there is a public method spec that covers it.

View specs

Don't. Prefer to use this time to write feature specs instead.

Controller specs

Lib specs

  • Unless you autoloaded the file you're testing, you will need to require it.

  • Do not require rails_helper if you can avoid it. Mock what you can.

Helper specs

  • RSpec provides a helper object so you don't have to include the module in a dummy class to test it.

    expect(helper.image_url_for user).to eq "http://wat.com/img/fifi"

Mailer specs

  • Always mock the models.

  • Do not test #deliver_now.

  • Test for addresses, subject and attachments.

    expect(mailer.to).to eq recipient.email
    expect(mailer.from).to eq sender.email
    expect(mailer.reply_to).to eq sender.reply_to_email
    expect(mailer.attachments.size).to eq 1

Request specs

  • Request specs are considered as integration tests. Treat them as such.

  • Only use these specs for testing APIs. Use Features for pages.

  • Test the body and status in the same example.

    it "returns the correct user" do
    get user_path(user)
    expect(response.body["id"]).to eq user.id
    expect(response.status).to eq 200
  • Use helpers to reduce duplication. For example, assuming you're working on a JSON API, this helper will clean up the parsing logic for you.

    # support/api_helpers.rb
    module ApiHelpers
    def json
    # rails_helper.rb
    config.include ApiHelpers, type: :request
    # usage
    expect(json["id"]).to eq user.id

Feature Specs

  • Use feature and scenario blocks.

    feature "User Authentication" do
    scenario "with valid credentials" do
  • Prefer to test for element visibility instead of testing model effects when possible.

    expect(page).to have_link "Log Out"
    # ✗ Avoid
    expect(user.signed_in?).to eq true # This should be in a unit test
  • Try to be more selective of tests. Using expect(page).to have_content will lead to really long error messages.

    # ✗ Avoid
    expect(page).to have_content "Log Out"
    # ✓ OK
    expect(page).to have_selector '#nav', text: /Log Out/
    # ❤ BETTER, if it works
    within '#nav' do
    expect(page).to have_content "Log Out"
  • Multiple expectations per scenario is encouraged. Each scenario takes time to spin up, so using less scenarios means faster tests.

  • Helper methods inside feature blocks or within the spec file is allowed.

  • Limit the usage of the js: true tag only to blocks that have javascript interaction.

  • Prefer selenium that uses the chrome driver. Avoid poltergeist and capybara-webkit.

  • There will be cases where you will be needing selenium to see what's going on. This snippet provides you with a selenium: true tag.

    # Gemfile
    gem 'capybara'
    gem 'selenium-webdriver'
    gem 'chromedriver-helper' # <- New!
    # rails_helper.rb
    Capybara.register_driver :selenium do |app|
    Capybara::Selenium::Driver.new(app, browser: :chrome)
    Capybara.javascript_driver = :chrome
    config.before(:each) do |example|
    Capybara.current_driver = :selenium if example.metadata[:selenium]
  • Don't use sleep in your specs. If you feel like you really need to, ask first.

  • Use find_button('Save').trigger('click') instead of click_button('Save') for javascript enabled specs.