rspec-rails 3.7.0 → 4.0.0

data/README.md

@@ -1,600 +1,369 @@
-# rspec-rails [![Build Status](https://secure.travis-ci.org/rspec/rspec-rails.svg?branch=master)](http://travis-ci.org/rspec/rspec-rails) [![Code Climate](https://img.shields.io/codeclimate/github/rspec/rspec-rails.svg)](https://codeclimate.com/github/rspec/rspec-rails)
-**rspec-rails** is a testing framework for Rails 3.x, 4.x and 5.0.
+# rspec-rails [![Build Status][]][travis-ci] [![Code Climate][]][code-climate] [![Gem Version][]](gem-version)
 
-Use **[rspec-rails 1.x](http://github.com/dchelimsky/rspec-rails)** for Rails
-2.x.
+`rspec-rails` brings the [RSpec][] testing framework to [Ruby on Rails][]
+as a drop-in alternative to its default testing framework, Minitest.
 
-## Installation
+In RSpec, tests are not just scripts that verify your application code.
+They’re also specifications (or _specs,_ for short):
+detailed explanations of how the application is supposed to behave,
+expressed in plain English.
 
-Add `rspec-rails` to **both** the `:development` and `:test` groups in the
-`Gemfile`:
+Use **[`rspec-rails` 1.x][]** for Rails 2.x.
 
-```ruby
-group :development, :test do
-  gem 'rspec-rails', '~> 3.6'
-end
-```
+[Build Status]: https://secure.travis-ci.org/rspec/rspec-rails.svg?branch=master
+[travis-ci]: https://travis-ci.org/rspec/rspec-rails
+[Code Climate]: https://codeclimate.com/github/rspec/rspec-rails.svg
+[code-climate]: https://codeclimate.com/github/rspec/rspec-rails
+[Gem Version]: https://badge.fury.io/rb/rspec-rails.svg
+[gem-version]: https://badge.fury.io/rb/rspec-rails
+[RSpec]: https://rspec.info/
+[Ruby on Rails]: https://rubyonrails.org/
+[`rspec-rails` 1.x]: https://github.com/dchelimsky/rspec-rails
 
-Want to run against the `master` branch? You'll need to include the dependent
-RSpec repos as well. Add the following to your `Gemfile`:
+## Installation
 
-```ruby
-%w[rspec-core rspec-expectations rspec-mocks rspec-rails rspec-support].each do |lib|
-  gem lib, :git => "https://github.com/rspec/#{lib}.git", :branch => 'master'
-end
-```
+1. Add `rspec-rails` to **both** the `:development` and `:test` groups
+   of your app’s `Gemfile`:
 
-Download and install by running:
+   ```ruby
+   # Run against the latest stable release
+   group :development, :test do
+     gem 'rspec-rails', '~> 4.0'
+   end
 
-```
-bundle install
-```
+   # Or, run against the master branch
+   # (requires master-branch versions of all related RSpec libraries)
+   group :development, :test do
+     %w[rspec-core rspec-expectations rspec-mocks rspec-rails rspec-support].each do |lib|
+       gem lib, git: "https://github.com/rspec/#{lib}.git", branch: 'master'
+     end
+   end
+   ```
 
-Initialize the `spec/` directory (where specs will reside) with:
+   (Adding it to the `:development` group is not strictly necessary,
+   but without it, generators and rake tasks must be preceded by `RAILS_ENV=test`.)
 
-```
-rails generate rspec:install
-```
+2. Then, in your project directory:
 
-This adds the following files which are used for configuration:
+   ```sh
+   # Download and install
+   $ bundle install
 
-- `.rspec`
-- `spec/spec_helper.rb`
-- `spec/rails_helper.rb`
+   # Generate boilerplate configuration files
+   # (check the comments in each generated file for more information)
+   $ rails generate rspec:install
+         create  .rspec
+         create  spec
+         create  spec/spec_helper.rb
+         create  spec/rails_helper.rb
+   ```
 
-Check the comments in each file for more information.
+## Upgrading
 
-Use the `rspec` command to run your specs:
+If your project is already using an older version of `rspec-rails`,
+upgrade to the latest version with:
 
-```
-bundle exec rspec
+```sh
+$ bundle update rspec-rails
 ```
 
-By default the above will run all `_spec.rb` files in the `spec` directory. For
-more details about this see the [RSpec spec file
-docs](https://www.relishapp.com/rspec/rspec-core/docs/spec-files).
+RSpec follows [semantic versioning](https://semver.org/),
+which means that “major version” upgrades (_e.g.,_ 2.x → 3.x)
+come with **breaking changes**.
+If you’re upgrading from version 2.x or below,
+read the [`rspec-rails` upgrade notes][] to find out what to watch out for.
 
-To run only a subset of these specs use the following command:
+Be sure to check the general [RSpec upgrade notes][] as well.
 
-```
-# Run only model specs
-bundle exec rspec spec/models
+[`rspec-rails` upgrade notes]: https://www.relishapp.com/rspec/rspec-rails/docs/upgrade
+[RSpec upgrade notes]: https://relishapp.com/rspec/docs/upgrade
 
-# Run only specs for AccountsController
-bundle exec rspec spec/controllers/accounts_controller_spec.rb
+## Usage
 
-# Run only spec on line 8 of AccountsController
-bundle exec rspec spec/controllers/accounts_controller_spec.rb:8
-```
+### Creating boilerplate specs with `rails generate`
 
-Specs can also be run via `rake spec`, though this command may be slower to
-start than the `rspec` command.
+```sh
+# RSpec hooks into built-in generators
+$ rails generate model user
+      invoke  active_record
+      create    db/migrate/20181017040312_create_users.rb
+      create    app/models/user.rb
+      invoke    rspec
+      create      spec/models/user_spec.rb
 
-In Rails 4, you may want to create a binstub for the `rspec` command so it can
-be run via `bin/rspec`:
+# RSpec also provides its own spec file generators
+$ rails generate rspec:model user
+      create  spec/models/user_spec.rb
 
+# List all RSpec generators
+$ rails generate --help | grep rspec
 ```
-bundle binstubs rspec-core
-```
-
-### Upgrade Note
-
-For detailed information on the general RSpec 3.x upgrade process see the
-[RSpec Upgrade docs](https://relishapp.com/rspec/docs/upgrade).
-
-There are three particular `rspec-rails` specific changes to be aware of:
-
-1. [The default helper files created in RSpec 3.x have changed](https://www.relishapp.com/rspec/rspec-rails/docs/upgrade#default-helper-files)
-2. [File-type inference disabled by default](https://www.relishapp.com/rspec/rspec-rails/docs/upgrade#file-type-inference-disabled)
-3. [Rails 4.x `ActiveRecord::Migration` pending migration checks](https://www.relishapp.com/rspec/rspec-rails/docs/upgrade#pending-migration-checks)
-4. Extraction of `stub_model` and `mock_model` to
-   [`rspec-activemodel-mocks`](https://github.com/rspec/rspec-activemodel-mocks)
-5. In Rails 5.x, controller testing has been moved to its own gem which is [rails-controller-testing](https://github.com/rails/rails-controller-testing). Using `assigns` in your controller specs without adding this gem will no longer work.
-6. `rspec-rails` now includes two helpers, `spec_helper.rb` and `rails_helper.rb`.
-   `spec_helper.rb` is the conventional RSpec configuration helper, whilst the
-    Rails specific loading and bootstrapping has moved to the `rails_helper.rb`
-    file. Rails specs now need this file required beforehand either at the top
-    of the specific file (recommended) or a common configuration location such
-    as your `.rspec` file.
 
-Please see the [RSpec Rails Upgrade
-docs](https://www.relishapp.com/rspec/rspec-rails/docs/upgrade) for full
-details.
+### Running specs
 
-**NOTE:** Generators run in RSpec 3.x will now require `rails_helper` instead
-of `spec_helper`.
+```sh
+# Default: Run all spec files (i.e., those matching spec/**/*_spec.rb)
+$ bundle exec rspec
 
-### Generators
+# Run all spec files in a single directory (recursively)
+$ bundle exec rspec spec/models
 
-Once installed, RSpec will generate spec files instead of Test::Unit test files
-when commands like `rails generate model` and `rails generate controller` are
-used.
+# Run a single spec file
+$ bundle exec rspec spec/controllers/accounts_controller_spec.rb
 
-You may also invoke RSpec generators independently. For instance,
-running `rails generate rspec:model` will generate a model spec. For more
-information, see [list of all
-generators](https://www.relishapp.com/rspec/rspec-rails/docs/generators).
+# Run a single example from a spec file (by line number)
+$ bundle exec rspec spec/controllers/accounts_controller_spec.rb:8
 
-## Contributing
-
-Once you've set up the environment, you'll need to cd into the working
-directory of whichever repo you want to work in. From there you can run the
-specs and cucumber features, and make patches.
-
-NOTE: You do not need to use rspec-dev to work on a specific RSpec repo. You
-can treat each RSpec repo as an independent project.
-Please see the following files:
-
-For `rspec-rails`-specific development information, see
-
-- [Build details](BUILD_DETAIL.md)
-- [Code of Conduct](CODE_OF_CONDUCT.md)
-- [Detailed contributing guide](CONTRIBUTING.md)
-- [Development setup guide](DEVELOPMENT.md)
-
-
-## Model Specs
-
-Use model specs to describe behavior of models (usually ActiveRecord-based) in
-the application.
-
-Model specs default to residing in the `spec/models` folder. Tagging any
-context with the metadata `:type => :model` treats its examples as model
-specs.
-
-For example:
-
-```ruby
-require "rails_helper"
-
-RSpec.describe User, :type => :model do
-  it "orders by last name" do
-    lindeman = User.create!(first_name: "Andy", last_name: "Lindeman")
-    chelimsky = User.create!(first_name: "David", last_name: "Chelimsky")
-
-    expect(User.ordered_by_last_name).to eq([chelimsky, lindeman])
-  end
-end
+# See all options for running specs
+$ bundle exec rspec --help
 ```
 
-For more information, see [cucumber scenarios for model
-specs](https://www.relishapp.com/rspec/rspec-rails/docs/model-specs).
+**Optional:** If `bundle exec rspec` is too verbose for you,
+you can generate a binstub at `bin/rspec` and use that instead:
 
-## Request Specs
+ ```sh
+ $ bundle binstubs rspec-core
+ ```
 
-Use request specs to describe the client-facing behavior of the application —
-specifically, the HTTP response to be issued for a given request (a.k.a.
-integration tests). Since such client-facing behavior encompasses controller
-actions, this is the type of spec to use for controller testing.
+## RSpec DSL Basics (or, how do I write a spec?)
 
-Request specs default to residing in the `spec/requests`, `spec/api`, and
-`spec/integration` directories. Tagging any context with the metadata `:type =>
-:request` treats its examples as request specs.
-
-Request specs mix in behavior from
-[ActionDispatch::Integration::Runner](http://api.rubyonrails.org/classes/ActionDispatch/Integration/Runner.html),
-which is the basis for [Rails' integration
-tests](http://guides.rubyonrails.org/testing.html#integration-testing).
+In RSpec, application behavior is described
+**first in (almost) plain English, then again in test code**, like so:
 
 ```ruby
-require 'rails_helper'
-
-RSpec.describe "home page", :type => :request do
-  it "displays the user's username after successful login" do
-    user = User.create!(:username => "jdoe", :password => "secret")
-    get "/login"
-    assert_select "form.login" do
-      assert_select "input[name=?]", "username"
-      assert_select "input[name=?]", "password"
-      assert_select "input[type=?]", "submit"
+RSpec.describe 'Post' do           #
+  context 'before publication' do  # (almost) plain English
+    it 'cannot have comments' do   #
+      expect { Post.create.comments.create! }.to raise_error(ActiveRecord::RecordInvalid)  # test code
     end
-
-    post "/login", :username => "jdoe", :password => "secret"
-    assert_select ".header .username", :text => "jdoe"
   end
 end
 ```
 
-The above example uses only standard Rails and RSpec APIs, but many
-RSpec/Rails users like to use extension libraries like
-[FactoryGirl](https://github.com/thoughtbot/factory_girl) and
-[Capybara](https://github.com/jnicklas/capybara):
-
-```ruby
-require 'rails_helper'
-
-RSpec.describe "home page", :type => :request do
-  it "displays the user's username after successful login" do
-    user = FactoryGirl.create(:user, :username => "jdoe", :password => "secret")
-    visit "/login"
-    fill_in "Username", :with => "jdoe"
-    fill_in "Password", :with => "secret"
-    click_button "Log in"
+Running `rspec` will execute this test code,
+and then use the plain-English descriptions
+to generate a report of where the application
+conforms to (or fails to meet) the spec:
 
-    expect(page).to have_selector(".header .username", :text => "jdoe")
-  end
-end
 ```
+$ rspec --format documentation spec/models/post_spec.rb
 
-FactoryGirl decouples this example from changes to validation requirements,
-which can be encoded into the underlying factory definition without requiring
-changes to this example.
-
-Among other benefits, Capybara binds the form post to the generated HTML, which
-means we don't need to specify them separately. Note that Capybara's DSL as
-shown is, by default, only available in specs in the spec/features directory.
-For more information, see the [Capybara integration
-docs](http://rubydoc.info/gems/rspec-rails/file/Capybara.md).
-
-There are several other Ruby libs that implement the factory pattern or provide
-a DSL for request specs (a.k.a. acceptance or integration specs), but
-FactoryGirl and Capybara seem to be the most widely used. Whether you choose
-these or other libs, we strongly recommend using something for each of these
-roles.
-
-For more information, see [cucumber scenarios for request
-specs](https://relishapp.com/rspec/rspec-rails/docs/request-specs/request-spec).
+Post
+  before publication
+    cannot have comments
 
-## Controller Specs
+Failures:
 
-Controller specs can be used to describe the behavior of Rails controllers. As
-of version 3.5, however, controller specs are discouraged in favor of request
-specs (which also focus largely on controllers, but capture other critical
-aspects of application behavior as well). Controller specs will continue to be
-supported until at least version 4.0 (see the [release
-notes](http://rspec.info/blog/2016/07/rspec-3-5-has-been-released/#rails-support-for-rails-5)
-for details).
+  1) Post before publication cannot have comments
+     Failure/Error: expect { Post.create.comments.create! }.to raise_error(ActiveRecord::RecordInvalid)
+       expected ActiveRecord::RecordInvalid but nothing was raised
+     # ./spec/models/post.rb:4:in `block (3 levels) in <top (required)>'
 
-For more information, see [cucumber scenarios for controller
-specs](https://www.relishapp.com/rspec/rspec-rails/docs/controller-specs).
+Finished in 0.00527 seconds (files took 0.29657 seconds to load)
+1 example, 1 failure
 
-## Feature Specs
+Failed examples:
 
-Feature specs test your application from the outside by simulating a browser.
-[`capybara`](https://github.com/jnicklas/capybara) is used to manage the
-simulated browser.
-
-Feature specs default to residing in the `spec/features` folder. Tagging any
-context with the metadata `:type => :feature` treats its examples as feature
-specs.
-
-Feature specs mix in functionality from the capybara gem, thus they require
-`capybara` to use. To use feature specs, add `capybara` to the `Gemfile`:
-
-```ruby
-gem "capybara"
+rspec ./spec/models/post_spec.rb:3 # Post before publication cannot have comments
 ```
 
-For more information, see the [cucumber scenarios for feature
-specs](https://www.relishapp.com/rspec/rspec-rails/v/3-4/docs/feature-specs/feature-spec).
+For an in-depth look at the RSpec DSL, including lots of examples,
+read the official Cucumber documentation for [RSpec Core][].
 
-## Mailer specs
+[RSpec Core]: https://relishapp.com/rspec/rspec-core/docs
 
-By default Mailer specs reside in the `spec/mailers` folder. Adding the metadata
-`:type => :mailer` to any context makes its examples be treated as mailer specs.
+### Helpful Rails Matchers
 
-`ActionMailer::TestCase::Behavior` is mixed into your mailer specs.
+In RSpec, assertions are called _expectations,_
+and every expectation is built around a _matcher._
+When you `expect(a).to eq(b)`, you’re using the `eq` matcher.
 
-```ruby
-require "rails_helper"
+In addition to [the matchers that come standard in RSpec][],
+here are some extras that make it easier
+to test the various parts of a Rails system:
 
-RSpec.describe Notifications, :type => :mailer do
-  describe "notify" do
-    let(:mail) { Notifications.signup }
+| RSpec matcher            | Delegates to      | Available in                    | Notes                                                    |
+| ------------------------ | ----------------- | ------------------------------- | -------------------------------------------------------- |
+| [`be_a_new`][]           |                   | all                             | primarily intended for controller specs                  |
+| [`render_template`][]    | `assert_template` | request / controller / view     | use with `expect(response).to`                           |
+| [`redirect_to`][]        | `assert_redirect` | request / controller            | use with `expect(response).to`                           |
+| [`route_to`]             | `assert_routing`  | routing / controller            | replaces `route_for` from version 1.x                    |
+| [`be_routable`]          |                   | routing / controller            | usu. for `expect(...).not_to be_routable`                |
+| [`have_http_status`][]   |                   | request / controller / feature  |                                                          |
+| [`match_array`][]        |                   | all                             | for comparing arrays of ActiveRecord objects             |
+| [`have_been_enqueued`][] |                   | all                             | requires config: `ActiveJob::Base.queue_adapter = :test` |
+| [`have_enqueued_job`][]  |                   | all                             | requires config: `ActiveJob::Base.queue_adapter = :test` |
 
-    it "renders the headers" do
-      expect(mail.subject).to eq("Signup")
-      expect(mail.to).to eq(["to@example.org"])
-      expect(mail.from).to eq(["from@example.com"])
-    end
+Follow the links above for examples of how each matcher is used.
 
-    it "renders the body" do
-      expect(mail.body.encoded).to match("Hi")
-    end
-  end
-end
-```
+[the matchers that come standard in RSpec]: https://relishapp.com/rspec/rspec-expectations/docs/built-in-matchers
+[`be_a_new`]: https://relishapp.com/rspec/rspec-rails/docs/matchers/be-a-new-matcher
+[`render_template`]: https://relishapp.com/rspec/rspec-rails/docs/matchers/render-template-matcher
+[`redirect_to`]: https://relishapp.com/rspec/rspec-rails/docs/matchers/redirect-to-matcher
+[`route_to`]: https://relishapp.com/rspec/rspec-rails/docs/routing-specs/route-to-matcher
+[`be_routable`]: https://relishapp.com/rspec/rspec-rails/docs/routing-specs/be-routable-matcher
+[`have_http_status`]: https://relishapp.com/rspec/rspec-rails/docs/matchers/have-http-status-matcher
+[`match_array`]: https://relishapp.com/rspec/rspec-rails/docs/matchers/activerecord-relation-match-array
+[`have_been_enqueued`]: https://relishapp.com/rspec/rspec-rails/docs/matchers/have-been-enqueued-matcher
+[`have_enqueued_job`]: https://relishapp.com/rspec/rspec-rails/docs/matchers/have-enqueued-job-matcher
 
-For more information, see the [cucumber scenarios for mailer specs
-](https://relishapp.com/rspec/rspec-rails/v/3-4/docs/mailer-specs).
+### What else does RSpec Rails add?
 
-## Job specs
+For a comprehensive look at RSpec Rails’ features,
+read the [official Cucumber documentation][].
 
-Tagging a context with the metadata `:type => :job` treats its examples as job
-specs. Typically these specs will live in `spec/jobs`.
+[official Cucumber documentation]: https://relishapp.com/rspec/rspec-rails/docs
 
-```ruby
-require 'rails_helper'
-
-RSpec.describe UploadBackupsJob, :type => :job do
-  describe "#perform_later" do
-    it "uploads a backup" do
-      ActiveJob::Base.queue_adapter = :test
-      UploadBackupsJob.perform_later('backup')
-      expect(UploadBackupsJob).to have_been_enqueued
-    end
-  end
-end
-```
+## What tests should I write?
 
-For more information, see the [cucumber scenarios for job specs
-](https://relishapp.com/rspec/rspec-rails/docs/job-specs).
+RSpec Rails defines ten different _types_ of specs
+for testing different parts of a typical Rails application.
+Each one inherits from one of Rails’ built-in `TestCase` classes,
+meaning the helper methods provided by default in Rails tests
+are available in RSpec, as well.
 
-## View specs
+  | Spec type      | Corresponding Rails test class        |
+  | -------------- | --------------------------------      |
+  | [model][]      |                                       |
+  | [controller][] | [`ActionController::TestCase`][]      |
+  | [mailer][]     | `ActionMailer::TestCase`              |
+  | [job][]        |                                       |
+  | [view][]       | `ActionView::TestCase`                |
+  | [routing][]    |                                       |
+  | [helper][]     | `ActionView::TestCase`                |
+  | [request][]    | [`ActionDispatch::IntegrationTest`][] |
+  | [feature][]    |                                       |
+  | [system][]     | [`ActionDispatch::SystemTestCase`][]  |
 
-View specs default to residing in the `spec/views` folder. Tagging any context
-with the metadata `:type => :view` treats its examples as view specs.
+Follow the links above to see examples of each spec type,
+or for official Rails API documentation on the given `TestCase` class.
 
-View specs mix in `ActionView::TestCase::Behavior`.
+> **Note: This is not a checklist.**
+>
+> Ask a hundred developers how to test an application,
+> and you’ll get a hundred different answers.
+>
+> RSpec Rails provides thoughtfully selected features
+> to encourage good testing practices, but there’s no “right” way to do it.
+> Ultimately, it’s up to you to decide how your test suite will be composed.
+
+When creating a spec file,
+assign it a type in the top-level `describe` block, like so:
 
 ```ruby
-require 'rails_helper'
+# spec/models/user_spec.rb
 
-RSpec.describe "events/index", :type => :view do
-  it "renders _event partial for each event" do
-    assign(:events, [double(Event), double(Event)])
-    render
-    expect(view).to render_template(:partial => "_event", :count => 2)
-  end
-end
-
-RSpec.describe "events/show", :type => :view do
-  it "displays the event location" do
-    assign(:event, Event.new(:location => "Chicago"))
-    render
-    expect(rendered).to include("Chicago")
-  end
-end
+RSpec.describe User, type: :model do
+...
 ```
 
-View specs infer the controller name and path from the path to the view
-template. e.g. if the template is `events/index.html.erb` then:
+[request]: https://relishapp.com/rspec/rspec-rails/docs/request-specs/request-spec
+[feature]: https://www.relishapp.com/rspec/rspec-rails/docs/feature-specs/feature-spec
+[system]: https://relishapp.com/rspec/rspec-rails/docs/system-specs/system-spec
+[model]: https://www.relishapp.com/rspec/rspec-rails/docs/model-specs
+[controller]: https://www.relishapp.com/rspec/rspec-rails/docs/controller-specs
+[mailer]: https://relishapp.com/rspec/rspec-rails/docs/mailer-specs
+[job]: https://relishapp.com/rspec/rspec-rails/docs/job-specs/job-spec
+[view]: https://www.relishapp.com/rspec/rspec-rails/docs/view-specs/view-spec
+[routing]: https://www.relishapp.com/rspec/rspec-rails/docs/routing-specs
+[helper]: https://www.relishapp.com/rspec/rspec-rails/docs/helper-specs/helper-spec
+[`ActionDispatch::IntegrationTest`]: https://api.rubyonrails.org/classes/ActionDispatch/IntegrationTest.html
+[`ActionDispatch::SystemTestCase`]: https://api.rubyonrails.org/classes/ActionDispatch/SystemTestCase.html
+[`ActionController::TestCase`]: https://api.rubyonrails.org/classes/ActionController/TestCase.html
+[in the appropriate folder]: https://relishapp.com/rspec/rspec-rails/docs/directory-structure
 
-```ruby
-controller.controller_path == "events"
-controller.request.path_parameters[:controller] == "events"
-```
+### System specs, feature specs, request specs–what’s the difference?
 
-This means that most of the time you don't need to set these values. When
-spec'ing a partial that is included across different controllers, you _may_
-need to override these values before rendering the view.
+RSpec Rails provides some end-to-end (entire application) testing capability
+to specify the interaction with the client.
 
-To provide a layout for the render, you'll need to specify _both_ the template
-and the layout explicitly. For example:
+#### System specs
 
-```ruby
-render :template => "events/show", :layout => "layouts/application"
-```
+Also called **acceptance tests**, **browser tests**, or **end-to-end tests**,
+system specs test the application from the perspective of a _human client._
+The test code walks through a user’s browser interactions,
 
-### `assign(key, val)`
+* `visit '/login'`
+* `fill_in 'Name', with: 'jdoe'`
 
-Use this to assign values to instance variables in the view:
+and the expectations revolve around page content.
 
-```ruby
-assign(:widget, Widget.new)
-render
-```
+* `expect(page).to have_text('Welcome')`
 
-The code above assigns `Widget.new` to the `@widget` variable in the view, and
-then renders the view.
+Because system specs are a wrapper around Rails’ built-in `SystemTestCase`,
+they’re only available on Rails 5.1+.
+(Feature specs serve the same purpose, but without this dependency.)
 
-Note that because view specs mix in `ActionView::TestCase` behavior, any
-instance variables you set will be transparently propagated into your views
-(similar to how instance variables you set in controller actions are made
-available in views). For example:
+#### Feature specs
 
-```ruby
-@widget = Widget.new
-render # @widget is available inside the view
-```
+Before Rails introduced system testing facilities,
+feature specs were the only spec type for end-to-end testing.
+While the RSpec team now [officially recommends system specs][] instead,
+feature specs are still fully supported, look basically identical,
+and work on older versions of Rails.
 
-RSpec doesn't officially support this pattern, which only works as a
-side-effect of the inclusion of `ActionView::TestCase`. Be aware that it may be
-made unavailable in the future.
+On the other hand, feature specs require non-trivial configuration
+to get some important features working,
+like JavaScript testing or making sure each test runs with a fresh DB state.
+With system specs, this configuration is provided out-of-the-box.
 
-#### Upgrade note
+Like system specs, feature specs require the [Capybara][] gem.
+Rails 5.1+ includes it by default as part of system tests,
+but if you don’t have the luxury of upgrading,
+be sure to add it to the `:test` group of your `Gemfile` first:
 
 ```ruby
-# rspec-rails-1.x
-assigns[key] = value
-
-# rspec-rails-2.x+
-assign(key, value)
-```
-
-### `rendered`
-
-This represents the rendered view.
-
-```ruby
-render
-expect(rendered).to match /Some text expected to appear on the page/
-```
-
-#### Upgrade note
-
-```ruby
-# rspec-rails-1.x
-render
-response.should xxx
-
-# rspec-rails-2.x+
-render
-rendered.should xxx
-
-# rspec-rails-2.x+ with expect syntax
-render
-expect(rendered).to xxx
-```
-
-## Routing specs
-
-Routing specs default to residing in the `spec/routing` folder. Tagging any
-context with the metadata `:type => :routing` treats its examples as routing
-specs.
-
-```ruby
-require 'rails_helper'
-
-RSpec.describe "routing to profiles", :type => :routing do
-  it "routes /profile/:username to profile#show for username" do
-    expect(:get => "/profiles/jsmith").to route_to(
-      :controller => "profiles",
-      :action => "show",
-      :username => "jsmith"
-    )
-  end
-
-  it "does not expose a list of profiles" do
-    expect(:get => "/profiles").not_to be_routable
-  end
+group :test do
+  gem "capybara"
 end
 ```
 
-### Upgrade note
-
-`route_for` from rspec-rails-1.x is gone. Use `route_to` and `be_routable`
-instead.
-
-## Helper specs
-
-Helper specs default to residing in the `spec/helpers` folder. Tagging any
-context with the metadata `:type => :helper` treats its examples as helper
-specs.
-
-Helper specs mix in ActionView::TestCase::Behavior. A `helper` object is
-provided which mixes in the helper module being spec'd, along with
-`ApplicationHelper` (if present).
-
-```ruby
-require 'rails_helper'
-
-RSpec.describe EventsHelper, :type => :helper do
-  describe "#link_to_event" do
-    it "displays the title, and formatted date" do
-      event = Event.new("Ruby Kaigi", Date.new(2010, 8, 27))
-      # helper is an instance of ActionView::Base configured with the
-      # EventsHelper and all of Rails' built-in helpers
-      expect(helper.link_to_event).to match /Ruby Kaigi, 27 Aug, 2010/
-    end
-  end
-end
-```
-
-## Matchers
-
-Several domain-specific matchers are provided to each of the example group
-types. Most simply delegate to their equivalent Rails' assertions.
-
-### `be_a_new`
-
-- Available in all specs
-- Primarily intended for controller specs
-
-```ruby
-expect(object).to be_a_new(Widget)
-```
-
-Passes if the object is a `Widget` and returns true for `new_record?`
+[officially recommends system specs]: https://rspec.info/blog/2017/10/rspec-3-7-has-been-released/#rails-actiondispatchsystemtest-integration-system-specs
+[Capybara]: https://github.com/teamcapybara/capybara
 
-### `render_template`
+#### Request specs
 
-- Delegates to Rails' `assert_template`
-- Available in request, controller, and view specs
+Request specs are for testing the application
+from the perspective of a _machine client._
+They begin with an HTTP request and end with the HTTP response,
+so they’re faster than feature specs,
+but do not examine your app’s UI or JavaScript.
 
-In request and controller specs, apply to the `response` object:
+Request specs provide a high-level alternative to controller specs.
+In fact, as of RSpec 3.5, both the Rails and RSpec teams
+[discourage directly testing controllers][]
+in favor of functional tests like request specs.
 
-```ruby
-expect(response).to render_template("new")
-```
-
-In view specs, apply to the `view` object:
-
-```ruby
-expect(view).to render_template(:partial => "_form", :locals => { :widget => widget } )
-```
-
-### `redirect_to`
-
-- Delegates to `assert_redirect`
-- Available in request and controller specs
-
-```ruby
-expect(response).to redirect_to(widgets_path)
-```
-
-### `route_to`
-
-- Delegates to Rails' `assert_routing`
-- Available in routing and controller specs
-
-```ruby
-expect(:get => "/widgets").to route_to(:controller => "widgets", :action => "index")
-```
-
-### `be_routable`
-
-Passes if the path is recognized by Rails' routing. This is primarily intended
-to be used with `not_to` to specify standard CRUD routes which should not be
-routable.
-
-```ruby
-expect(:get => "/widgets/1/edit").not_to be_routable
-```
-
-### `have_http_status`
-
-- Passes if `response` has a matching HTTP status code
-- The following symbolic status codes are allowed:
-  - `Rack::Utils::SYMBOL_TO_STATUS_CODE`
-  - One of the defined `ActionDispatch::TestResponse` aliases:
-    - `:error`
-    - `:missing`
-    - `:redirect`
-    - `:success`
-- Available in controller, feature, and request specs.
-
-In controller and request specs, apply to the `response` object:
+When writing them, try to answer the question,
+“For a given HTTP request (verb + path + parameters),
+what HTTP response should the application return?”
 
-```ruby
-expect(response).to have_http_status(201)
-expect(response).not_to have_http_status(:created)
-```
-
-In feature specs, apply to the `page` object:
+[discourage directly testing controllers]: https://rspec.info/blog/2016/07/rspec-3-5-has-been-released/#rails-support-for-rails-5
 
-```ruby
-expect(page).to have_http_status(:success)
-```
-
-## `rake` tasks
-
-Several rake tasks are provided as a convenience for working with RSpec. To run
-the entire spec suite use `rake spec`. To run a subset of specs use the
-associated type task, for example `rake spec:models`.
-
-A full list of the available rake tasks can be seen by running `rake -T | grep
-spec`.
+## Contributing
 
-### Customizing `rake` tasks
+- [Build details](BUILD_DETAIL.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [Detailed contributing guide](CONTRIBUTING.md)
 
-If you want to customize the behavior of `rake spec`, you may [define your own
-task in the `Rakefile` for your
-project](https://www.relishapp.com/rspec/rspec-core/docs/command-line/rake-task).
-However, you must first clear the task that rspec-rails defined:
+Once you’ve cloned the repo and [set up the environment](DEVELOPMENT.md),
+you can run the specs and Cucumber features, or submit a pull request.
 
-```ruby
-task("spec").clear
-```
+## See Also
 
+### RSpec base libraries
 
-## Also see
+* <https://github.com/rspec/rspec>
+* <https://github.com/rspec/rspec-core>
+* <https://github.com/rspec/rspec-expectations>
+* <https://github.com/rspec/rspec-mocks>
 
-* [https://github.com/rspec/rspec](https://github.com/rspec/rspec)
-* [https://github.com/rspec/rspec-core](https://github.com/rspec/rspec-core)
-* [https://github.com/rspec/rspec-expectations](https://github.com/rspec/rspec-expectations)
-* [https://github.com/rspec/rspec-mocks](https://github.com/rspec/rspec-mocks)
+### Recommended third-party extensions
 
-## Feature Requests & Bugs
+* [FactoryBot](https://github.com/thoughtbot/factory_bot)
+* [Capybara](https://github.com/teamcapybara/capybara)
+  (Included by default in Rails 5.1+.
+  Note that [additional configuration is required][] to use the Capybara DSL
+  anywhere other than system specs and feature specs.)
 
-See <http://github.com/rspec/rspec-rails/issues>
+  [additional configuration is required]: https://rubydoc.info/gems/rspec-rails/file/Capybara.md