An RSpec cheatsheet in the form of a Rails app. Learn how to expertly test Rails apps from a model codebase

A small yet comprehensive reference for developers who want to know how to test Rails apps using RSpec.

Here you'll find in-depth examples with detailed documentation explaining how to test with RSpec and related testing gems, which you can then apply to your own projects.

This application was originally written for the benefit of the developers I coach, who've found it a useful memory aid and catalyst for when they're learning RSpec. Now I'd like to get feedback from the wider community.

The repo contains examples of various spec types such as feature, mailer, and model. See the spec/ directory for all the example specs and types.

In the README below, you'll find links to some of the most useful cheatsheets and API documentation available for RSpec users.

See the well-commented files in the spec/support directory for walkthroughs on how to configure popular testing gems, such as DatabaseCleaner, Capybara, and FactoryGirl.

Hopefully this will be of help to those of you learning RSpec and Rails. If there's anything missing you'd like to see covered in the project, please submit your request via the issue tracker, I'd be happy to help — Eliot Sykes

PS. Interested in growing your skills and supporting this project? Learn with the TDD Masterclass, get Test Coverage First Aid for your app, or grow with one-to-one coaching for Rails developers.

• Support Configuration
• Run Specs in a Random Order
• Testing Production Errors
• Testing Rake Tasks with RSpec
• Pry-rescue debugging
• Time Travel Examples
• ActiveJob Examples
• Database Cleaner Examples
• Factory Girl Examples
• VCR Examples
• Capybara Examples
• Puffing Billy Examples
• Shoulda-Matchers Examples
• Email-Spec Examples
• Devise Examples
• Custom Matchers
• RSpec-Expectations Docs
• RSpec-Mocks Specs & Docs
• RSpec-Rails
  • Matchers
  • Generators
  • Feature Specs & Docs
  • API Request Specs, Docs, & Helpers
  • Mailer Specs & Docs
  • Controller Specs & Docs
  • View Specs & Docs
  • Helper Specs & Docs
  • Routing Specs & Docs
• Validator Specs
• Enable Spring for RSpec
• Automated Continuous Integration with Travis CI
• Contributors

The tests rely on this configuration being uncommented in spec/rails_helper.rb, you probably want it uncommented in your app too:

# Loads `.rb` files in `spec/support` and its subdirectories:
Dir[Rails.root.join("spec/support/**/*.rb")].each { |f| require f }

(The rspec-rails installer generates this line, but it will be commented out.)

In a dependable, repeatable automated test suite, data stores (such as database, job queues, and sent email on ActionMailer::Base.deliveries) should return to a consistent state between each spec, regardless of the order specs are run in.

For a maintainable, predictable test suite, one spec should not set up data (e.g. creating users) needed by a later spec to pass. Each spec should look after its own test data and clear up after itself. (NB. If there is reference data that all tests need, such as populating a countries table, then this can go in db/seeds.rb and be run once before the entire suite).

The specs run in a random order each time the test suite is run. This helps prevent the introduction of run order and test data dependencies between tests, which are best avoided.

Random order test runs are configured using the config.order = :random and Kernel.srand config.seed options in spec/spec_helper.rb.

When errors are raised, the Rails test environment may not behave as in production. The test environment may mask the actual error response you want to test. To help with this, you can disable test environment exception handling temporarily, spec/support/error_responses.rb provides respond_without_detailed_exceptions. See it in use in spec/api/v1/token_spec.rb to provide production-like error responses in the test environment.

RSpec testing Rake task configuration and example:

• spec/support/tasks.rb essential to load Rake tasks before specs run
• spec/tasks/subscription_tasks_spec.rb

pry-rescue can be used to debug failing specs, by opening pry's debugger whenever a test failure is encountered. For setup and usage see pry-rescue's README.

ActiveSupport::Testing::TimeHelpers provides helpers for manipulating and freezing the current time reported within tests. These methods are often enough to replace the time-related testing methods that the timecop gem is used for.

TimeHelpers configuration how-to and examples:

• spec/support/time_helpers.rb
• spec/models/subscription_spec.rb
• spec/tasks/subscription_tasks_spec.rb
• travel_to example: spec/models/subscription_spec.rb
• ActiveSupport::Testing::TimeHelpers API documentation

ActiveJob::TestHelper provides help to test ActiveJob jobs.

ActiveJob::TestHelper configuration how-to and examples:

• spec/support/job_helpers.rb
• spec/jobs/headline_scraper_job_spec.rb
• ActiveJob::TestHelper API documentation

Database Cleaner is a set of strategies for cleaning your database in Ruby, to ensure a consistent environment for each test run.

Database Cleaner configuration how-to:

• spec/support/database_cleaner.rb

Factory Girl is a library to help setup test data. factory_girl_rails integrates Factory Girl with Rails.

Factory Girl configuration how-to and examples:

• spec/support/factory_girl.rb
• spec/factories
• spec/factories/users.rb
• spec/models/subscription_spec.rb
• spec/tasks/subscription_tasks_spec.rb
• spec/features/user_login_and_logout_spec.rb

VCR records your test suite's HTTP interactions and replays them during future test runs. Your tests can run independent of a connection to external URLs. These HTTP interactions are stored in cassette files.

VCR configuration how-to and examples:

• spec/support/vcr.rb
• spec/jobs/headline_scraper_job_spec.rb
• Cassette files in spec/support/http_cache/vcr
• VCR Relish docs
• VCR API docs

Capybara helps you write feature specs that interact with your app's UI as a user does with a browser.

Capybara configuration how-to and examples:

• spec/support/capybara.rb
• spec/features/home_page_spec.rb
• spec/features/subscribe_to_newsletter_spec.rb
• spec/features/user_login_and_logout_spec.rb
• spec/features/user_registers_spec.rb
• Capybara cheatsheet
• Capybara matchers

Puffing Billy is like VCR for browsers used by feature specs. Puffing Billy is a HTTP proxy between your browser and external sites, including 3rd party JavaScript. If your app depends on JavaScript hosted on another site, then Puffing Billy will keep a copy of that JavaScript and serve it from a local web server during testing. This means tests dependent on that JavaScript will carry on working even if the original host cannot be connected to.

If you need to debug Puffing Billy, refer to its output in log/test.log.

Puffing Billy configuration how-to and examples:

• spec/support/puffing_billy.rb
• spec/features/share_page_spec.rb
• Cache options
• Cached responses in spec/support/http_cache/billy

Shoulda-matchers make light work of model specs.

shoulda-matchers configuration how-to and examples:

• spec/support/shoulda_matchers.rb
• spec/models/subscription_spec.rb

The "Subscribe to newsletter" feature was developed with help from email_spec

email_spec configuration how-to and examples:

• spec/support/email_spec.rb
• spec/jobs/headline_scraper_job_spec.rb
• spec/mailers/news_mailer_spec.rb
• spec/mailers/subscription_mailer_spec.rb
• spec/features/subscribe_to_newsletter_spec.rb
• spec/features/user_registers_spec.rb
• EmailSpec::Helpers API documentation
• EmailSpec::Matchers API documentation

Specs testing registration, sign-in, and other user authentication features provided by Devise:

• spec/features/user_login_and_logout_spec.rb
• spec/features/user_registers_spec.rb

You can write your own custom RSpec matchers. Custom matchers can help you write more understandable specs.

Custom matchers configuration how-to and examples:

• spec/support/matchers.rb
• spec/matchers
• spec/matchers/be_pending_subscription_page.rb
• Chainable matcher: spec/matchers/be_confirm_subscription_page.rb
• spec/matchers/have_error_messages.rb
• spec/features/subscribe_to_newsletter_spec.rb
• Lightweight matcher with satisfy: spec/api/v1/token_spec.rb

• RSpec-Expectations API
• RSpec-Expectations matchers
• Expectations matchers cheatsheet

• spec/controllers/subscriptions_controller_spec.rb
• spec/mailers/subscription_mailer_spec.rb
• spec/models/subscription_spec.rb
• RSpec Mocks API

See RSpec Rails for installation instructions.

• https://relishapp.com/rspec/rspec-rails/docs/matchers

• https://relishapp.com/rspec/rspec-rails/docs/generators

• spec/features/subscribe_to_newsletter_spec.rb
• Feature specs API

• spec/api/v1/token_spec.rb
• spec/support/json_helper.rb
• spec/support/error_responses.rb
• Request specs API

• spec/mailers/subscription_mailer_spec.rb
• Mailer specs API

• spec/controllers/subscriptions_controller_spec.rb
• Controller specs API
• Controller specs cheatsheet

• The Big List of View Specs
• View specs API

• spec/helpers/application_helper_spec.rb
• Helper specs API

• spec/routing/subscriptions_routing_spec.rb
• Routing specs API

To test a custom validator you've written, refer to these validator specs from other Rails projects. These specs each follow a similar pattern where the validator is tested with a dummy model that is defined and used within the spec only. Using a dummy model is usually preferable to writing a validator spec that is dependent on a real model.

• blacklist_validator_spec.rb from Calagator
• quality_title_validator_spec.rb from Discourse
• phone_number_validator_spec.rb from Netguru-People
• no_empty_spaces_validator_spec.rb from OpenSit

Related task: Demonstrate Validator Specs within rspec-rails-examples

Spring is a Rails application preloader. It speeds up development by keeping your application running in the background so you don't need to boot it every time you run a new command.

To take advantage of this boost when you run bin/rspec, the spring-commands-rspec gem needs to be installed and a new rspec binstub needs to be created:

# 1. Add `spring-commands-rspec` to Gemfile in development and test groups and
#    install gem:
bundle install

# 2. Spring-ify the `bin/rspec` binstub:
bundle exec spring binstub rspec

# 3. Stop spring to ensure the changes are picked up:
bin/spring stop

# 4. Check bin/rspec is still working:
bin/rspec

See the spring-commands-rspec README for up-to-date installation instructions: https://github.com/jonleighton/spring-commands-rspec

Continuous Integration (CI) is the practice of integrating new code into the master branch frequently, to help detect merge conflicts, bugs, and improve the quality of the software a development team writes.

CI is usually accompanied by running an application's test suite against the latest code changes, and flagging any test failures that are found. Developers are expected to investigate and fix these failures to maintain a passing test suite and therefore quality.

Travis CI is a build server that helps automate the CI process. Travis CI runs an application's tests against the latest changes pushed to the application's code respository. In this project, Travis CI runs the project's tests (rake test) on pull requests and on changes to the master branch.

Travis CI configuration how-to and example:

• .travis.yml - Travis CI's configuration file (with instructions)
• Our Travis CI build!
• Our Travis CI badge (hopefully its green):

• Eliot Sykes https://eliotsykes.com/
• Vitaly Tatarintsev https://github.com/ck3g
• Ryan Wold https://afomi.com/
• Andy Waite http://blog.andywaite.com/
• Alex Birdsall https://github.com/ambirdsall
• Lee Smith https://github.com/leesmith
• Abdullah Alger http://www.abdullahalger.com/
• Your name here, contributions are welcome and easy, just fork the GitHub repo, make your changes, then submit your pull request! Please ask if you'd like some help.