RSpec 3 includes many breaking changes, but our hope is to make this the smoothest
major-version gem upgrade you've ever done. To assist with that process, we've developed
RSpec 2.99 in tandem with RSpec 3. Every breaking change in 3.0 hash a corresponding
deprecation to 2.99. Rather than just giving you a generic upgrade document that describes
all of the breaking changes (most of which affect very few users!), RSpec 2.99 gives you a
detailed upgrade checklist tailored to your project.
In addition, Yuji Nakayama has created Transpec -- an absolutely amazing tool that can
automatically upgrade most RSpec suites. We've tried it on a few projects and have been amazed at how well it works.
- Ensure your test suite is already green on whatever RSpec 2.x version you're already using.
- Install RSpec 2.99.
- Run your test suite and ensure it's still green. (It should be, but we may have made a mistake -- if it breaks anything, please report a bug!). Now would be a good time to commit.
- You'll notice a bunch of deprecation warnings printed off at the
end of the spec run. These may be truncated since we don't to
spam you with the same deprecation warning over and over again. To
get the full list of deprecations, you can pipe them into a file
by passing the
- If you want to understand all of what is being deprecated, it's a
good idea to read through the deprecation messages. In some cases,
you have choices -- such as continuing to use the
havecollection cardinality matchers via the extracted rspec-collection_matchers gem, or by rewriting the expectation expression to something like
gem install transpec(Note that this need not go into your
Gemfile: you run
transpecas a standalone executable outside the context of your bundle).
- Run transpec on your project. Check
transpec --helpor the README for a full list of options.
- Run the test suite (it should still be green but it's always good to check!) and commit.
- If there are any remaining deprecation warnings (transpec doesn't quite handle all of the warnings you may get), deal with them.
- Once you've got a deprecation-free test suite running against RSpec 2.99, you're ready to upgrade to RSpec 3. Install RSpec 3.
- Run your test suite. It should still be green. If anything fails, please open a Github issue -- we consider it a bug! Note that you may still get a few additional deprecation warnings on RSpec 3 that weren't present on 2.99. This is normal -- there are a few things we couldn't easily deprecate in 2.99 and remove in 3.0, so they trigger deprecations in 3.0 with the plan to remove them in RSpec 4.
- We recommend running
transpeca second time. There are some changes that transpec is only able to make when your project is on RSpec 3.
- Commit and enjoy using the latest RSpec release!
Last published over 7 years ago by myronmarston.