# 3.1.2
### Deprecations
* This is the **last version** that supports Rails 4.0 and 4.1 and Ruby 2.0 and 2.1.
### Bug fixes
* When the `permit` matcher was used without `#on`, the controller did not use
`params#require`, the params object was duplicated, and the matcher did not
recognize the `#permit` call inside the controller. This behavior happened
because the matcher overwrote double registries with the same parameter hash
whenever ActionController::Parameters was instantiated.
* *Commit: [44c019]*
* *Issue: [#899]*
* *Pull request: [#902]*
# 3.1.1
### Bug fixes
* Some matchers make use of ActiveSupport's `in?` method, but do not include the
file where this is defined in ActiveSupport. This causes problems with
projects using shoulda-matchers that do not include all of ActiveSupport by
default. To fix this, replace `in?` with Ruby's builtin `include?`.
* *Pull request: [#879]*
* `validate_uniqueness_of` works by creating a record if it doesn't exist, and
then testing against a new record with various attributes set that are equal
to (or different than) corresponding attributes in the existing record. In
3.1.0 a change was made whereby when the uniqueness matcher is given a new
record and creates an existing record out of it, it ensures that the record is
valid before continuing on. This created a problem because if the subject,
before it was saved, was empty and therefore in an invalid state, it could not
effectively be saved. While ideally this should be enforced, doing so would be
a backward-incompatible change, so this behavior has been rolled back.
([#880], [#884], [#885])
* *Commit: [45de869]*
* *Issues: [#880], [#884], [#885]*
* Fix an issue with `validate_uniqueness_of` + `scoped_to` when used against a
model where the attribute has multiple uniqueness validations and each
validation has a different set of scopes. In this case, a test written for the
first validation (and its scopes) would pass, but tests for the other
validations (and their scopes) would not, as the matcher only considered the
first set of scopes as the *actual* set of scopes.
* *Commit: [28bd9a1]*
* *Issues: [#830]*
### Improvements
* Update `validate_uniqueness_of` so that if an existing record fails to be
created because a column is non-nullable and was not filled in, raise an
ExistingRecordInvalid exception with details on how to fix the test.
* *Commit: [78ccfc5]*
[#879]: https://github.com/thoughtbot/shoulda-matchers/issues/879
[45de869]: 45de869848
[#880]: https://github.com/thoughtbot/shoulda-matchers/issues/880
[#884]: https://github.com/thoughtbot/shoulda-matchers/issues/884
[#885]: https://github.com/thoughtbot/shoulda-matchers/issues/885
[78ccfc5]: 78ccfc50b5
[28bd9a1]: 28bd9a10c7
[#830]: https://github.com/thoughtbot/shoulda-matchers/issues/830
# 3.1.0
### Bug fixes
* Update `validate_numericality_of` so that submatchers are applied lazily
instead of immediately. Previously, qualifiers were order-dependent, meaning
that if you used `strict` before you used, say, `odd`, then `strict` wouldn't
actually apply to `odd`. Now the order that you specify qualifiers doesn't
matter.
* *Source: [6c67a5e]*
* Fix `allow_value` so that it does not raise an AttributeChangedValueError
(formerly CouldNotSetAttributeError) when used against an attribute that is an
enum in an ActiveRecord model.
* *Source: [9e8603e]*
* Add a `ignoring_interference_by_writer` qualifier to all matchers, not just
`allow_value`. *This is enabled by default, which means that you should never
get a CouldNotSetAttributeError again.* (You may get some more information if
a test fails, however.)
* *Source: [1189934], [5532f43]*
* *Fixes: [#786], [#799], [#801], [#804], [#817], [#841], [#849], [#872],
[#873], and [#874]*
* Fix `validate_numericality_of` so that it does not blow up when used against
a virtual attribute defined in an ActiveRecord model (that is, an attribute
that is not present in the database but is defined using `attr_accessor`).
* *Source: [#822]*
* Update `validate_numericality_of` so that it no longer raises an
IneffectiveTestError if used against a numeric column.
* *Source: [5ed0362]*
* *Fixes: [#832]*
[6c67a5e]: 6c67a5eb0d
[9e8603e]: 9e8603eb74
[1189934]: 1189934806
[5532f43]: 5532f4359a
[#786]: https://github.com/thoughtbot/shoulda-matchers/issues/786
[#799]: https://github.com/thoughtbot/shoulda-matchers/issues/799
[#801]: https://github.com/thoughtbot/shoulda-matchers/issues/801
[#804]: https://github.com/thoughtbot/shoulda-matchers/issues/804
[#817]: https://github.com/thoughtbot/shoulda-matchers/issues/817
[#841]: https://github.com/thoughtbot/shoulda-matchers/issues/841
[#849]: https://github.com/thoughtbot/shoulda-matchers/issues/849
[#872]: https://github.com/thoughtbot/shoulda-matchers/issues/872
[#873]: https://github.com/thoughtbot/shoulda-matchers/issues/873
[#874]: https://github.com/thoughtbot/shoulda-matchers/issues/874
[#822]: https://github.com/thoughtbot/shoulda-matchers/pull/822
[5ed0362]: 5ed0362419
[#832]: https://github.com/thoughtbot/shoulda-matchers/issues/832
### Features
* Add a new qualifier, `ignoring_case_sensitivity`, to `validate_uniqueness_of`.
This provides a way to test uniqueness of an attribute whose case is
normalized, either in a custom writer method for that attribute, or in a
custom `before_validation` callback.
* *Source: [#840]*
* *Fixes: [#836]*
[#840]: https://github.com/thoughtbot/shoulda-matchers/pull/840
[#836]: https://github.com/thoughtbot/shoulda-matchers/issues/836
### Improvements
* Improve failure messages and descriptions of all matchers across the board so
that it is easier to understand what the matcher was doing when it failed.
(You'll see a huge difference in the output of the numericality and uniqueness
matchers in particular.)
* Matchers now raise an error if any attributes that the matcher is attempting
to set do not exist on the model.
* *Source: [2962112]*
* Update `validate_numericality_of` so that it doesn't always run all of the
submatchers, but stops on the first one that fails. Since failure messages
now contain information as to what value the matcher set on the attribute when
it failed, this change guarantees that the correct value will be shown.
* *Source: [8e24a6e]*
* Continue to detect if attributes change incoming values, but now instead of
immediately seeing a CouldNotSetAttributeError, you will only be informed
about it if the test you've written fails.
* *Source: [1189934]*
* Add an additional check to `define_enum_for` to ensure that the column that
underlies the enum attribute you're testing is an integer column.
* *Source: [68dd70a]*
* Add a test for `validate_numericality_of` so that it officially supports money
columns.
* *Source: [a559713]*
* *Refs: [#841]*
[2962112]: 2962112114
[8e24a6e]: 8e24a6e9b2
[68dd70a]: 68dd70a23d
[a559713]: a559713f96
# 3.0.1
### Bug fixes
* Fix `validate_inclusion_of` + `in_array` when used against a date or datetime
column/attribute so that it does not raise a CouldNotSetAttributeError.
([#783], [8fa97b4])
* Fix `validate_numericality_of` when used against a numeric column so that it
no longer raises a CouldNotSetAttributeError if the matcher has been qualified
in any way (`only_integer`, `greater_than`, `odd`, etc.). ([#784], [#812])
### Improvements
* `validate_uniqueness_of` now raises a NonCaseSwappableValueError if the value
the matcher is using to test uniqueness cannot be case-swapped -- in other
words, if it doesn't contain any alpha characters. When this is the case, the
matcher cannot work effectively. ([#789], [ada9bd3])
[#783]: https://github.com/thoughtbot/shoulda-matchers/pull/783
[8fa97b4]: 8fa97b4ff3
[#784]: https://github.com/thoughtbot/shoulda-matchers/pull/784
[#789]: https://github.com/thoughtbot/shoulda-matchers/pull/789
[ada9bd3]: ada9bd3a1b
[#812]: https://github.com/thoughtbot/shoulda-matchers/pull/812
# 3.0.0
### Backward-incompatible changes
* We've dropped support for Rails 3.x, Ruby 1.9.2, and Ruby 1.9.3, and RSpec 2.
All of these have been end-of-lifed. ([a4045a1], [b7fe87a], [32c0e62])
* The gem no longer detects the test framework you're using or mixes itself into
that framework automatically. [History][no-auto-integration-1] has
[shown][no-auto-integration-2] that performing any kind of detection is prone
to bugs and more complicated than it should be.
Here are the updated instructions:
* You no longer need to say `require: false` in your Gemfile; you can
include the gem as normal.
* You'll need to add the following somewhere in your `rails_helper` (for
RSpec) or `test_helper` (for Minitest / Test::Unit):
``` ruby
Shoulda::Matchers.configure do |config|
config.integrate do |with|
# Choose a test framework:
with.test_framework :rspec
with.test_framework :minitest
with.test_framework :minitest_4
with.test_framework :test_unit
# Choose one or more libraries:
with.library :active_record
with.library :active_model
with.library :action_controller
# Or, choose the following (which implies all of the above):
with.library :rails
end
end
```
([1900071])
* Previously, under RSpec, all of the matchers were mixed into all of the
example groups. This created a problem because some gems, such as
[active_model_serializers-matchers], provide matchers that share the same
name as some of our own matchers. Now, matchers are only mixed into whichever
example group they belong to:
* ActiveModel and ActiveRecord matchers are available only in model example
groups.
* ActionController matchers are available only in controller example groups.
* The `route` matcher is available only in routing example groups.
([af98a23], [8cf449b])
* There are two changes to `allow_value`:
* The negative form of `allow_value` has been changed so that instead of
asserting that any of the given values is an invalid value (allowing good
values to pass through), assert that *all* values are invalid values
(allowing good values not to pass through). This means that this test which
formerly passed will now fail:
``` ruby
expect(record).not_to allow_value('good value', *bad_values)
```
([19ce8a6])
* `allow_value` now raises a CouldNotSetAttributeError if in setting the
attribute, the value of the attribute from reading the attribute back is
different from the one used to set it.
This would happen if the writer method for that attribute has custom logic
to ignore certain incoming values or change them in any way. Here are three
examples we've seen:
* You're attempting to assert that an attribute should not allow nil, yet
the attribute's writer method contains a conditional to do nothing if
the attribute is set to nil:
``` ruby
class Foo
include ActiveModel::Model
attr_reader :bar
def bar=(value)
return if value.nil?
@bar = value
end
end
describe Foo do
it do
foo = Foo.new
foo.bar = "baz"
# This will raise a CouldNotSetAttributeError since `foo.bar` is now "123"
expect(foo).not_to allow_value(nil).for(:bar)
end
end
```
* You're attempting to assert that an numeric attribute should not allow a
string that contains non-numeric characters, yet the writer method for
that attribute strips out non-numeric characters:
``` ruby
class Foo
include ActiveModel::Model
attr_reader :bar
def bar=(value)
@bar = value.gsub(/\D+/, '')
end
end
describe Foo do
it do
foo = Foo.new
# This will raise a CouldNotSetAttributeError since `foo.bar` is now "123"
expect(foo).not_to allow_value("abc123").for(:bar)
end
end
```
* You're passing a value to `allow_value` that the model typecasts into
another value:
``` ruby
describe Foo do
# Assume that `attr` is a string
# This will raise a CouldNotSetAttributeError since `attr` typecasts `[]` to `"[]"`
it { should_not allow_value([]).for(:attr) }
end
```
With all of these failing examples, why are we making this change? We want
to guard you (as the developer) from writing a test that you think acts one
way but actually acts a different way, as this could lead to a confusing
false positive or negative.
If you understand the problem and wish to override this behavior so that
you do not get a CouldNotSetAttributeError, you can add the
`ignoring_interference_by_writer` qualifier like so. Note that this will not
always cause the test to pass.
``` ruby
it { should_not allow_value([]).for(:attr).ignoring_interference_by_writer }
```
([9d9dc4e])
* `validate_uniqueness_of` is now properly case-sensitive by default, to match
the default behavior of the validation itself. This is a backward-incompatible
change because this test which incorrectly passed before will now fail:
``` ruby
class Product < ActiveRecord::Base
validates_uniqueness_of :name, case_sensitive: false
end
describe Product do
it { is_expected.to validate_uniqueness_of(:name) }
end
```
([57a1922])
* `ensure_inclusion_of`, `ensure_exclusion_of`, and `ensure_length_of` have been
removed in favor of their `validate_*` counterparts. ([55c8d09])
* `set_the_flash` and `set_session` have been changed to more closely align with
each other:
* `set_the_flash` has been removed in favor of `set_flash`. ([801f2c7])
* `set_session('foo')` is no longer valid syntax, please use
`set_session['foo']` instead. ([535fe05])
* `set_session['key'].to(nil)` will no longer pass when the key in question
has not been set yet. ([535fe05])
* Change `set_flash` so that `set_flash[:foo].now` is no longer valid syntax.
You'll want to use `set_flash.now[:foo]` instead. This was changed in order to
more closely align with how `flash.now` works when used in a controller.
([#755], [#752])
* Change behavior of `validate_uniqueness_of` when the matcher is not
qualified with any scopes, but your validation is. Previously the following
test would pass when it now fails:
``` ruby
class Post < ActiveRecord::Base
validate :slug, uniqueness: { scope: :user_id }
end
describe Post do
it { should validate_uniqueness_of(:slug) }
end
```
([6ac7b81])
[active_model_serializers-matchers]: https://github.com/adambarber/active_model_serializers-matchers
[no-auto-integration-1]: 049080c673
[no-auto-integration-2]: https://github.com/rr/rr/issues/29
[1900071]: 190007155e
[b7fe87a]: b7fe87ae91
[a4045a1]: a4045a1f9b
[57a1922]: 57a19228b6
[19ce8a6]: 19c38a642a
[eaaa2d8]: eaaa2d83e5
[55c8d09]: 55c8d09bf2
[801f2c7]: 801f2c7c1e
[535fe05]: 535fe05be8
[6ac7b81]: 6ac7b8158c
[#755]: https://github.com/thoughtbot/shoulda-matchers/pull/755
[#752]: https://github.com/thoughtbot/shoulda-matchers/pull/752
[9d9dc4e]: 9d9dc4e6b9
[32c0e62]: 32c0e62596
[af98a23]: af98a23091
[8cf449b]: 8cf449b4ca
### Bug fixes
* So far the tests for the gem have been running against only SQLite. Now they
run against PostgreSQL, too. As a result we were able to fix some
Postgres-related bugs, specifically around `validate_uniqueness_of`:
* When scoped to a UUID column that ends in an "f", the matcher is able to
generate a proper "next" value without erroring. ([#402], [#587], [#662])
* Support scopes that are PostgreSQL array columns. Please note that this is
only supported for Rails 4.2 and greater, as versions before this cannot
handle array columns correctly, particularly in conjunction with the
uniqueness validator. ([#554])
* Fix so that when scoped to a text column and the scope is set to nil before
running it through the matcher, the matcher does not fail. ([#521], [#607])
* Fix `define_enum_for` so that it actually tests that the attribute is present
in the list of defined enums, as you could fool it by merely defining a class
method that was the pluralized version of the attribute name. In the same
vein, passing a pluralized version of the attribute name to `define_enum_for`
would erroneously pass, and now it fails. ([#641])
* Fix `permit` so that it does not break the functionality of
ActionController::Parameters#require. ([#648], [#675])
* Fix `validate_uniqueness_of` + `scoped_to` so that it does not raise an error
if a record exists where the scoped attribute is nil. ([#677])
* Fix `route` matcher so if your route includes a default `format`, you can
specify this as a symbol or string. ([#693])
* Fix `validate_uniqueness_of` so that it allows you to test against scoped
attributes that are boolean columns. ([#457], [#694])
* Fix failure message for `validate_numericality_of` as it sometimes didn't
provide the reason for failure. ([#699])
* Fix `shoulda/matchers/independent` so that it can be required
independently, without having to require all of the gem. ([#746], [e0a0200])
### Features
* Add `on` qualifier to `permit`. This allows you to make an assertion that
a restriction was placed on a slice of the `params` hash and not the entire
`params` hash. Although we don't require you to use this qualifier, we do
recommend it, as it's a more precise check. ([#675])
* Add `strict` qualifier to `validate_numericality_of`. ([#620])
* Add `on` qualifier to `validate_numericality_of`. ([9748869]; h/t [#356],
[#358])
* Add `join_table` qualifier to `have_and_belong_to_many`. ([#556])
* `allow_values` is now an alias for `allow_value`. This makes more sense when
checking against multiple values:
``` ruby
it { should allow_values('this', 'and', 'that') }
```
([#692])
[9748869]: 9748869091
[#402]: https://github.com/thoughtbot/shoulda-matchers/pull/402
[#587]: https://github.com/thoughtbot/shoulda-matchers/pull/587
[#662]: https://github.com/thoughtbot/shoulda-matchers/pull/662
[#554]: https://github.com/thoughtbot/shoulda-matchers/pull/554
[#641]: https://github.com/thoughtbot/shoulda-matchers/pull/641
[#521]: https://github.com/thoughtbot/shoulda-matchers/pull/521
[#607]: https://github.com/thoughtbot/shoulda-matchers/pull/607
[#648]: https://github.com/thoughtbot/shoulda-matchers/pull/648
[#675]: https://github.com/thoughtbot/shoulda-matchers/pull/675
[#677]: https://github.com/thoughtbot/shoulda-matchers/pull/677
[#620]: https://github.com/thoughtbot/shoulda-matchers/pull/620
[#693]: https://github.com/thoughtbot/shoulda-matchers/pull/693
[#356]: https://github.com/thoughtbot/shoulda-matchers/pull/356
[#358]: https://github.com/thoughtbot/shoulda-matchers/pull/358
[#556]: https://github.com/thoughtbot/shoulda-matchers/pull/556
[#457]: https://github.com/thoughtbot/shoulda-matchers/pull/457
[#694]: https://github.com/thoughtbot/shoulda-matchers/pull/694
[#692]: https://github.com/thoughtbot/shoulda-matchers/pull/692
[#699]: https://github.com/thoughtbot/shoulda-matchers/pull/699
[#746]: https://github.com/thoughtbot/shoulda-matchers/pull/746
d8caa5a73b