David Chelimsky

Changes in rspec-core and rspec-rails are listed below. There are no changes to rspec-mocks and rspec-expectations for this release.

rspec-core-2.4.0 / 2011-01-02

full changelog

• Enhancements

  • start the debugger on -d so the stack trace is visible when it stops (Clifford Heath)
  • apply hook filtering to examples as well as groups (Myron Marston)
  • support multiple formatters, each with their own output
  • show exception classes in failure messages unless they come from RSpec matchers or message expectations
  • before(:all) { pending } sets all examples to pending

• Bug fixes

  • fix bug due to change in behavior of reject in Ruby 1.9.3-dev (Shota Fukumori)
  • fix bug when running in jruby: be explicit about passing block to super (John Firebaugh)
  • rake task doesn’t choke on paths with quotes (Janmejay Singh)
  • restore –options option from rspec-1
  • require ‘ostruct’ to fix bug with its([key]) (Kim Burgestrand)
  • –configure option generates .rspec file instead of autotest/discover.rb

rspec-rails-2.4.0 / 2011-01-02

full changelog

• Enhancements

  • include ApplicationHelper in helper object in helper specs
  • include request spec extensions in files in spec/integration
  • include controller spec extensions in groups that use :type => :controller
  • same for :model, :view, :helper, :mailer, :request, :routing

• Bug fixes

  • restore global config.render_views so you only need to say it once
  • support overriding render_views in nested groups
  • matchers that delegate to Rails’ assertions capture ActiveSupport::TestCase::Assertion (so they work properly now with should_not in Ruby 1.8.7 and 1.9.1)

• Deprecations

  • include_self_when_dir_matches

full changelog

• Bug fixes
  • send debugger warning message to $stdout if RSpec.configuration.error_stream has not been defined yet.
  • HTML Formatter finally properly displays nested groups (Jarmo Pertman)
  • eliminate some warnings when running RSpec’s own suite (Jarmo Pertman)

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#

rspec-core-2.1.0 / 2010-11-07

Cucumber features
RDoc # will be generated by 2010-11-08
full changelog

• Enhancments

  • Add skip_bundler option to rake task to tell rake task to ignore the presence of a Gemfile (jfelchner)
  • Add gemfile option to rake task to tell rake task what Gemfile to look for (defaults to ‘Gemfile’)
  • Allow passing caller trace into Metadata to support extensions (Glenn Vanderburg)
  • Add deprecation warning for Spec::Runner.configure to aid upgrade from RSpec-1
  • Add deprecated Spec::Rake::SpecTask to aid upgrade from RSpec-1
  • Add ‘autospec’ command with helpful message to aid upgrade from RSpec-1
  • Add support for filtering with tags on CLI (Lailson Bandeira)
  • Add a helpful message about RUBYOPT when require fails in bin/rspec (slyphon)
  • Add “-Ilib” to the default rcov options (Tianyi Cui)
  • Make the expectation framework configurable (default rspec, of course) (Justin Ko)
  • Add ‘pending’ to be conditional (Myron Marston)
  • Add explicit support for :if and :unless as metadata keys for conditional run of examples (Myron Marston)
  • Add –fail-fast command line option (Jeff Kreeftmeijer)

• Bug fixes

  • Eliminate stack overflow with “subject { self }”
  • Require ‘rspec/core’ in the Raketask (ensures it required when running rcov)

rspec-expectations-2.1.0 / 2010-11-07

Cucumber features
RDoc # will be generated by 2010-11-08
full changelog

• Enhancements

  • be_within(delta).of(expected) matcher (Myron Marston)
  • Lots of new Cucumber features (Myron Marston)
  • Raise error if you try “should != expected” on Ruby-1.9 (Myron Marston)
  • Improved failure messages from throw_symbol (Myron Marston)

• Bug fixes

  • Eliminate hard dependency on RSpec::Core (Myron Marston)
  • have_matcher - use pluralize only when ActiveSupport inflections are indeed defined (Josep M Bach)
  • throw_symbol matcher no longer swallows exceptions (Myron Marston)
  • fix matcher chaining to avoid name collisions (Myron Marston)

rspec-mocks-2.1.0 / 2010-11-07

Cucumber features
RDoc # will be generated by 2010-11-08
full changelog

• Bug fixes
  • Fix serialization of stubbed object (Josep M Bach)

rspec-rails-2.1.0 / 2010-11-07

Cucumber features
RDoc # will be generated by 2010-11-08
full changelog

• Enhancements

  • Move errors_on to ActiveModel to support other AM-compliant ORMs

• Bug fixes

  • Check for presence of ActiveRecord instead of checking Rails config (gets rspec out of the way of multiple ORMs in the same app)

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

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)