rspec-rails 2.14.0.rc1 → 2.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 04c5822ee12ba5761dfec43b208aeb0d945e70b0
-  data.tar.gz: 4b06190cf25cd2c4058da8c2b9ba777b3d0d7359
+  metadata.gz: 3d8abb1f01a347fd1b2a6ec73a1fa43744b8b721
+  data.tar.gz: 2217552c216c853b6cfb550680193da17b324269
 SHA512:
-  metadata.gz: 604533fb3bb940d49e396d434633b07ed51e3aa28a7ec16d7c00f38a4bec2722ac123a1658df97125afa827dd05afa52dc89804314ab1ff26f324b105e4945e2
-  data.tar.gz: 8c4648637f18a46590249f07de896212d4fb08a0913dcd31d48ddbfe543d1cc3f8940543f901c8db9d8c64917ce091ca0fcb9916fa0cd4a014addd2d0ac12113
+  metadata.gz: 303482e646eba42a2a8b5eb9a3d6634b769337b3a496db7b40098f0fb99f2dbc9ea05c53f7c12e97dc40dec8802ad69a100e8a26269fd3bd938ed0bac011b345
+  data.tar.gz: 8a4c7c39fe7817b538a3fb79c18cfe9852947c542a7f10b426a491968078f7a4afa6411e8c02f3840c38b7816db6204f10be7734d40fe798d5fe2590c8b71a86

data/Changelog.md

@@ -1,3 +1,15 @@
+### 2.14.0 / 2013-07-06
+[full changelog](http://github.com/rspec/rspec-rails/compare/v2.14.0.rc1...v2.14.0)
+
+Bug fixes
+
+* Rake tasks do not define methods that might interact with other libraries.
+  (Fujimura Daisuke)
+* Reverts fix for out-of-order `let` definitions in controller specs after the
+  issue was fixed upstream in rspec-core. (Andy Lindeman)
+* Fixes deprecation warning when using `expect(Model).to have(n).records` with
+  Rails 4. (Andy Lindeman)
+
 ### 2.14.0.rc1 / 2013-05-27
 [full changelog](http://github.com/rspec/rspec-rails/compare/v2.13.2...v2.14.0.rc1)
 

data/README.md

@@ -57,7 +57,7 @@ when commands like `rails generate model` and `rails generate controller` are
 used.
 
 You may also invoke invoke RSpec generators independently. For instance,
-running `rspec generate rspec:model` will generate a model spec. For more
+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).
 
@@ -402,7 +402,7 @@ expect(:get => "/widgets/1/edit").not_to be_routable
 and subsets of tests (e.g., `rake spec:models`).
 
 A full list of the available rake tasks can be seen by running `rake -T | grep
-rspec`.
+spec`.
 
 ## Customizing `rake` tasks
 

data/features/Autotest.md

@@ -0,0 +1,24 @@
+The `rspec:install` generator creates a `.rspec` file, which tells RSpec to
+tell Autotest that you're using RSpec. You'll also need to add the ZenTest and
+autotest-rails gems to your Gemfile:
+
+    gem "ZenTest", "~> 4.4.2"
+    gem "autotest-rails", "~> 4.1.0"
+
+If all of the gems in your Gemfile are installed in system gems, you can just
+type
+
+    autotest
+
+If Bundler is managing any gems for you directly (i.e. you've got `:git` or
+`:path` attributes in the Gemfile), however, you may need to run
+
+    bundle exec autotest
+
+If you do, you require Autotest's bundler plugin in a `.autotest` file in the
+project root directory or your home directory:
+
+    require "autotest/bundler"
+
+Now you can just type `autotest`, it should prefix the generated shell command
+with `bundle exec`.

data/features/Generators.md

@@ -0,0 +1,24 @@
+RSpec spec are normally generated alongside other application components.
+For instance, `rails generate model` will also generate an RSpec spec file
+for the model.
+
+Note that the generators are there to help you get started, but they are no
+substitute for writing your own examples, and they are only guaranteed to work
+out of the box for with Rails' defaults.
+
+RSpec generators can also be run independently. For instance,
+
+    rails generate rspec:model widget
+
+will create a new spec file in `spec/models/widget_spec.rb`.
+
+The same generator pattern is available for all specs:
+
+* scaffold
+* model
+* controller
+* helper
+* view
+* mailer
+* observer
+* integration

data/features/GettingStarted.md

@@ -0,0 +1,84 @@
+Install Rails-3
+
+    $ gem install rails -v "~> 3.0.0"
+
+### Generate an app
+
+    $ rails new example
+    $ cd example
+
+### Add rspec-rails to the Gemfile
+
+    $ echo 'gem "rspec-rails", :group => [:development, :test]' >> Gemfile
+
+### Install the bundle
+
+    $ bundle install
+
+### Bootstrap RSpec
+
+    $ rails generate rspec:install
+
+### Generate a scaffold
+
+    $ rails generate scaffold Widgets name:string
+
+This generates files in the `app` and `spec` directories. The files in the
+`app` directory are generated by Rails, and Rails delegates the generation of
+the files in the `spec` directory to RSpec.
+
+### Run migrations
+
+    $ rake db:migrate && rake db:test:prepare
+
+### Run RSpec
+
+    $ rake spec
+
+or
+
+    $ rspec spec --format documentation
+
+If all went well, you should see output ending with:
+
+    29 examples, 0 failures, 2 pending
+
+This output also includes the following controller spec:
+
+    WidgetsController
+      GET index
+        assigns all widgets as @widgets
+      GET show
+        assigns the requested widget as @widget
+      GET new
+        assigns a new widget as @widget
+      GET edit
+        assigns the requested widget as @widget
+      POST create
+        with valid params
+          creates a new Widget
+          assigns a newly created widget as @widget
+          redirects to the created widget
+        with invalid params
+          assigns a newly created but unsaved widget as @widget
+          re-renders the 'new' template
+      PUT update
+        with valid params
+          updates the requested widget
+          assigns the requested widget as @widget
+          redirects to the widget
+        with invalid params
+          assigns the widget as @widget
+          re-renders the 'edit' template
+      DELETE destroy
+        destroys the requested widget
+        redirects to the widgets list
+
+Output like this can help to quickly gain a high level understanding of how an
+object behaves. It also exposes which cases have been specified and which have
+not. Note the balance between the examples for the `create` and `update`
+actions. If the `redirects to the widget` example was missing from one or the
+other, it would be easy to spot.
+
+Take a look at the generated `spec/controllers/widgets_controller_spec.rb` to
+get a sense of how to organize your specs to generate output like this.

data/features/README.md

@@ -0,0 +1,56 @@
+rspec-rails extends Rails' built-in testing framework to support rspec examples
+for requests, controllers, models, views, helpers, mailers and routing.
+
+## Rails-3
+
+rspec-rails-2 supports rails-3.0.0 and later. For earlier versions of Rails,
+you need [rspec-rails-1.3](http://rspec.info).
+
+## Install
+
+    gem install rspec-rails
+
+This installs the following gems:
+
+    rspec
+    rspec-core
+    rspec-expectations
+    rspec-mocks
+    rspec-rails
+
+## Configure
+
+Add rspec-rails to the :test and :development groups in the Gemfile:
+
+    group :test, :development do
+      gem "rspec-rails", "~> 2.4"
+    end
+
+It needs to be in the :development group to expose generators and rake tasks
+without having to type RAILS_ENV=test.
+
+Now you can run:
+
+    script/rails generate rspec:install
+
+This adds the spec directory and some skeleton files, including a .rspec
+file.
+
+## Webrat and Capybara
+
+You can choose between webrat or capybara for simulating a browser, automating
+a browser, or setting expectations using the matchers they supply. Just add
+your preference to the Gemfile:
+
+    gem "webrat"
+    gem "capybara"
+
+## Issues
+
+The documentation for rspec-rails is a work in progress. We'll be adding
+Cucumber features over time, and clarifying existing ones.  If you have
+specific features you'd like to see added, find the existing documentation
+incomplete or confusing, or, better yet, wish to write a missing Cucumber
+feature yourself, please [submit an
+issue](http://github.com/rspec/rspec-rails/issues) or a [pull
+request](http://github.com/rspec/rspec-rails).

data/features/RailsVersions.md

@@ -0,0 +1,4 @@
+    rails version | rspec-rails version
+    2.3           | 1.3.4
+    3.0           | >= 2.0
+    3.1           | >= 2.6

data/features/Transactions.md

@@ -0,0 +1,84 @@
+When you run `rails generate rspec:install`, the `spec/spec_helper.rb` file
+includes the following configuration:
+
+    RSpec.configure do |config|
+      config.use_transactional_fixtures = true
+    end
+
+The name of this setting is a bit misleading. What it really means in Rails
+is "run every test method within a transaction." In the context of rspec-rails,
+it means "run every example within a transaction."
+
+The idea is to start each example with a clean database, create whatever data
+is necessary for that example, and then remove that data by simply rolling back
+the transaction at the end of the example.
+
+### Disabling transactions
+
+If you prefer to manage the data yourself, or using another tool like
+[database_cleaner](https://github.com/bmabey/database_cleaner) to do it for you,
+simply tell RSpec to tell Rails not to manage transactions:
+
+    RSpec.configure do |config|
+      config.use_transactional_fixtures = false
+    end
+
+### Data created in `before(:each)` are rolled back
+
+Any data you create in a `before(:each)` hook will be rolled back at the end of
+the example. This is a good thing because it means that each example is
+isolated from state that would otherwise be left around by the examples that
+already ran. For example:
+
+    describe Widget do
+      before(:each) do
+        @widget = Widget.create
+      end
+
+      it "does something" do
+        expect(@widget).to do_something
+      end
+        
+      it "does something else" do
+        expect(@widget).to do_something_else
+      end
+    end
+
+The `@widget` is recreated in each of the two examples above, so each example
+has a different object, _and_ the underlying data is rolled back so the data
+backing the `@widget` in each example is new.
+        
+### Data created in `before(:all)` are _not_ rolled back
+
+`before(:all)` hooks are invoked before the transaction is opened. You can use
+this to speed things up by creating data once before any example in a group is
+run, however, this introduces a number of complications and you should only do
+this if you have a firm grasp of the implications. Here are a couple of
+guidelines:
+
+1.  Be sure to clean up any data in an `after(:all)` hook:
+
+        before(:all) do
+          @widget = Widget.create!
+        end
+
+        after(:all) do
+          @widget.destroy
+        end
+
+    If you don't do that, you'll leave data lying around that will eventually
+    interfere with other examples.
+
+2.  Reload the object in a `before(:each)` hook.
+
+        before(:all) do
+          @widget = Widget.create!
+        end
+
+        before(:each) do
+          @widget.reload
+        end
+
+      Even though database updates in each example will be rolled back, the
+      object won't _know_ about those rollbacks so the object and its backing
+      data can easily get out of sync.

data/features/Upgrade.md

@@ -0,0 +1,121 @@
+# 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.