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 ½ 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.

1
2
3
4
5
6
7
8
9
10
11
12

module RSpec
  module Rails
    class Railtie < ::Rails::Railtie
      config.generators.integration_tool :rspec
      config.generators.test_framework   :rspec

      rake_tasks do
        load "rspec/rails/tasks/rspec.rake"
      end
    end
  end
end

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:

1

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!

View isolation is changing in rspec-rails-2. As of beta.14, the view template needs to exist, but the content of the template will not be evaluated. This still provides isolation from the content of the template and its dependencies, it just means the file has to be there, which means you have to create it.

Why this change?

rspec-rails-1 performed some serious gymnastics to isolate controller specs from views. As many rspec/rails users well know, all the monkey patching of Rails’ internals led to rspec-rails releases immediately following rails releases.

Thankfully, Rails 3 exposes very clean extension points and APIs that make it far simpler to get the most important part of this isolation: isolation from the content of the template.

Rails 3 Resolvers

Rails makes a number of decisions based on the existence or lack thereof of a given template on the file system. Rails 3 also supports custom resolvers that let you store view templates in a database, for example. Given the wide array of possibilities, it is not possible for RSpec to predict every way in which templates will be stored or accessed.

What RSpec can do, and does as of beta.14, is use the Rails machinery, or custom extensions that adhere to the Rails Resolver API, to find and load templates, and then stub out the content. Doing so requires much less code and, more importantly, much less invasive code. This increases the likelihood that new features in Rails will just work with rspec-rails as it is, and decreases the likelihood that changes to Rails’ internals will require rspec-rails to release updates with every new release of Rails.

When contributing to a git(hub)-hosted open source project, it is often recommended that you follow these steps:

• fork the repo
• make changes on a topic branch
• push the branch to your repo
• send a pull request or link to the commit from a ticket

I was recently asked whether the topic branch in step 2 was necessary. The answer is that it’s not really necessary, it just makes life easier for both the contributor and the maintainer. Here’s why.

When maintainers merge patches, they often modify commit messages: rewording for consistency in the commit logs, sign-off statements, etc. They’ll also sometimes change the actual content of the commit to fix typos, reorganize methods in a file, etc, etc.

In either case, the result is that the commit that gets merged to the mainline repo has a different sha1 than the commit you submitted. This means that when you go to merge the mainline master branch back into your master branch, you’ll run into conflicts. Then, if you resolve them, the HEAD of your master branch is not the same as the HEAD of the mainline master branch, so the next patch you submit off your master branch will likely not apply easily.

By keeping your patches on topic branches, you’re able to keep your master branch aligned with the mainline master branch. This makes it easier for you to submit more patches later. It also makes it more likely that your contributions will apply cleanly, which increases the likelihood that they’ll be accepted.

In RSpec-2, every example group and example has associated metadata, to which you can append arbitrary information. This allows you to slice and dice a spec suite in a variety of ways.

Adding arbitrary metadata

The describe and it methods, and their aliases, each accept a hash as the last argument before the block:

describe "something", :this => {:is => :arbitrary} do
it "does something", :and => "so is this" do
  # ...
end
end

filter_run

The keys in these hashes can be accessed in a number of ways via RSpec.configure. If, for example, you’re working on a specific example and don’t want to run the full suite, you can use the filter_run method on the configuration like this:

# in spec/spec_helper.rb
RSpec.configure do |c|
c.filter_run :focus => true
end

# in spec/any_spec.rb
describe "something" do
it "does something", :focus => true do
  # ....
end
end

Now if you run rspec spec, it will only run that one example, no matter how many others there are in the suite.

This works for examples and groups, so if you want to run all the examples in one group that you’re focusing on, but nothing else, you can do this:

RSpec.configure do |c|
c.filter_run :focus => true
end

describe "something", :focus => true do
it "does something" do
  # ....
end
it "does something else" do
  # ....
end
end

The rspec command would now run both of the examples in that group.

filter_run_excluding

This is the inverse of filter_run. It excludes any examples or groups that match the filter:

RSpec.configure do |c|
c.filter_run_excluding :slow => true
end

describe "something", :slow => true do
it "does something" do
  # ....
end
it "does something else" do
  # ....
end
end

The rspec command would now run all the other examples in the suite, but not these two.

NOTE: filter_run_excluding was added in beta.12, which was just released this morning.

lambda

You can filter on runtime conditions by assigning a lambda to a key. If your app is expected to behave differently in different versions of Ruby, you can use a lambda with filter_run_excluding like this:

RSpec.configure do |c|
c.filter_run_excluding :ruby => lambda {|version|
  !(RUBY_VERSION.to_s =~ /^#{version.to_s}/)
}
end

describe "something" do
it "does something", :ruby => 1.8 do
  # ....
end
it "does something", :ruby => 1.9 do
  # ....
end
end

This example comes directly from rspec-core’s own spec_helper.rb.

RSpec passes 1.8 and 1.9 to the lambda, which accepts it as the version block argument. If the lambda returns true, the example is excluded from the run (because we’re using filter_run_excluding). Now the first example will only run if the ruby version is 1.8. Similarly, the latter example only runs under 1.9.

(no) command line support (yet)

We plan to add some sort of command line API to access these filters, but we’re not sure yet what this is going to look like. There is an open issue in github issues for rspec-core . Please feel free to review and add any comments there.

[Updated on 17 March, 2010]

I just released rspec-2.0.0.beta.4 with support for autotest, among other enhancements. Autotest integration is going to be a bit different in rspec-2. We’re removing the autospec command, which did nothing but set an environment variable and call autotest.

In rspec-2, you’ll use the autotest command directly, but doing so requires a small bit of configuration. As of beta.4, you’ll have to do add this configuration manually. Just create an autotest directory in the root of your project, put the following statement in ./autotest/discover.rb:

Autotest.add_discovery { "rspec2" }

The final 2.0.0 release will include a generator (even for non-rails projects) that will add this for you.

We’ve started to do some preliminary work on rspec-2.0, which we plan to release before Rails-3 goes final. At that point, the rspec-rails-2.0 plugin/gem will only work with rspec >= 2.0 and rails >= 3.0.

We’re committed to making the upgrade from rspec-1.x to rspec-2.0 as seamless as possible for most users, but extenders are going to see some differences. This is why we’re going to take our time with alpha, beta, and candidate releases.

Here are some of the improvements you can expect:

Modularity

Following the Rails and Merb models, Rspec-2 will be broken up into component gems and a meta-gem that depends on them. Most users will still gem install rspec, and doing so will install the component gems.

We’ve broken rspec up into 4 repos in the rspec account on github:

• rspec => meta gem that depends on the others
• rspec-core => runner and output formatters
• rspec-expectations => should and matchers
• rspec-mocks => mocks and stubs

With separate component repos, you’ll be able to use rspec as you do today or mix and match components with other frameworks. This will also make it easier for contributors to contribute to the components they are interested in without worrying about other components.

New runner extracted from Micronaut

The rspec-core repository is a complete rewrite of the runner, which has been a big sore spot over the years for contributors and extenders. We extracted the runner from Micronaut, which is an Rspec-compatible framework written by Chad Humphries.

Micronaut has a simple and powerful metadata model, which allows us to easily slice and dice a spec suite in much the same way we do now with Cucumber using tags. It also helps to simplify rspec’s own specs (because you can access it from within an example).

Because we’re able to intercept examples before they are run, we’ll also be able to offer a clean extension API, allowing you to add structures like Merb’s given blocks without monkey patching. Less monkey patching == more maintainable.

Where we are today

While Micronaut runs the same specs that Rspec does, there are some different names for things, and there are some differences in the CLI as well. We’ve started to resolve some of the differences in rspec-core, but we have a way to go.

If you want to try it out and see what works and what doesn’t, you can either install the prerelease gems (2.0.0.a2 as of this writing):

[sudo] gem install rspec --prerelease

You can also grab the dev environment and have a look at the code. See the rspec-dev README for info.

Please do not start reporting issues yet as this will only slow us down.

There is a lot that works, but there is also a lot that doesn’t. Once we get to beta, we’ll be looking for feedback and contributions, but for now we just want to let you know where things are.

Rspec 2 uses Rspec as the root namespace and installs an rspec command instead of a spec command. Until we release 2.0.0 final, this will make it easy for you to keep things separate on your system and in your apps. Once we go final we’ll either alias the old names or release a separate backwards-compatibility wrapper gem that does this for you.

What’s next

We want to focus most of our efforts on rspec-2 at this point, so we don’t plan any new development on the rspec-1.x series. We’ll do bug-fix releases of rspec[-rails]-1.3, but no new features.

I’ll follow up with more information as it becomes clear. Look here for announcements about alpha and beta releases if you’re interested in trying it out early or getting involved.

With the beta release of Rails 3 just around the corner, we’re planning a 2.0 release of Rspec, with an rspec-rails-2.0 gem for rails-3.0.

Late last week and through the weekend, Engine Yard, Relevance and Obtiva sponsored a meeting with Yehuda Katz, Carl Lerche, Chad Humphries, and me. The four of us laid out some groundwork and made some good progress toward what promises to be be a very friendly world for Rspec and Rails users and extenders.

Thanks to David Heinemeier Hansson and the rest of the Rails core team for embracing agnosticism without compromising convention over configuration.

I’ll follow up with details as things shape up, but here is a quick synopsis:

Rails users

Whether or not you use Rspec, you’ll see improvements in some of the built-in assertions, and other testing facilities that ship with Rails.

Rspec-rails users

If you do use Rspec, you’ll see a new rspec-rails plugin/gem that hooks into new features of rails-3 like the new rails generators. You’ll also see support for Merb-style request specs that wrap Rails’ integration tests.

Test framework authors

Rails’ testing APIs will be decoupled from the Test::Unit and Minitest runners. For authors of new testing frameworks, this means that you’ll be able to include a module in your framework’s objects instead of having to subclass TestCase. This will make it much easier to experiment with new ideas in the context of Rails, which clearly exposes those ideas to a wider audience than otherwise.