shoulda-matchers 2.8.0 → 3.0.0.rc1

data/Guardfile

@@ -0,0 +1,5 @@
+guard 'yard' do
+  watch('README.md')
+  watch(%r{doc_config/yard/.+})
+  watch(%r{lib/[^/]+\.rb})
+end

data/NEWS.md

@@ -1,3 +1,206 @@
+# HEAD
+
+### 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 things have been end-of-lifed. This doesn't mean that the gem
+  will stop working immediately, but we won't accept any pull requests to fix
+  any compatibility issues, so you're encouraged to upgrade.
+  ([a4045a1], [b7fe87a])
+
+* 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])
+
+* There are two changes to `allow_value`:
+
+  * The negative form of the matcher 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:
+
+        expect(record).not_to allow_value('good value', *bad_values)
+
+    ([19ce8a6])
+
+  * The matcher may raise an error if the attribute in question contains
+    custom logic to ignore certain values, resulting in a discrepancy between
+    the value you provide and the value that the attribute is actually set to.
+    Specifically, if the attribute cannot be changed from a non-nil value to a
+    nil value, or vice versa, then you'll get a CouldNotSetAttributeError. The
+    current behavior (which is to permit this) is misleading, as the test that
+    you're writing under the hood by using `allow_value` could be different from
+    the test that actually ends up getting run. ([eaaa2d8])
+
+* `validate_uniqueness_of` is now properly case-insensitive 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 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])
+
+[no-auto-integration-1]: https://github.com/freerange/mocha/commit/049080c673ee3f76e76adc1e1a6122c7869f1648
+[no-auto-integration-2]: https://github.com/rr/rr/issues/29
+[1900071]: https://github.com/thoughtbot/shoulda-matchers/commit/190007155e0676aae84d08d8ed8eed3beebc3a06
+[b7fe87a]: https://github.com/thoughtbot/shoulda-matchers/commit/b7fe87ae915f6b1f99d64e847fea536ad0f78024
+[a4045a1]: https://github.com/thoughtbot/shoulda-matchers/commit/a4045a1f9bc454e618a7c55960942eb030f02fdd
+[57a1922]: https://github.com/thoughtbot/shoulda-matchers/commit/57a19228b6a85f12ba7a79a26dae5869c1499c6d
+[19ce8a6]: https://github.com/thoughtbot/shoulda-matchers/commit/19c38a642a2ae1316ef12540a0185cd026901e74
+[eaaa2d8]: https://github.com/thoughtbot/shoulda-matchers/commit/eaaa2d83e5cd31a3ca0a1aaa65441ea1a4fffa49
+[55c8d09]: https://github.com/thoughtbot/shoulda-matchers/commit/55c8d09bf2af886540924efa83c3b518d926a770
+[801f2c7]: https://github.com/thoughtbot/shoulda-matchers/commit/801f2c7c1eab3b2053244485c9800f850959cfef
+[535fe05]: https://github.com/thoughtbot/shoulda-matchers/commit/535fe05be8686fdafd8b22f2ed5c4192bd565d50
+[eaaa2d8]: https://github.com/thoughtbot/shoulda-matchers/commit/eaaa2d83e5cd31a3ca0a1aaa65441ea1a4fffa49
+[6ac7b81]: https://github.com/thoughtbot/shoulda-matchers/commit/6ac7b8158cfba3b518eb3da3c24345e4473b416f
+
+### 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])
+
+### 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]: https://github.com/thoughtbot/shoulda-matchers/commit/97488690910520ed8e1f2e164b1982eff5ef1f19
+[#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
+
 # 2.8.0
 
 ### Deprecations

data/README.md

@@ -1,12 +1,17 @@
-# shoulda-matchers [![Gem Version][version-badge]][rubygems] [![Build Status][travis-badge]][travis] ![Downloads][downloads-badge]
+# Shoulda Matchers [![Gem Version][version-badge]][rubygems] [![Build Status][travis-badge]][travis] ![Downloads][downloads-badge]
 
-[Official Documentation][rubydocs]
-
-shoulda-matchers provides Test::Unit- and RSpec-compatible one-liners that test
+Shoulda Matchers provides RSpec- and Minitest-compatible one-liners that test
 common Rails functionality. These tests would otherwise be much longer, more
 complex, and error-prone.
 
-### ActiveModel Matchers
+[View the official documentation for the latest version (2.8.0).][rubydocs]
+
+**Heads up! This is the README for the master branch. [You might be more
+interested in the README for 2.8.0 instead.][2.8.0-README]**
+
+----
+
+### ActiveModel matchers
 
 * **[allow_mass_assignment_of](lib/shoulda/matchers/active_model/allow_mass_assignment_of_matcher.rb)**
   tests usage of Rails 3's `attr_accessible` and `attr_protected` macros.
@@ -27,7 +32,7 @@ complex, and error-prone.
 * **[validate_presence_of](lib/shoulda/matchers/active_model/validate_presence_of_matcher.rb)**
   tests usage of `validates_presence_of`.
 
-### ActiveRecord Matchers
+### ActiveRecord matchers
 
 * **[accept_nested_attributes_for](lib/shoulda/matchers/active_record/accept_nested_attributes_for_matcher.rb)**
   tests usage of the `accepts_nested_attributes_for` macro.
@@ -52,10 +57,12 @@ complex, and error-prone.
 * **[validate_uniqueness_of](lib/shoulda/matchers/active_record/validate_uniqueness_of_matcher.rb)**
   tests usage of `validates_uniqueness_of`.
 
-### ActionController Matchers
+### ActionController matchers
 
 * **[filter_param](lib/shoulda/matchers/action_controller/filter_param_matcher.rb)**
   tests parameter filtering configuration.
+* **[permit](lib/shoulda/matchers/action_controller/permit_matcher.rb)** tests
+  that an action places a restriction on the `params` hash.
 * **[redirect_to](lib/shoulda/matchers/action_controller/redirect_to_matcher.rb)**
   tests that an action redirects to a certain location.
 * **[render_template](lib/shoulda/matchers/action_controller/render_template_matcher.rb)**
@@ -72,17 +79,17 @@ complex, and error-prone.
   makes assertions on the `session` hash.
 * **[set_flash](lib/shoulda/matchers/action_controller/set_flash_matcher.rb)**
   makes assertions on the `flash` hash.
-* **[use_after_action](lib/shoulda/matchers/action_controller/use_after_action.rb)**
+* **[use_after_action](lib/shoulda/matchers/action_controller/callback_matcher.rb#L79)**
   tests that a `after_action` callback is defined in your controller. (Aliased
   as *use_after_filter*.)
-* **[use_around_action](lib/shoulda/matchers/action_controller/use_around_action.rb)**
+* **[use_around_action](lib/shoulda/matchers/action_controller/callback_matcher.rb#L129)**
   tests that a `around_action` callback is defined in your controller. (Aliased
   as *use_around_filter*.)
-* **[use_before_action](lib/shoulda/matchers/action_controller/use_before_action.rb)**
+* **[use_before_action](lib/shoulda/matchers/action_controller/callback_matcher.rb#L54)**
   tests that a `before_action` callback is defined in your controller. (Aliased
   as *use_before_filter*.)
 
-### Independent Matchers
+### Independent matchers
 
 * **[delegate_method](lib/shoulda/matchers/independent/delegate_method_matcher.rb)**
   tests that an object forwards messages to other, internal objects by way of
@@ -92,27 +99,30 @@ complex, and error-prone.
 
 ### RSpec
 
-Include the gem in your Gemfile:
+Include `shoulda-matchers` in your Gemfile:
 
 ``` ruby
 group :test do
-  gem 'shoulda-matchers', require: false
+  gem 'shoulda-matchers'
 end
 ```
 
-Then require the gem following rspec-rails in your rails_helper (or spec_helper
-if you're using RSpec 2.x):
+[Then, configure the gem to integrate with RSpec](#configuration).
+
+Now you can use matchers in your tests. For instance a model test might look
+like this:
 
 ``` ruby
-require 'rspec/rails'
-require 'shoulda/matchers'
+describe Person do
+  it { should validate_presence_of(:name) }
+end
 ```
 
-### Test::Unit
+### Minitest / Test::Unit
 
-shoulda-matchers was originally a component of [Shoulda][shoulda], a meta-gem
-that also provides `should` and `context` syntax via
-[shoulda-context][shoulda-context]. For this reason you'll want to include this
+Shoulda Matchers was originally a component of [Shoulda][shoulda], a gem that
+also provides `should` and `context` syntax via
+[`shoulda-context`][shoulda-context]. For this reason you'll want to include this
 gem in your Gemfile instead:
 
 ```ruby
@@ -121,31 +131,48 @@ group :test do
 end
 ```
 
-### Non-Rails apps
-
-Once it is loaded, shoulda-matchers automatically includes itself into your test
-framework. It will mix in the appropriate matchers for ActiveRecord,
-ActiveModel, and ActionController depending on the modules that are available at
-runtime. For instance, in order to use the ActiveRecord matchers, ActiveRecord
-must be present beforehand.
+[Then, configure the gem to integrate with Minitest](#configuration).
 
-If your application is written against Rails, everything should "just work", as
-shoulda-matchers will most likely be declared after Rails in your Gemfile. If
-your application is written against another framework such as Sinatra or
-Padrino, you may have a different setup, so you will want to ensure that you are
-requiring shoulda-matchers after the components of Rails you are using. For
-instance, if you wanted to use and test against ActiveModel, you'd say:
+Now you can use matchers in your tests. For instance a model test might look
+like this:
 
-```ruby
-gem 'activemodel'
-gem 'shoulda-matchers'
+``` ruby
+class PersonTest < ActiveSupport::TestCase
+  should validate_presence_of(:name)
+end
 ```
 
-and not:
+### Configuration
 
-```ruby
-gem 'shoulda-matchers'
-gem 'activemodel'
+**NOTE: The new configuration syntax isn't available in a public release just
+yet -- please refer to the [README for 2.8.0][2.8.0-README] for the current
+installation instructions.**
+
+Before you can use Shoulda Matchers, you'll need to tell it a couple of things:
+
+* Which test framework you're using
+* Which portion of the matchers you want to use
+
+You can supply this information by using a configuration block. Place the
+following in your test or spec helper:
+
+``` 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
 ```
 
 ## Generating documentation
@@ -160,31 +187,49 @@ from this directory. Then, open `doc/index.html` in your browser.
 If you want to see a live preview as you work without having to run `yard` over
 and over again, keep this command running in a separate terminal session:
 
-    watchr docs.watchr
+    bundle exec guard
 
-## Versioning
+## Contributing
 
-shoulda-matchers follows Semantic Versioning 2.0 as defined at
-<http://semver.org>.
+Shoulda Matchers is open source, and we are grateful for
+[everyone][contributors] who's contributed so far.
 
-## Credits
+If you'd like to contribute, please take a look at the
+[instructions](CONTRIBUTING.md) for installing dependencies and crafting a good
+pull request.
 
-shoulda-matchers is maintained and funded by [thoughtbot][community]. Thank you
-to all the [contributors][contributors].
+## Versioning
+
+Shoulda Matchers follows Semantic Versioning 2.0 as defined at
+<http://semver.org>.
 
 ## License
 
-shoulda-matchers is copyright © 2006-2014 thoughtbot, inc. It is free software,
+Shoulda Matchers is copyright © 2006-2015
+[thoughtbot, inc](https://thoughtbot.com/). It is free software,
 and may be redistributed under the terms specified in the
 [MIT-LICENSE](MIT-LICENSE) file.
 
+## About thoughtbot
+
+![thoughtbot](https://thoughtbot.com/logo.png)
+
+Shoulda Matchers is maintained and funded by thoughtbot, inc.
+The names and logos for thoughtbot are trademarks of thoughtbot, inc.
+
+We are passionate about open source software.
+See [our other projects][community].
+We are [available for hire][hire].
+
+[community]: https://thoughtbot.com/community?utm_source=github
+[hire]: https://thoughtbot.com?utm_source=github
 [version-badge]: http://img.shields.io/gem/v/shoulda-matchers.svg
 [rubygems]: http://rubygems.org/gems/shoulda-matchers
 [travis-badge]: http://img.shields.io/travis/thoughtbot/shoulda-matchers/master.svg
 [travis]: http://travis-ci.org/thoughtbot/shoulda-matchers
 [downloads-badge]: http://img.shields.io/gem/dtv/shoulda-matchers.svg
 [rubydocs]: http://matchers.shoulda.io/docs
-[community]: http://thoughtbot.com/community
 [contributors]: https://github.com/thoughtbot/shoulda-matchers/contributors
 [shoulda]: http://github.com/thoughtbot/shoulda
 [shoulda-context]: http://github.com/thoughtbot/shoulda-context
+[2.8.0-README]: https://github.com/thoughtbot/shoulda-matchers/tree/v2.8.0#shoulda-matchers---

data/Rakefile

@@ -3,6 +3,7 @@ require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 require 'appraisal'
 require_relative 'tasks/documentation'
+require_relative 'spec/support/tests/database'
 
 RSpec::Core::RakeTask.new('spec:unit') do |t|
   t.ruby_opts = '-w -r ./spec/report_warnings'