David Chelimsky

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

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!

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.

I’d like to welcome Chad Humphries to the Rspec Development Team.

Chad wrote an Rspec-compatible framework named Micronaut, which runs specs written for Rspec. With Chad on board, we’re replacing Rspec’s runner with Micronaut’s runner for rspec-2.0, which is already in progress and should be released with a new rspec-rails-2.0 plugin/gem in time for the Rails 3.0 release.

Check back here for more details over the coming days, but in the mean time:

Welcome, Chad!

Beta 10????? When the hell are we going to start chopping down some trees? Well, first, here’s what’s new in Beta 10 of The RSpec Book:

Automating the Browser with Webrat and Selenium

This new chapter from Bryan Helmkamp shows you how to drive Cucumber scenarios right through your browser using Webrat and Selenium. You’ll type a single command and watch a browser fire up and walk through each scenario step by step right before your very eyes, and then see a standard Cucumber report in the shell. It’s a sight to behold, and a great way to drive out behaviour that requires JavaScript.

And now, for your reading pleasure … Read the rest of this entry »