Update installation instructions in README
Also: * Mention RSpec before Minitest (since it's used more often) * Fix instructions on generating YARD documentation automatically * Make a new Contributing section * Use "Shoulda Matchers", not shoulda-matchers * Add notice that this is the README for the master branch [ci skip]
This commit is contained in:
parent
05a11ae90c
commit
aab1aa5bc1
114
README.md
114
README.md
|
@ -1,14 +1,15 @@
|
||||||
# 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 RSpec- and Minitest-compatible one-liners that test
|
||||||
|
|
||||||
shoulda-matchers provides Test::Unit- and RSpec-compatible one-liners that test
|
|
||||||
common Rails functionality. These tests would otherwise be much longer, more
|
common Rails functionality. These tests would otherwise be much longer, more
|
||||||
complex, and error-prone.
|
complex, and error-prone.
|
||||||
|
|
||||||
Thank you to all the [contributors][contributors].
|
[View the official documentation for the latest version (2.8.0).][rubydocs]
|
||||||
|
|
||||||
### ActiveModel Matchers
|
*This is the README for the master branch (3.0.0.alpha). [View 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)**
|
* **[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.
|
tests usage of Rails 3's `attr_accessible` and `attr_protected` macros.
|
||||||
|
@ -29,7 +30,7 @@ Thank you to all the [contributors][contributors].
|
||||||
* **[validate_presence_of](lib/shoulda/matchers/active_model/validate_presence_of_matcher.rb)**
|
* **[validate_presence_of](lib/shoulda/matchers/active_model/validate_presence_of_matcher.rb)**
|
||||||
tests usage of `validates_presence_of`.
|
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)**
|
* **[accept_nested_attributes_for](lib/shoulda/matchers/active_record/accept_nested_attributes_for_matcher.rb)**
|
||||||
tests usage of the `accepts_nested_attributes_for` macro.
|
tests usage of the `accepts_nested_attributes_for` macro.
|
||||||
|
@ -54,7 +55,7 @@ Thank you to all the [contributors][contributors].
|
||||||
* **[validate_uniqueness_of](lib/shoulda/matchers/active_record/validate_uniqueness_of_matcher.rb)**
|
* **[validate_uniqueness_of](lib/shoulda/matchers/active_record/validate_uniqueness_of_matcher.rb)**
|
||||||
tests usage of `validates_uniqueness_of`.
|
tests usage of `validates_uniqueness_of`.
|
||||||
|
|
||||||
### ActionController Matchers
|
### ActionController matchers
|
||||||
|
|
||||||
* **[filter_param](lib/shoulda/matchers/action_controller/filter_param_matcher.rb)**
|
* **[filter_param](lib/shoulda/matchers/action_controller/filter_param_matcher.rb)**
|
||||||
tests parameter filtering configuration.
|
tests parameter filtering configuration.
|
||||||
|
@ -86,7 +87,7 @@ Thank you to all the [contributors][contributors].
|
||||||
tests that a `before_action` callback is defined in your controller. (Aliased
|
tests that a `before_action` callback is defined in your controller. (Aliased
|
||||||
as *use_before_filter*.)
|
as *use_before_filter*.)
|
||||||
|
|
||||||
### Independent Matchers
|
### Independent matchers
|
||||||
|
|
||||||
* **[delegate_method](lib/shoulda/matchers/independent/delegate_method_matcher.rb)**
|
* **[delegate_method](lib/shoulda/matchers/independent/delegate_method_matcher.rb)**
|
||||||
tests that an object forwards messages to other, internal objects by way of
|
tests that an object forwards messages to other, internal objects by way of
|
||||||
|
@ -96,27 +97,30 @@ Thank you to all the [contributors][contributors].
|
||||||
|
|
||||||
### RSpec
|
### RSpec
|
||||||
|
|
||||||
Include the gem in your Gemfile:
|
Include `shoulda-matchers` in your Gemfile:
|
||||||
|
|
||||||
``` ruby
|
``` ruby
|
||||||
group :test do
|
group :test do
|
||||||
gem 'shoulda-matchers', require: false
|
gem 'shoulda-matchers'
|
||||||
end
|
end
|
||||||
```
|
```
|
||||||
|
|
||||||
Then require the gem following rspec-rails in your rails_helper (or spec_helper
|
[Then, configure the gem to integrate with RSpec](#configuration).
|
||||||
if you're using RSpec 2.x):
|
|
||||||
|
Now you can use matchers in your tests. For instance a model test might look
|
||||||
|
like this:
|
||||||
|
|
||||||
``` ruby
|
``` ruby
|
||||||
require 'rspec/rails'
|
describe Person do
|
||||||
require 'shoulda/matchers'
|
it { should validate_presence_of(:name) }
|
||||||
|
end
|
||||||
```
|
```
|
||||||
|
|
||||||
### Test::Unit
|
### Minitest / Test::Unit
|
||||||
|
|
||||||
shoulda-matchers was originally a component of [Shoulda][shoulda], a meta-gem
|
Shoulda Matchers was originally a component of [Shoulda][shoulda], a gem that
|
||||||
that also provides `should` and `context` syntax via
|
also provides `should` and `context` syntax via
|
||||||
[shoulda-context][shoulda-context]. For this reason you'll want to include this
|
[`shoulda-context`][shoulda-context]. For this reason you'll want to include this
|
||||||
gem in your Gemfile instead:
|
gem in your Gemfile instead:
|
||||||
|
|
||||||
```ruby
|
```ruby
|
||||||
|
@ -125,31 +129,44 @@ group :test do
|
||||||
end
|
end
|
||||||
```
|
```
|
||||||
|
|
||||||
### Non-Rails apps
|
[Then, configure the gem to integrate with Minitest](#configuration).
|
||||||
|
|
||||||
Once it is loaded, shoulda-matchers automatically includes itself into your test
|
Now you can use matchers in your tests. For instance a model test might look
|
||||||
framework. It will mix in the appropriate matchers for ActiveRecord,
|
like this:
|
||||||
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
|
``` ruby
|
||||||
shoulda-matchers will most likely be declared after Rails in your Gemfile. If
|
class PersonTest < ActiveSupport::TestCase
|
||||||
your application is written against another framework such as Sinatra or
|
should validate_presence_of(:name)
|
||||||
Padrino, you may have a different setup, so you will want to ensure that you are
|
end
|
||||||
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:
|
|
||||||
|
|
||||||
```ruby
|
|
||||||
gem 'activemodel'
|
|
||||||
gem 'shoulda-matchers'
|
|
||||||
```
|
```
|
||||||
|
|
||||||
and not:
|
### Configuration
|
||||||
|
|
||||||
```ruby
|
Before you can use Shoulda Matchers, you'll need to tell it a couple of things:
|
||||||
gem 'shoulda-matchers'
|
|
||||||
gem 'activemodel'
|
* 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 a library:
|
||||||
|
with.library :active_record
|
||||||
|
with.library :active_model
|
||||||
|
with.library :action_controller
|
||||||
|
# Or, choose all of the above:
|
||||||
|
with.library :rails
|
||||||
|
end
|
||||||
|
end
|
||||||
```
|
```
|
||||||
|
|
||||||
## Generating documentation
|
## Generating documentation
|
||||||
|
@ -164,16 +181,26 @@ 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
|
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:
|
and over again, keep this command running in a separate terminal session:
|
||||||
|
|
||||||
watchr docs.watchr
|
bundle exec guard
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
Shoulda Matchers is open source, and we are grateful for
|
||||||
|
[everyone][contributors] who's contributed so far.
|
||||||
|
|
||||||
|
If you'd like to contribute, please take a look at the
|
||||||
|
[instructions](CONTRIBUTING.md) for installing dependencies and crafting a good
|
||||||
|
pull request.
|
||||||
|
|
||||||
## Versioning
|
## Versioning
|
||||||
|
|
||||||
shoulda-matchers follows Semantic Versioning 2.0 as defined at
|
Shoulda Matchers follows Semantic Versioning 2.0 as defined at
|
||||||
<http://semver.org>.
|
<http://semver.org>.
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
shoulda-matchers is copyright © 2006-2015 [thoughtbot, inc](https://thoughtbot.com/). 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
|
and may be redistributed under the terms specified in the
|
||||||
[MIT-LICENSE](MIT-LICENSE) file.
|
[MIT-LICENSE](MIT-LICENSE) file.
|
||||||
|
|
||||||
|
@ -181,7 +208,7 @@ and may be redistributed under the terms specified in the
|
||||||
|
|
||||||
![thoughtbot](https://thoughtbot.com/logo.png)
|
![thoughtbot](https://thoughtbot.com/logo.png)
|
||||||
|
|
||||||
shoulda-matchers is maintained and funded by thoughtbot, inc.
|
Shoulda Matchers is maintained and funded by thoughtbot, inc.
|
||||||
The names and logos for thoughtbot are trademarks of thoughtbot, inc.
|
The names and logos for thoughtbot are trademarks of thoughtbot, inc.
|
||||||
|
|
||||||
We are passionate about open source software.
|
We are passionate about open source software.
|
||||||
|
@ -199,3 +226,4 @@ We are [available for hire][hire].
|
||||||
[contributors]: https://github.com/thoughtbot/shoulda-matchers/contributors
|
[contributors]: https://github.com/thoughtbot/shoulda-matchers/contributors
|
||||||
[shoulda]: http://github.com/thoughtbot/shoulda
|
[shoulda]: http://github.com/thoughtbot/shoulda
|
||||||
[shoulda-context]: http://github.com/thoughtbot/shoulda-context
|
[shoulda-context]: http://github.com/thoughtbot/shoulda-context
|
||||||
|
[2.8.0-README]: https://github.com/thoughtbot/shoulda-matchers/tree/v2.8.0#shoulda-matchers---
|
||||||
|
|
Loading…
Reference in New Issue