thoughtbot /shoulda-matchers

Simple one-liner tests for common Rails functionality

★ 3,578⑂ 914👁 75⑃ 944● 778▤ 27
RubyMITCreated 2010-12-15matchers.shoulda.io
下载:v8.0.1v8.0.1 ↓8.0.12026-06-12
+0
日增长
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 you

Top issues

Latest release

v8.0.1 v8.0.1 2026-06-12
What'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

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON