From c85060420df1bf09dd2d1601659ad702390b957f Mon Sep 17 00:00:00 2001 From: Phil Pirozhkov Date: Thu, 26 Mar 2020 12:49:35 +0300 Subject: [PATCH] Update docs for RSpec Rails 4.0 --- README.md | 6 +- README_DEV.md | 2 +- features/upgrade/from_1x_to_2x.md | 121 ------------------------------ 3 files changed, 5 insertions(+), 124 deletions(-) delete mode 100644 features/upgrade/from_1x_to_2x.md diff --git a/README.md b/README.md index ad3726e236..e1d54738cc 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ They’re also specifications (or _specs,_ for short): detailed explanations of how the application is supposed to behave, expressed in plain English. +Use **[`rspec-rails` 3.x][]** for Rails earlier than 5.0. Use **[`rspec-rails` 1.x][]** for Rails 2.x. [Build Status]: https://secure.travis-ci.org/rspec/rspec-rails.svg?branch=master @@ -19,6 +20,7 @@ Use **[`rspec-rails` 1.x][]** for Rails 2.x. [RSpec]: https://rspec.info/ [Ruby on Rails]: https://rubyonrails.org/ [`rspec-rails` 1.x]: https://github.com/dchelimsky/rspec-rails +[`rspec-rails` 3.x]: https://github.com/rspec/rspec-rails/tree/3-9-maintenance ## Installation @@ -190,8 +192,8 @@ to test the various parts of a Rails system: | [`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` | +| [`route_to`] | `assert_routing` | routing / controller | use with `expect(...).to route_to` | +| [`be_routable`] | | routing / controller | use with `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` | diff --git a/README_DEV.md b/README_DEV.md index bfbed90d07..8c01e824e0 100644 --- a/README_DEV.md +++ b/README_DEV.md @@ -34,6 +34,6 @@ Rails than you are trying to use now. To run the specs against a different version of Rails, use the `thor` command: ```bash -bin/thor version:use 3.2.13 +bin/thor version:use 6.0.2.2 bin/rake ``` diff --git a/features/upgrade/from_1x_to_2x.md b/features/upgrade/from_1x_to_2x.md deleted file mode 100644 index 5679ba6c52..0000000000 --- a/features/upgrade/from_1x_to_2x.md +++ /dev/null @@ -1,121 +0,0 @@ -# Upgrading from rspec-rails-1.x to rspec-rails-2 - -This is a work in progress. Please submit errata, missing steps, or patches to -the [rspec-rails issue tracker](https://github.com/rspec/rspec-rails/issues). - -## Rake tasks - -Delete lib/tasks/rspec.rake, if present. Rake tasks now live in the rspec-rails -gem. - -## `spec_helper.rb` - -There were a few changes to the generated `spec/spec_helper.rb` file. We -recommend the following: - -1. set aside a copy of your existing `spec/spec_helper.rb` file. -2. run `rails generate rspec:install` -3. copy any customizations from your old spec_helper to the new one - -If you prefer to make the changes manually in the existing spec_helper, here -is what you need to change: - - # rspec-1 - require 'spec/autorun' - - Spec::Runner.configure do |config| - ... - end - - # rspec-2 - require 'rspec/rails' - - RSpec.configure do |config| - ... - end - -## Controller specs - -### isolation from view templates - -By default, controller specs do _not_ render view templates. This keeps -controller specs isolated from the content of views and their requirements. - -NOTE that the template must exist, but it will not be rendered. This is -different from rspec-rails-1.x, in which the template didn't need to exist, but -ActionController makes a number of new decisions in Rails 3 based on the -existence of the template. To keep the RSpec code free of monkey patches, and -to keep the rspec user experience simpler, we decided that this would be a fair -trade-off. - -### `response.should render_template` - -This needs to move from before the action to after. For example: - - # rspec-rails-1 - controller.should render_template("edit") - get :edit, :id => "37" - - # rspec-rails-2 - get :edit, :id => "37" - response.should render_template("edit") - - # rspec-rails-2 with expect syntax - get :edit, :id => "37" - expect(response).to render_template("edit") - -rspec-1 had to monkey patch Rails to get render_template to work before the -action, and this broke a couple of times with Rails releases (requiring urgent -fix releases in RSpec). Part of the philosophy of rspec-rails-2 is to rely on -public APIs in Rails as much as possible. In this case, `render_template` -delegates directly to Rails' `assert_template`, which only works after the -action. - -## View specs - -### `view.should render_template` - -Rails changed the way it renders partials, so to set an expectation that a -partial gets rendered, you need - - render - view.should render_template(:partial => "widget/_row") - -### stub_template - -Introduced in rspec-rails-2.2, simulates the presence of view templates on the -file system. This supports isolation from partials rendered by the vew template -that is the subject of a view example: - - stub_template "widgets/_widget.html.erb" => "This Content" - -### No more `have_tag` or `have_text` - -Before Webrat came along, rspec-rails had its own `have_tag` and `have_text` -matchers that wrapped Rails' `assert_select`. Webrat included replacements for -these methods, as well as new matchers (`have_selector` and `have_xpath`), all -of which rely on Nokogiri to do its work, and are far less brittle than RSpec's -`have_tag`. - -Capybara has similar matchers, which will soon be available view specs (they -are already available in controller specs with `render_views`). - -Given the brittleness of RSpec's `have_tag` and `have_text` matchers and the -presence of new Webrat and Capybara matchers that do a better job, `have_tag` -and `have_text` were not included in rspec-rails-2. - -## Mocks, stubs, doubles - -### as_new_record - -Earlier versions of the view generators generated stub_model with `:new_record? -=> true`. That is no longer recognized in rspec-rails-2, so you need to change -this: - - stub_model(Widget, :new_record? => true) - -to this: - - stub_model(Widget).as_new_record - -Generators in 2.0.0 final release will do the latter.