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.

RSpec

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
--color
--format=doc

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|
  ...
end

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

describe

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
  ...
end

Avoid instance variables

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

Move your `before`s 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"

`context`

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
    end
  end

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

`it`

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"
  event.publish!
  expect(event.published?).to eq true
end

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"
end

# ✓ OK
it "#untested_method"

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

Metaprogramming tests

Don't.

Rails

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"
user.save
expect(user.reload.role).to eq "admin"

# or test for the just the call
expect_any_instance_of(User).to receive(:ensure_default_role)
user.save

# then test the functionality
user.nil
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

See Features.

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
end

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
  JSON.parse(response.body)
end
end

# 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
  ...
end
end

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"
end

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)
end

Capybara.javascript_driver = :chrome

config.before(:each) do |example|
Capybara.current_driver = :selenium if example.metadata[:selenium]
end

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.