David Chelimsky

The rails-3.0.1 release excluded a change that I had naively expected to be included. This upgrade is only necessary if you write view specs and are upgrading to rails-3.0.1. To upgrade, all you need to do is change your Gemfile to read:

gem "rspec-rails", "2.0.1"

And then run

bundle update rspec-rails

Release Notes

2.0.1 / 2010-10-15

full changelog

• Enhancements

  • Add option to not generate request spec (–skip-request-specs)

• Bug fixes

  • Updated the mock_[model] method generated in controller specs so it adds any stubs submitted each time it is called.
  • Fixed bug where view assigns weren’t making it to the view in view specs in Rails-3.0.1. (Emanuele Vicentini)

This marks the end of a year-long effort that improves RSpec in a number of ways, including modularity, cleaner code, and much better integration with Rails-3 than was possible before.

Docs, with a little bit of relish

In addition to the documentation available at all the places mentioned my earlier post, we’ve also got all of the Cucumber features posted to Justin Ko’s new Cucumber presentation app, relish.

http://relishapp.com/rspec

We’ll also have the RDoc up on http://rdoc.info in a day or so.

Thanks!

Big thanks to 80+ contributors who submitted patches for RSpec-2.0.0, including [1]:

Aan, Adam Walters, Akira Matsuda, Alex Crichton, Anderson Dias, Andre Arko, Andreas Neuhaus, Ashley Moran, Ben Armston, Ben Rady, Brasten Sager, Brian J Reath, Carlhuda, Chad Humphries, Charles Lowell, Chris Redinger, Chuck Remes, Corey Ehmke, Corey Haines, Dan Peterson, Dave Newman, David Genord II, David S. Kang, Ethan Gunderson, Gonçalo Silva, Greg Sterndale, Hans de Graaff, Iain Hecker, Jacques Crocker, Jean-Daniel Guyot, Jeff Ramnani, Jim Breen, Johan Kiviniemi, Josep Mª Bach, Josh Graham, Joshua Nichols, Kabari Hendrick, Kristian M, Lailson B, Len Smith, Leonardo Bessa, Les Hill, Luis Lavena, Marcin Kulik, Markus Schirp, Matt Remsik, Matt Yoho, Matthew Todd, Michael Niessner, Mike Gehard, Myron Marston, Nate Jackson, Neeraj Singh, Nestor Ovroy, Nick Ang, Nicolas Braem, Paul Rosania, Phil Smith, Postmodern, Prasad, Rob Sanheim, Roman Chernyatchik, Ryan Bigg, Ryan Briones, Sam Pohlenz, Scott Taylor, Shin-ichiro OGAWA, Thibaud Guillaume-Gentil, Tim Connor, Tim Harper, Tom Stuart, Vít Ondruch, Wincent Colaiuta, aslakhellesoy, eira, garren smith, grosser, hasimo, justinko, rup, speedmax, wycats

Extra special thanks go to:

• Chad Humphries for contributing his Micronaut gem which is the basis for rspec-core-2
• Yehuda Katz, Carl Lerche, and José Valim, for their assistance with getting rspec-rails-2 to take advantage of new APIs in Rails-3, and for shepherding patches to Rails that made it far simpler for testing extensions like rspec-rails to hook into Rails’ testing infrastructure. Their work here has significantly reduced the risk that Rails point-releases will break rspec-rails.
• Myron Marston for a wealth of thoughtful contributions including Cucumber features that we can all learn from
• Justin Ko for his direct contributions to rspec, and for relish, which makes executable documentation act more like documentation.

What’s next?

rspec-rails-2 for rails-2

There are a couple of projects floating around that support rspec-2 and rails-2. I haven’t had the chance to review any of these myself, but my hope is that we’ll have be an official rspec-2 for rails-2 gem in the coming months.

rspec-1 maintenance

rspec-1 will continue to get maintenance releases, but these will be restricted, primarily, to bug fixes. Any new features will go into rspec-2, and will likely not be back-ported.

[1] Contributor names were generated from the git commit logs.

I just released rspec-1.3.1 and rspec-rails-1.3.3.

These are mostly bug fixes that have been sitting around for all to long as I focused on rspec-2 (coming very soon).

Report issues for rspec[-rails]-1.x to https://rspec.lighthouseapp.com/projects/5645.

Docs:

http://rspec.info/
http://rdoc.info/gems/rspec/1.3.1/frames
http://rdoc.info/gems/rspec-rails/1.3.3/frames

Cheers, David

rspec-1.3.1 / 2010-10-09

• enhancements

  • Array =~ matcher works with subclasses of Array (Matthew Peychich & Pat Maddox)
  • config.suppress_deprecation_warnings!

• bug fixes

  • QuitBacktraceTweaker no longer eats all paths with ‘lib’ (Tim Harper - #912)
  • Fix delegation of stubbed values on superclass class-level methods. (Scott Taylor - #496 - #957)
  • Fix pending to work with ruby-1.9

• deprecations

  • share_as (will be removed from rspec-core-2.0)
  • simple_matcher (will be removed from rspec-core-2.0)

rspec-rails-1.3.3 / 2010-10-09

• enhancements

  • replace use of ‘returning’ with ‘tap’

• bug fixes

  • support message expectation on template.render with locals (Sergey Nebolsin). Closes #941.
  • helper instance variable no longer persists across examples (alex rothenberg). Closes #627.
  • mock_model stubs marked_for_destruction? (returns false).

See http://blog.davidchelimsky.net/2010/07/01/rspec-2-documentation for links to all sorts of documentation on rspec-2.

Plan is to release rspec-2.0.0 (final) within the next week, so please install, upgrade, etc, and report issues to:

http://github.com/rspec/rspec-core/issues
http://github.com/rspec/rspec-expectations/issues
http://github.com/rspec/rspec-mocks/issues
http://github.com/rspec/rspec-rails/issues

Many thinks to all of the contributors who got us here!

rspec-core-2.0.0.rc / 2010-10-05

full changelog

• Enhancements

  • implicitly require unknown formatters so you don’t have to require the file explicitly on the commmand line (Michael Grosser)
  • add –out/-o option to assign output target
  • added fail_fast configuration option to abort on first failure
  • support a Hash subject (its([:key]) { should == value }) (Josep M. Bach)

• Bug fixes

  • Explicitly require rspec version to fix broken rdoc task (Hans de Graaff)
  • Ignore backtrace lines that come from other languages, like Java or Javascript (Charles Lowell)
  • Rake task now does what is expected when setting (or not setting) fail_on_error and verbose
  • Fix bug in which before/after(:all) hooks were running on excluded nested groups (Myron Marston)
  • Fix before(:all) error handling so that it fails examples in nested groups, too (Myron Marston)

rspec-expectations-2.0.0.rc / 2010-10-05

full changelog

• Enhancements

  • require ‘rspec/expectations’ in a T::U or MiniUnit suite (Josep M. Bach)

• Bug fixes

  • change by 0 passes/fails correctly (Len Smith)
  • Add description to satisfy matcher

rspec-mocks-2.0.0.rc / 2010-10-05

full changelog

• Enhancements

  • support passing a block to an expecttation block (Nicolas Braem)
  • obj.should_receive(:msg) {|&block| … }

• Bug fixes

  • Fix YAML serialization of stub (Myron Marston)
  • Fix rdoc rake task (Hans de Graaff)

rspec-rails-2.0.0.rc / 2010-10-05

full changelog

• Enhancements
  • add –webrat-matchers flag to scaffold generator (for view specs)
  • separate ActiveModel and ActiveRecord APIs in mock_model and stub_model
  • ControllerExampleGroup uses controller as the implicit subject by default (Paul Rosania)

We’re getting very close to a 2.0 release candidate, so if you’re not already using rspec-2 (with or without rails-3), now is the time to start. I need your feedback, so from here on in I’ll be sending out announcements and release notes for each beta release.

As for rspec-2 with rails-2, there are a few efforts underway to make that work, but that will be in the form of a separate gem and our priority is getting rspec-2 out the door.

Please report issues or submit pull requests (yes, pull requests are fine now that github has integrated them so well with issues) to the appropriate repos:

• http://github.com/rspec/rspec-core/issues
• http://github.com/rspec/rspec-expectations/issues
• http://github.com/rspec/rspec-mocks/issues
• http://github.com/rspec/rspec-rails/issues

Here are release notes for each gem in this beta release, drawn from the nascent History.md files in each project.

rspec-core-2.0.0.beta.22 / 2010-09-12

full changelog

• Enhancements

  • removed at_exit hook
  • CTRL-C stops the run (almost) immediately
  • first it cleans things up by running the appropriate after(:all) and after(:suite) hooks
  • then it reports on any examples that have already run
  • cleaned up rake task
  • generate correct task under variety of conditions
  • options are more consistent
  • deprecated redundant options
  • run ‘bundle exec autotest’ when Gemfile is present
  • support ERB in .rspec options files (Justin Ko)
  • depend on bundler for development tasks (Myron Marston)
  • add example_group_finished to formatters and reporter (Roman Chernyatchik)

• Bug fixes

  • support paths with spaces when using autotest (Andreas Neuhaus)
  • fix module_exec with ruby 1.8.6 (Myron Marston)
  • remove context method from top-level
  • was conflicting with irb, for example
  • errors in before(:all) are now reported correctly (Chad Humphries)

• Removals

  • removed -o –options-file command line option
  • use ./.rspec and ~/.rspec

rspec-expectations-2.0.0.beta.22 / 2010-09-12

full changelog

• Enhancements

  • diffing improvements
  • diff multiline strings
  • don’t diff single line strings
  • don’t diff numbers (silly)
  • diff regexp + multiline string

• Bug fixes

  • should[_not] change now handles boolean values correctly

rspec-mocks-2.0.0.beta.22 / 2010-09-12

full changelog

• Bug fixes
  • fixed regression that broke obj.stub_chain(:a, :b => :c)
  • fixed regression that broke obj.stub_chain(:a, :b) { :c }
  • respond_to? always returns true when using as_null_object

2.0.0.beta.22 / 2010-09-12

full changelog

• Enhancements

  • autotest mapping improvements (Andreas Neuhaus)

• Bug fixes

  • delegate flunk to assertion delegate

I’m thrilled to announce that The RSpec Book has entered the production process!

For those of you unfamiliar with the publishing industry, as I was before this project, “has entered the production process” does not mean that it’s off to the printer. What it does mean is that it is currently being indexed so readers will be able to find the stuff they’re looking for. After indexing it will be copyedited (in which someone with better grammar and spelling than any of the authors possess makes the book more readable) and typeset, and then off to the printer.

If all goes to plan (yes, there actually is a plan!), books.should be_on_shelves in late September, early October.

That light at the end of the tunnel is, finally, not an oncoming train!

The Pragmatic Bookshelf has just released Beta-14 of The RSpec Book.

This is the first beta release since we made the rather ambitious decision to update the book for RSpec-2 and Rails-3, and includes updates to the tutorial in Part I of the book, as well as the first chapter in Part III: Code Examples.

We’re planning two more beta releases over the next couple of weeks. One to update the rest of Part III, and then a final beta release with Part V (the Rails section) updated to RSpec-2 and Rails-3.

What this means for the short run is that 1/2 of the beta book uses newer gem versions, while the rest uses the old versions. We thought for a long time about whether to delay this beta until it was all up to date, but decided in the end that beta readers had waited long enough—now that RSpec 2 and Rails 3 release candidates are just around the corner, we wanted to get this new content out as soon as we could. Keep in mind that this is only for a week or two, while we put the finishing touches on the book.

With that in mind, here is some information that will help you navigate the beta book:

Ruby 1.8.7

The code examples in the book were written using Ruby 1.8.7. Most of them, but not all, will work with 1.9.2-rc2.

Code for the updated chapters in beta-14

While we’re getting these last few beta releases out, the updated chapters all have red headers, like this:

The examples in these chapters work with the following gem versions:

rspec-2.0.0.beta.18
cucumber-0.8.5

Code for the rest of the chapters in beta-14

The chapters that have not been updated yet have gray headers, like this:

The examples in these chapters work with the following gem versions:

rspec-1.3.0
rspec-rails-1.3.2
rails-2.3.5
cucumber-0.6.2
cucumber-rails-0.2.4
database_cleaner-0.4.3
webrat-0.7.0
selenium-client-0.2.18

Reporting Errata

Technical errors in the updated chapters

We are now in the final phases of preparing the book for print. For those of you reading the beta book, we are very interested in technical errata in the updated chapters. If the behaviour of any examples in the updated chapters differs from what the book tells you to expect with the versions listed above, please report that to http://www.pragprog.com/titles/achbd/errata.

Copyedit issues

The book has not been through copyedit yet (that’s next), so please don’t worry about spelling, grammar, or phrasing. That will all be addressed by our very able copyeditor.

Typesetting issues

The book has not been formally typeset yet (that’s last), so please don’t worry about code examples that span page turns, or issues with syntax highlighting.

Other technical errors

If you find that the behaviour works differently with newer Ruby or gem versions than those listed above, please submit bug reports to the appropriate trackers:

• rspec-core (describe/it/etc)
• rspec-expectations (should/should_not + matchers)
• rspec-mocks
• rspec-rails
• cucumber

Some questions have come up since I posted about rspec-rails-2 generators and rake tasks requiring that rspec-rails be declared in the :development group in a Gemfile. Here are a few of them, paraphrased, with answers:

Why the change?

rspec-rails now uses a Railtie to expose the rake tasks and generators. Railties allow Rails extensions to register themselves with Rails without having to copy files into your app. This makes installation and, especially, upgrades much easier to manage for both maintainers and users.

Do I need rspec-rails in both :development and :test groups?

:development

We need rspec-rails in the :development group in order to expose the rake tasks and generators without having to type RAILS_ENV=test when we want to use them.

:test

Quite ironically, it turns out that we don’t need it in the :test group at all. That may change in the future, and I don’t see any harm in keeping it in the :test group as well, so I’ll probably keep it there in my apps.

Doesn’t that mean I’m loading rspec-rails and all of its dependencies in the :development environment?

No, and herein lies the benefit of using a Railtie for this.

When you declare a gem in a Gemfile, Bundler loads up a file with the same name as the gem, in our case rspec-rails.rb.

The generator configs are only invoked when running rails generate, which is when you want them. The require statement is only invoked when running rake, which is when you want it. If you’re not running rake or rails generate, then no other files from rspec-rails or any of its dependencies are loaded, unless you load them explicitly from elsewhere in your app.

Does this actually work? When I add rspec-rails to the :development group and run rails generate, I don’t see most of the rspec generators.

The only RSpec generator that is intended to be invoked directly is rspec:install, which you’ll still see. The others are invoked implicitly by Rails when you run the various Rails generators. e.g., if you run script/rails generate controller Widgets, the controller generator implicitly calls out to the rspec:controller generator to generate a WidgetsController spec.

Because these are intended to be implicit, Rails hides them from you in order to reduce the noise level.

OK, but now I see all of the test_unit generators. What’s up with those?

Because RSpec is the test framework of record, Rails doesn’t know to hide the test_unit generators. If you want to hide them, just add this to one of your config files:

Rails::Generators.hide_namespace("test_unit")

[Updated on 7//14]

Turns out that hide_namespaces doesn’t work for this use case. I’ve got an open ticket in the Rails tracker to address this, and I’ll updated this post again once it’s addressed.

As of rspec-rails-2.0.0.beta.17, generators and rake tasks are exposed through a Railtie. In order to see them when you run rails generate and rake -T, you need to include the rspec-rails gem in the :development group in your Gemfile.

group :development, :test do
  gem "rspec-rails", ">= 2.0.0.beta.17"
end

If you have a previous version of rspec-rails-2.0.0.beta installed, you should also remove these files:

lib/tasks/rspec.rake
config/initializers/rspec_generator.rb

RSpec-2 is getting close to a release candidate, and as the beta gems have been flowing a lot of questions have been coming in, especially about documentation. Here is some information that should help.

Source code

RSpec development has moved to the rspec account on github. There are five repositories at the moment:

• http://github.com/rspec/rspec
• http://github.com/rspec/rspec-core
• http://github.com/rspec/rspec-expectations
• http://github.com/rspec/rspec-mocks
• http://github.com/rspec/rspec-rails

rspec-rails depends on rspec, which depends, in turn, on the other three.

This structure has many benefits, but one cost is that the documentation, though plentiful, is a bit scattered.

READMEs

• http://github.com/rspec/rspec
• http://github.com/rspec/rspec-core
• http://github.com/rspec/rspec-expectations
• http://github.com/rspec/rspec-mocks
• http://github.com/rspec/rspec-rails

Upgrade Notes

• http://github.com/rspec/rspec-core/blob/master/Upgrade.markdown
• http://github.com/rspec/rspec-expectations/blob/master/Upgrade.markdown
• http://github.com/rspec/rspec-rails/blob/master/Upgrade.markdown

Cucumber features

Each of the repos has a growing set of Cucumber features. Some of the features have been added in after the fact, but many of the new features have been driven out using Cucumber. These are a great source of “How-To” information, and you know they’re up to date because they are executable documentation.

If you peruse these and are unable to find the information you’re looking for, or find any of the information incomplete or confusing, please, please, please submit a github issue (see Known Issues, below). Or, better yet, submit a patch!

• http://github.com/rspec/rspec-core/tree/master/features/
• http://github.com/rspec/rspec-expectations/tree/master/features/
• http://github.com/rspec/rspec-mocks/tree/master/features/
• http://github.com/rspec/rspec-rails/tree/master/features/

RDoc

The RDoc is arguably the weakest link here. Patches welcome!

• http://rdoc.info/projects/rspec/rspec-core
• http://rdoc.info/projects/rspec/rspec-expectations
• http://rdoc.info/projects/rspec/rspec-mocks
• http://rdoc.info/projects/rspec/rspec-rails

Known Issues

Issues for rspec-2 are being maintained on github.

• http://github.com/rspec/rspec-core/issues
• http://github.com/rspec/rspec-expectations/issues
• http://github.com/rspec/rspec-mocks/issues
• http://github.com/rspec/rspec-rails/issues

If you want to submit an issue and you’re not sure which tracker it belongs in, just pick the one you think is most appropriate. I’m more interested in getting the feedback then you knowing where to put the issue. I’ll move it to the right place if necessary.

Wikis

PLEASE NOTE: github wikis can be updated by anybody with a github account, and I don’t get any notification when wiki pages have changed. Most of the time, users add valuable information, but the structure is poor and always in flux, and there have been occasions in which the information was either misleading or simply inaccurate. The Cucumber features mentioned above, though currently incomplete, are a much better source for accurate documentation.

• http://wiki.github.com/rspec/rspec/
• http://wiki.github.com/rspec/rspec-core/
• http://wiki.github.com/rspec/rspec-expectations/
• http://wiki.github.com/rspec/rspec-mocks/
• http://wiki.github.com/rspec/rspec-rails/

The RSpec Book

The RSpec Book is being updated for RSpec-2 and Rails-3. There will still be references back to RSpec-1 and Rails-2 where things have changed, but the focus will be on the way forward. Once the rails-3 and rspec-2 release candidates are out, we’ll release one more updated PDF of the book for those in the beta program, and then off to the printer it goes. FINALLY!