Shoulda Matchers 2.8.0

Our popular gem for helping you write succinct tests for your validations and associations, Shoulda Matchers, continues to improve with the release of 2.8.0. This is the last release in the 2.x line, and we’ll be focusing on 3.0 next. We’ll talk more about that in a future post, but for now, let’s take a look at list of changes in this release.

Deprecations

We’ve been trying to align the matchers API more closely with APIs in Rails. In 2.7.0, we renamed ensure_inclusion_of to validate_inclusion_of, and ensure_exclusion_of to validation_inclusion_of. In 2.8.0 we’ve also renamed ensure_length_of to validate_length_of. You may continue to use the older names, but we’ll be removing them in 3.0.

In addition we’ve also made a few changes to set_the_flash and set_session. In Rails, flash and session have similar APIs, and so we are making their matcher counterparts similar, too. For this reason, we’ve renamed set_the_flash to set_flash, and we’ve also deprecated set_session(:foo) in favor of set_session[:foo]. These older usages will be removed in 3.0. Finally, to clean up the API, we are deprecating should set_session[:key].to(nil) to assert that a certain value in session is unset. You should change this syntax to should_not set_session[:key], as we will be changing the former syntax so that it passes only if the value is truly nil in 3.0.

Bug fixes

There are a whole host of bugs that we squashed in this release, but most notable are these:

• The gem now supports Rails 4.2.

  • The serialize matcher no longer emits a warning about serialized_attributes being deprecated. (#627)
  • allow_value, validate_numericality_of and validate_inclusion_of have been fixed so that they handle RangeErrors emitted from ActiveRecord 4.2. These exceptions arise whenever we attempt to set an attribute using a value that lies outside the range of the column (assuming the column is an integer). RangeError is now treated specially, failing the test instead of bubbling up as an error. (#634, #637, #642)

• We’ve fixed a long-standing (2-year!) bug with validate_uniqueness_of and scoped attributes. Specifically, if one of these scopes was a polymorphic *_type attribute, and the model had another validation on the same attribute, the matcher would fail with an error. (#203, #366, #592)

• delegate_method now works again with Shoulda Context. (#591)

• have_many + through is fixed so that when the association does not exist, and the matcher fails, it does not raise an error when producing the failure message. (#588)

• validate_inclusion_of + with_message is fixed so that it fails if given a message that does not match the message on the validation. (#598)

• route is fixed so that when controller and action are specified in hash notation (e.g. posts#show), route parameters such as id do not need to be specified as a string but may be specified as a number as well. (#602)

Features

Association matchers, validate_uniqueness_of, set_session, and delegate_method also gained some new abilities, which you can read about in the NEWS file.

Known issues

As we alluded to earlier, our next immediate focus will be 3.0. However, once this is shipped, we will turn our attention to the following issues:

• Fixing several Postgres-related bugs (#402, #521, #554, #587, #607, #639)
• Fixing validate_numericality_of so that it supports specifying a context with the on qualifier (#356, #358)

Thanks

Thank you to these fine contributors for their help on making Shoulda Matchers better:

• Aditya Kapoor
• Adrià Planas
• George Millo
• Ian Zabel
• Josh Kalderimis
• Ken Liu
• Luciano Sousa
• Matt Gibson
• Mauro George
• Peter Marsh
• Sean Devine
• Sean Doyle
• fervic

New site

Oh, and last but not least, Shoulda Matchers now has a new site, thanks to one of our amazing designers, Rachel Cope. So if you’re trying to convince a coworker to use the gem, now you know where to point them!