+0
Daily
3,578
stars
914
forks
75
watchers
944
prs
778
issues
27
releases
README
Shoulda Matchers [![Gem Version][version-badge]][rubygems] [![Build Status][github-actions-badge]][github-actions] [![Total Downloads][downloads-total]][rubygems] [![Downloads][downloads-badge]][rubygems]
[version-badge]: https://img.shields.io/gem/v/shoulda-matchers.svg
[rubygems]: https://rubygems.org/gems/shoulda-matchers
[github-actions-badge]: https://img.shields.io/github/actions/workflow/status/thoughtbot/shoulda-matchers/ci.yml?branch=main
[github-actions]: https://github.com/thoughtbot/shoulda-matchers/actions
[downloads-total]: https://img.shields.io/gem/dt/shoulda-matchers.svg
[downloads-badge]: https://img.shields.io/gem/dtv/shoulda-matchers.svg
[downloads-badge]: https://img.shields.io/gem/dtv/shoulda-matchers.svg
[![shoulda-matchers][logo]][website]
[logo]: https://matchers.shoulda.io/images/shoulda-matchers-logo.png
[website]: https://matchers.shoulda.io/
Shoulda Matchers provides RSpec and Minitest-compatible one-liners to test
common Rails functionality that, if written by hand, would be much longer, more
complex, and error-prone.
Quick links
📖 [Read the documentation for the latest version][rubydocs].
📢 [See what's changed in recent versions][changelog].
[rubydocs]: https://matchers.shoulda.io/docs
[changelog]: CHANGELOG.md
Table of contents
- Getting started
- RSpec
- Rails apps
- Non-Rails apps
- Minitest
- Rails apps
- Non-Rails apps
- Usage
- On the subject of subject
- Availability of RSpec matchers in example groups
- Rails projects
- Non-Rails projects
- should vs is_expected.to
- A Note on Testing Style
- Matchers
- ActiveModel matchers
- ActiveRecord matchers
- ActionController matchers
- Routing matchers
- Independent matchers
- Extensions
- Contributing
- Compatibility
- Versioning
- Team
- Copyright/License
- About thoughtbot
Getting started
RSpec
Start by including shoulda-matchers in your Gemfile:
ruby
group :test do
gem 'shoulda-matchers', '~ 8.0'
end
Then run bundle install.
Now you need to configure the gem by telling it:
- which matchers you want to use in your tests
- that you're using RSpec so that it can make those matchers available in
your example groups
Rails apps
If you're working on a Rails app, simply place this at the bottom of
spec/rails_helper.rb (or in a support file if you so choose):
ruby
Shoulda::Matchers.configure do |config|
config.integrate do |with|
with.test_framework :rspec
with.library :rails
end
end
Non-Rails apps
If you're not working on a Rails app, but you still make use of ActiveRecord or
ActiveModel in your project, you can still use this gem too! In that case,
you'll want to place the following configuration at the bottom of
spec/spec_helper.rb:
ruby
Shoulda::Matchers.configure do |config|
config.integrate do |with|
with.test_framework :rspec
Keep as many of these lines as are necessary:
with.library :active_record
with.library :active_model
end
end
Minitest
If youTop issues
#682validate_uniqueness_of and foreign key problem23 comments · 2015-03-10#1247shoulda-matcher could not found test class name when work with rails 6 minitest13 comments · 2019-10-16#1113NoMethodError: undefined method `response_code' for nil:NilClass9 comments · 2018-06-25#586delegate_method doesn't allow me to test #to another class9 comments · 2014-09-15#1538Problem when running the tests7 comments · 2023-02-15#1337JoinTableMatcher doesn't find join tables with schema7 comments · 2020-08-27#1382`with_arguments` adds non-documented arguments to delegate method call6 comments · 2020-11-26#1659Different prefixes are not detected by `with_prefix`5 comments · 2025-01-17
Latest release
v8.0.1 v8.0.1 2026-06-12What's Changed fix: Prevent test-model leak without DescendantsTracker.clear by @matsales28 in https://github.com/thoughtbot/shoulda-matchers/pull/1713 Full Changelog: https://github.com/thoughtbot/shoulda-matchers/compare/v8.0.0...v8.0.1