Simple one-liner tests for common Rails functionality

Go to file

Elliot Winkler 9ba21381d7 Handle RangeErrors emitted now in ActiveRecord 4.2 In Rails 4.2, ActiveRecord was changed such that if you attempt to set an attribute to a value and that value is outside the range of the column, then it will raise a RangeError. For instance, an integer column with a limit of 2 (i.e. a smallint) only accepts values between -32768 and +32767. This means that if you try to do any of these three things, a RangeError could be raised: * Use validate_numericality_of along with any of the comparison submatchers and a value that sits on either side of the boundary. * Use allow_value with a value that sits outside the range. * Use validates_inclusion_of against an integer column. (Here we attempt to set that column to a non-integer value to verify that the attribute does not allow said value. That value is really a string version of a large number, so if the column does not take large numbers then the matcher could blow up.) Ancillary changes in this commit: * Remove ValidationMessageFinder and ExceptionMessageFinder in favor of Validator, StrictValidator, and ValidatorWithCapturedRangeError. * The allow_value matcher now uses an instance of Validator under the hood. StrictValidator and/or ValidatorWithCapturedRangeError may be mixed into the Validator object as needed.		2015-01-22 21:05:09 -07:00
.hound_config	Use correct Hound config file	2015-01-22 19:40:39 -07:00
doc_config	Import Source Sans Pro italic in YARD docs	2014-07-25 23:35:46 -06:00
gemfiles	Use pry-nav for more debugging awesomeness	2015-01-22 19:27:52 -07:00
lib	Handle RangeErrors emitted now in ActiveRecord 4.2	2015-01-22 21:05:09 -07:00
script	Add script to update a gem in all appraisals	2015-01-20 13:35:30 -07:00
spec	Handle RangeErrors emitted now in ActiveRecord 4.2	2015-01-22 21:05:09 -07:00
.gitignore	Publish new docs when releasing a new version	2014-06-20 16:41:37 -06:00
.hound.yml	Use correct Hound config file	2015-01-22 19:40:39 -07:00
.travis.yml	Use the new beta build env on Travis	2014-11-19 05:11:29 -07:00
.yardopts	Generate docs using YARD	2014-06-20 16:41:32 -06:00
Appraisals	Add Appraisal for Rails 4.2	2014-12-24 16:27:51 -05:00
CONTRIBUTING.md	Update guide on CONTRIBUTING	2014-10-16 09:59:07 -06:00
Gemfile	Use pry-nav for more debugging awesomeness	2015-01-22 19:27:52 -07:00
Gemfile.lock	Use pry-nav for more debugging awesomeness	2015-01-22 19:27:52 -07:00
MIT-LICENSE	Changed MIT License copyright year to 2014	2014-01-20 09:22:41 -07:00
NEWS.md	Handle RangeErrors emitted now in ActiveRecord 4.2	2015-01-22 21:05:09 -07:00
README.md	Add callback matchers to README	2015-01-19 23:23:53 -07:00
Rakefile	Remove Cucumber tests	2014-11-05 09:53:51 -07:00
cucumber.yml	Use same assertion class as Rails, if loaded	2014-06-27 14:06:47 -06:00
docs.watchr	Rename yard.watchr to docs.watchr	2014-06-21 20:04:17 -06:00
shoulda-matchers.gemspec	Add Elliot Winkler to authors	2014-12-29 16:38:46 -05:00

README.md

shoulda-matchers

Official Documentation

shoulda-matchers provides Test::Unit- and RSpec-compatible one-liners that test common Rails functionality. These tests would otherwise be much longer, more complex, and error-prone.

ActiveModel Matchers

allow_mass_assignment_of tests usage of Rails 3's attr_accessible and attr_protected macros.
allow_value tests usage of the validates_format_of validation.
have_secure_password tests usage of has_secure_password.
validate_confirmation_of tests usage of validates_confirmation_of.
validate_exclusion_of tests usage of validates_exclusion_of.
validate_inclusion_of tests usage of validates_inclusion_of.
validate_length_of tests usage of validates_length_of.
validate_numericality_of tests usage of validates_numericality_of.
validate_presence_of tests usage of validates_presence_of.

ActiveRecord Matchers

accept_nested_attributes_for tests usage of the accepts_nested_attributes_for macro.
belong_to tests your belongs_to associations.
define_enum_for tests usage of the enum macro.
have_and_belong_to_many tests your has_and_belongs_to_many associations.
have_db_column tests that the table that backs your model has a specific column.
have_db_index tests that the table that backs your model has an index on a specific column.
have_many tests your has_many associations.
have_one tests your has_one associations.
have_readonly_attribute tests usage of the attr_readonly macro.
serialize tests usage of the serialize macro.
validate_uniqueness_of tests usage of validates_uniqueness_of.

ActionController Matchers

filter_param tests parameter filtering configuration.
redirect_to tests that an action redirects to a certain location.
render_template tests that an action renders a template.
render_with_layout tests that an action is rendered with a certain layout.
rescue_from tests usage of the rescue_from macro.
respond_with tests that an action responds with a certain status code.
route tests your routes.
set_session makes assertions on the session hash.
set_flash makes assertions on the flash hash.
use_after_action tests that a after_action callback is defined in your controller. (Aliased as use_after_filter.)
use_around_action tests that a around_action callback is defined in your controller. (Aliased as use_around_filter.)
use_before_action tests that a before_action callback is defined in your controller. (Aliased as use_before_filter.)

Independent Matchers

delegate_method tests that an object forwards messages to other, internal objects by way of delegation.

Installation

RSpec

Include the gem in your Gemfile:

group :test do
  gem 'shoulda-matchers', require: false
end

Then require the gem following rspec-rails in your rails_helper (or spec_helper if you're using RSpec 2.x):

require 'rspec/rails'
require 'shoulda/matchers'

Test::Unit

shoulda-matchers was originally a component of Shoulda, a meta-gem that also provides should and context syntax via shoulda-context. For this reason you'll want to include this gem in your Gemfile instead:

group :test do
  gem 'shoulda'
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.

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:

gem 'activemodel'
gem 'shoulda-matchers'

and not:

gem 'shoulda-matchers'
gem 'activemodel'

Generating documentation

YARD is used to generate documentation, which can be viewed online. You can preview changes you make to the documentation locally by running

yard doc

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

Versioning

shoulda-matchers follows Semantic Versioning 2.0 as defined at http://semver.org.

Credits

shoulda-matchers is maintained and funded by thoughtbot. Thank you to all the contributors.