David Chelimsky

rspec-core-2.5.1

full changelog

This release breaks compatibility with rspec/autotest/bundler integration, but does so in order to greatly simplify it.

With the release of rspec-core-2.5.1, if you want the generated autotest command to include bundle exec, require Autotest’s bundler plugin in a .autotest file in the project’s root directory or in your home directory:

require "autotest/bundler"

Now you can just type ‘autotest’ on the commmand line and it will work as you expect.

If you don’t want ‘bundle exec’, there is nothing you have to do.

rspec-2.5 is a minor upgrade, and is fully backward compatible with rspec-2.4. It includes several bug fixes, enhancements, and one deprecation. See the changelog below for details.

We had a little glitch publishing the docs to http://relishapp.com/rspec, so the 2.5 docs won’t be up for another day or two, so I’ll detail the noticable differences here.

Autotest/Bundler integration

UPDATE: the –skip-bundler option does not work, and is removed from rspec-core-2.5.1. See the post on the 2.5.1 release for more information.

autotest -- --skip-bundler

Autotest ignores everything after the initial --, so RSpec’s Autotest extension handles the --skip-bundler option.

Autotest’s bundler plugin

Autotest ships with a plugin for bundler. Just add the following to a .autotest file in the project’s root directory, or your home directory:

require 'autotest/bundler'

This prefixes the generated shell command with ‘bundle exec’.

UPDATE: The implicit detection of Gemfile is removed from rspec-core-2.5.1. See the post on the 2.5.1 release for more information.

Given that Autotest has its own way of dealing with Bundler (see above), we deprecated the implicit assumption that Gemfile means “use bundler”. You’ll see a deprecation notice if you are relying on that, but it still works. It’s just a deprecation warning. To silence the warning, either use the --skip-bundler option or Autotest’s bundler plugin, described above.

HTML Formatter

The HTML formatter now has a set of checkboxes in the header that allow you to filter what you’re looking at:

to not, or not to not

Are you the sort of person for whom “expect this block of code to not raise an error” is like nails on chalkboard? If so, relief has arrived. You may now type either of the following, and RSpec will happily service you:

expect { ... }.to_not raise_error
expect { ... }.not_to raise_error

Changelog

rspec-core-2.5.0

full changelog

• Enhancements

  • Autotest::Rspec2 parses command line args passed to autotest after ‘–’
  • –skip-bundler option for autotest command
  • Autotest regexp fixes (Jon Rowe)
  • Add filters to html and textmate formatters (Daniel Quimper)
  • Explicit passing of block (need for JRuby 1.6) (John Firebaugh)

• Bug fixes

  • fix dom IDs in HTML formatter (Brian Faherty)
  • fix bug with –drb + formatters when not running in drb
  • include –tag options in drb args (monocle)
  • fix regression so now SPEC_OPTS take precedence over CLI options again (Roman Chernyatchik)
  • only call its(:attribute) once (failing example from Brian Dunn)
  • fix bizarre bug where rspec would hang after String.alias :to_int :to_i (Damian Nurzynski)

• Deprecations

  • implicit inclusion of ‘bundle exec’ when Gemfile present (use autotest’s bundler plugin instead)

rspec-expectations-2.5.0

full changelog

• Enhancements

  • should exist works with exist? or exists? (Myron Marston)
  • expect { ... }.not_to do_something (in addition to to_not)

• Documentation

  • improved docs for raise_error matcher (James Almond)

rspec-mocks-2.5.0

full changelog

• Bug fixes
  • message expectation counts now work in combination with a stub (Damian Nurzynski)
  • fix failure message when message received with incorrect args (Josep M. Bach)

rspec-rails-2.5.0

full changelog

• Enhancements

  • use index_helper instead of table_name when generating specs (Reza Primardiansyah)

• Bug fixes

  • fixed bug in which render_views in a nested group set the value in its parent group.
  • only include MailerExampleGroup when it is defiend (Steve Sloan)
  • mock_model.as_null_object.attribute.blank? returns false (Randy Schmidt)
  • fix typo in request specs (Paco Guzman)

rspec-core-2.3.0 / 2010-12-12

full changelog

• Enhancements

  • tell autotest to use “rspec2″ if it sees a .rspec file in the project’s root directory
    • replaces the need for ./autotest/discover.rb, which will not work with all versions of ZenTest and/or autotest
  • config.expect_with
    • :rspec # => rspec/expectations
    • :stdlib # => test/unit/assertions
    • :rspec, :stdlib # => both

• Bug fixes

  • fix dev Gemfile to work on non-mac-os machines (Lake Denman)
  • ensure explicit subject is only eval’d once (Laszlo Bacsi)

rspec-expectations-2.3.0 / 2010-12-12

full changelog

• Enhancements
  • diff strings when include matcher fails (Mike Sassak)

rspec-mocks-2.3.0 / 2010-12-12

full changelog

• Bug fixes
  • Fix our Marshal extension so that it does not interfere with objects that have their own @mock_proxy instance variable. (Myron Marston)

rspec-rails-2.3.0 / 2010-12-12

full changelog

• Changes
  • Generator no longer generates autotest/autodiscover.rb, as it is no longer needed (as of rspec-core-2.3.0)

rspec-rails-2.2.1 / 2010-12-01

full changelog

• Bug fixes

  • Depend on railties, activesupport, and actionpack instead of rails (Piotr Solnica)
  • Got webrat integration working properly across different types of specs

• Deprecations

  • –webrat-matchers flag for generators is deprecated. use –webrat instead.

2.2.1 / 2010-11-28

full changelog

• Bug fixes
  • alias_method instead of override Kernel#method_missing (John Wilger)
  • changed –autotest to –tty in generated command (MIKAMI Yoshiyuki)
  • revert change to debugger (had introduced conflict with Rails)
  • also restored –debugger/-debug option

rspec-core-2.2.0

full changelog

• Deprecations/changes

  • –debug/-d on command line is deprecated and now has no effect
  • win32console is now ignored; Windows users must use ANSICON for color support (Bosko Ivanisevic)

• Enhancements

  • Raise exception with helpful message when rspec-1 is loaded alongside rspec-2 (Justin Ko)
  • debugger statements just work as long as ruby-debug is installed
  • otherwise you get warned, but not fired
  • Expose example.metadata in around hooks
  • Performance improvments (see Upgrade.markdown)

• Bug fixes

  • Make sure –fail-fast makes it across drb
  • Pass -Ilib:spec to rcov

rspec-mocks-2.2.0

full changelog

• Enhancements

  • Added “rspec/mocks/standalone” for exploring the rspec-mocks in irb.

• Bug fix

  • Eliminate warning on splat args without parens (Gioele Barabucci)
  • Fix bug where obj.should_receive(:foo).with(stub.as_null_object) would
    pass with a false positive.

rspec-rails-2.2.0

full changelog

• Enhancements

  • Added stub_template in view specs

• Bug fixes

  • Properly include helpers in views (Jonathan del Strother)
  • Fix bug in which method missing led to a stack overflow
  • Fix stack overflow in request specs with open_session
  • Fix stack overflow in any spec when method_missing was invoked
  • Add gem dependency on rails ~> 3.0.0 (ensures bundler won’t install rspec-rails-2 with rails-2 apps).

One question that comes up on the rspec-users mailing list / google group is: “How do I specify modules that get mixed into other modules and classes?”

This is a great question and, naturally, leads to a wide variety of answers depending on context. I’m going to approach this generally, and explain my viewpoint about it, but keep in mind that context is everything, and YMMV. That said:

In theory

With a tool like RSpec, the goal is to specify responsibilities of objects from the perspective of their consumers. Consider this structure:

module M
end
 
class C
 include M
end

If module M is included in class C, consumers of class C have no reason to know that module M is involved. They just care about the behaviour. Same is true of classes A, B, and D, if they each include module M. Keeping in mind that each host class/module/object (those that include or extend M) can override any of the behaviour of M, each host should be specified independently.

Additionally, if module M enforces some rule, like host objects (i.e. classes and modules that include or extend M) must implement method F, then that responsibility belongs to M, and should be specified in the context of M, not any of its host classes/objects. These rules can be further broken down into rules enforced at mix-in time and rules enforced at runtime.

So we’re interested in specifying two fundamentally different things

• the behaviour of each class/object that mixes in M in response to events triggered by their consumers
• the behaviour of M in response to being mixed-in

In practice

Specifying the behaviour of a module in response to being mixed in

Imagine we are developing a module that exposes a bunch of methods related to a person’s age: can_vote?, can_drink?, etc. For this to work, the host object needs to supply the birthdate of the person in question. These sorts of requirements are often documented for us by library providers, but less often required programatically. It would be nice to provide a clear message to the developer when

For this, I’ll typically mix M into anonymous classes and objects and specify what happens:

describe AgeBasedApprovable do
  it "requires host object to provide a 'birthdate' method" do
    host = Object.new
    expect do
      host.extend(AgeBasedApprovable)
    end.to raise_error(/Objects that extend AgeBasedApprovable must provide a 'birthdate' method/)
  end
end

Specifying the behaviour of host classes/objects

For this, I’ve used a combination of shared example groups and custom macros in the past, but the macros are not necessary any longer. Thanks to some lively discussion [1-5], and code from Wincent Colaiuta, Ashley Moran and Myron Marston, shared example groups just got awesome in rspec-2.0! They can now be parameterized and/or customized in three different ways. The biggest change came from having it_should_behave_like (and its new alias, it_behaves_like), generate a nested example group instead of mixing a module directly into the host group. This means that this:

shared_examples_for M do
  it "does something" do
    # ....
  end
end
 
describe C do
  it_behaves_like M
end

… is equivalent to this:

describe C do
  context "behaves like M" do 
    it "does something" do
      # ....
    end
  end
end

In rspec-1, shared groups are modules that get mixed into the host group, which means material defined in the shared group can impact the host group in surprising ways. With this new structure in rspec-2, the nested group is a completely separate group, and the combination of sharing behaviour (through inheritance) and isolating behaviour (through encapsulation) provides power we never had before in RSpec.

Customizing shared example groups

Here are three techniques for customizing shared groups:

Parameterization

describe Host do
  it_should_behave_like M, Host.new
end

Here, the result of Host.new is passed to the shared group as a block parameter, making that value available at the group level (each example group is a class), and the instance level (each example runs in an instance of that class). So …

shared_examples_for M do |host|
  it "can access #{host} in the docstring" do
    host.do_something # it can access the host _in_ the example
  end
end

Methods defined in host group

describe Host do
  let(:foo) { Host.new }
  it_should_behave_like M
end

In this case, the foo() method defined by let() is inherited by the generated nested group, and available within any of the examples defined in the shared group.

shared_examples_for M do
  it "does something" do
    foo
  end
end

NOTE that instance methods that are inherited like this are not available in the class scope of the generated example group, and are therefore not available for use in docstings:

shared_examples_for M do
  it "does some #{foo}" do # this would raise an error
    # ...
  end
end

Methods defined in an extension block

describe Host do
  it_should_behave_like M do
    let(:foo) { Host.new }
  end
end

The block passed to it_should_behave_like() is eval’d after the shared group is eval’d, allowing you to define default implementations of methods in the shared group. This means we can define groups that programmatically enforce rules for the host groups. For example:

shared_examples_for M do
  def foo
    raise "Groups that include shared examples for M must provide a foo method"
  end
 
  it "does something needing foo" do
    foo
  end
end

Now library authors can now ship shared groups that will programmatically instruct end users how to use them!

[1] http://github.com/rspec/rspec-core/issues/issue/71
[2] http://github.com/rspec/rspec-core/issues/issue/74
[3] http://groups.google.com/group/rspec/browse_thread/thread/f5620df1c42874bf#
[4] http://groups.google.com/group/rspec/browse_thread/thread/16d553ee2e51ccbd#
[5] http://groups.google.com/group/rspec/browse_thread/thread/a23d5fb84a31f11e#

This is primarily a bug-fix release for rspec-core:

rspec-core-2.0.1

full changelog

• Bug fixes
  • restore color when using spork + autotest
  • Pending examples without docstrings render the correct message (Josep M. Bach)
  • Fixed bug where a failure in a spec file ending in anything but _spec.rb would fail in a confusing way.
  • Support backtrace lines from erb templates in html formatter (Alex Crichton)

rspec-expectations-2.0.1

full changelog

• Enhancements
  • Make dependencies on other rspec gems consistent across gems

rspec-mocks-2.0.1

full changelog

• Enhancements
  • Make dependencies on other rspec gems consistent across gems

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.

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)