README.md in shoulda-context-1.2.2 vs README.md in shoulda-context-2.0.0.rc1
- old
+ new
@@ -1,24 +1,36 @@
-# shoulda-context [](http://badge.fury.io/rb/shoulda-context) [](https://travis-ci.org/thoughtbot/shoulda-context)
+# Shoulda Context [![Gem Version][version-badge]][rubygems] [![Build Status][travis-badge]][travis] ![Downloads][downloads-badge] [![Hound][hound-badge]][hound]
-[Official Documentation](http://rubydoc.info/github/thoughtbot/shoulda-context/master/frames)
+[version-badge]: https://img.shields.io/gem/v/shoulda-context.svg
+[rubygems]: https://rubygems.org/gems/shoulda-matchers
+[travis-badge]: https://img.shields.io/travis/thoughtbot/shoulda-context/master.svg
+[travis]: https://travis-ci.org/thoughtbot/shoulda-context
+[downloads-badge]: https://img.shields.io/gem/dtv/shoulda-context.svg
+[hound-badge]: https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg
+[hound]: https://houndci.com
-Shoulda's contexts make it easy to write understandable and maintainable tests for Test::Unit.
-It's fully compatible with your existing tests in Test::Unit, and requires no retooling to use.
+Shoulda Context makes it easy to write understandable and maintainable tests
+under Minitest and Test::Unit within Rails projects or plain Ruby projects. It's
+fully compatible with your existing tests and requires no retooling to use.
-Refer to the [shoulda](https://github.com/thoughtbot/shoulda) gem if you want to know more
-about using shoulda with Rails or RSpec.
+**[View the documentation for the latest version (1.2.2)][rubydocs] • [View
+the changelog][changelog]**
-## Contexts
+[changelog]: CHANGELOG.md
-Instead of writing Ruby methods with `lots_of_underscores`, shoulda-context adds
-context, setup, and should blocks...
+---
-```ruby
-require "test/unit"
+## Usage
-class CalculatorTest < Test::Unit::TestCase
+Instead of writing Ruby methods with `lots_of_underscores`, Shoulda Context lets
+you name your tests and group them together using English.
+
+At a minimum, the gem provides some convenience layers around core Minitest
+functionality. For instance, this test case:
+
+```ruby
+class CalculatorTest < Minitest::Test
context "a calculator" do
setup do
@calculator = Calculator.new
end
@@ -31,37 +43,136 @@
end
end
end
```
-... which combine to produce the following test methods:
+is a prettier, but functionally equivalent, way of saying:
- "test: a calculator should add two numbers for the sum."
- "test: a calculator should multiply two numbers for the product."
+```ruby
+class CalculatorTest < Minitest::Test
+ def setup
+ @calculator = Calculator.new
+ end
-When running a single test method via (example from a Rails context):
+ define_method "test_: a calculator should add two numbers for the sum" do
+ assert_equal 4, @calculator.sum(2, 2)
+ end
- ruby -I"lib:test" path_to_test_file -n name_of_the_test_method
+ define_method "test_: a calculator should multiply two numbers for the product" do
+ assert_equal 10, @calculator.product(2, 5)
+ end
+end
+```
-you should include a trailing space(!), e.g.,
+However, Shoulda Context also provides functionality apart from Minitest /
+Test::Unit that allows you to shorten tests drastically by making use of
+RSpec-compatible matchers. For instance, with [Shoulda
+Matchers][shoulda-matchers] you can write such tests as:
- ruby -I"lib:test" path_to_test_file -n "test: a calculator should add two numbers for the sum. "
+```ruby
+class User < ActiveSupport::TestCase
+ context "validations" do
+ subject { FactoryBot.build(:user) }
+ should validate_presence_of(:first_name)
+ should validate_presence_of(:last_name)
+ should validate_uniqueness_of(:email)
+ should_not allow_value('weird').for(:email)
+ end
+end
+```
-## Assertions
+[shoulda-matchers]: https://github.com/thoughtbot/shoulda-matchers
-It also has two additional Test::Unit assertions for working with Ruby's Array:
+## API
- assert_same_elements([:a, :b, :c], [:c, :a, :b])
- assert_contains(['a', '1'], /\d/)
- assert_contains(['a', '1'], 'a')
+### DSL
+The primary method in Shoulda Context's API is `context`, which declares a group
+of a tests.
+
+These methods are available inside of a `context`:
+
+* `setup` — a DSL-y alternative to defining a `setup` method
+* `teardown` — a DSL-y alternative to defining a `teardown` method
+* `should` — There are two forms:
+ 1. when passed a name + block, creates a test equivalent to defining a
+ `test_` method
+ 2. when passed a matcher, creates a test that will run the matcher, asserting
+ that it passes
+* `should_not` — like the matcher version of `should`, but creates a test that
+ asserts that the matcher fails
+* `should_eventually` — allows you to temporarily skip tests
+* `context` — creates a subcontext
+
+These methods are available within a test case class, but outside of a
+`context`:
+
+* `should` — same as above
+* `should_not` — same as above
+* `should_eventually` — same as above
+* `described_type` — returns the class being tested, as determined by the class
+ name of the outermost class
+* `subject` — lets you define an object that is the primary focus of the tests
+ within a context; this is most useful when using a matcher as the matcher will
+ make use of this as _its_ subject
+
+And these methods are available inside of a test (whether defined via a method
+or via `should`):
+
+* `subject` — an instance of the class under test, which is derived
+ automatically from the name of the test case class but is overridable via the
+ class method version of `subject` above
+
+[rubydocs]: http://rubydoc.info/github/thoughtbot/shoulda-context/master/frames
+
+### Assertions
+
+In addition to the main API, the gem also provides some extra assertions that
+may be of use:
+
+* `assert_same_elements` — compares two arrays for equality, but ignoring
+ ordering
+* `assert_contains` — asserts that an array has an item
+* `assert_does_not_contain` — the opposite of `assert_contains`
+* `assert_accepts` — what `should` uses internally; asserts that a matcher
+ object matches against a value
+* `assert_reject` — what `should_not` uses internally; asserts that a matcher
+ object does not match against a value
+
+## Note on running tests
+
+Normally, you will run a single test like this:
+
+ ruby -I lib -I test path_to_test.rb -n name_of_test_method
+
+When using Shoulda Context, however, you'll need to put a space after the test
+name:
+
+ ruby -I lib -I test path_to_test.rb -n "test_: a calculator should add two numbers for the sum. "
+
+If this is too cumbersome, consider using the [m] gem to run tests instead:
+
+ m path_to_test.rb:39
+
+[m]: https://github.com/qrush/m
+
+## Compatibility
+
+Shoulda Context is tested and supported against Rails 5.x, Rails 4.2, Minitest
+5, Test::Unit 3, and Ruby 2.3+.
+
## Credits
-Shoulda is maintained and funded by [thoughtbot](http://thoughtbot.com/community).
-shoulda-context is maintained by [Travis Jeffery](https://github.com/travisjeffery).
-Thank you to all the [contributors](https://github.com/thoughtbot/shoulda-context/contributors).
+Shoulda Context is maintained by [Travis Jeffery][travis-jeffery] and
+thoughtbot. Thank you to all the [contributors].
+[travis-jeffery]: https://github.com/travisjeffery
+[contributors]: https://github.com/thoughtbot/shoulda-context/contributors
+
## License
-Shoulda is Copyright © 2006-2016 thoughtbot, inc.
-It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.
+Shoulda Context is copyright © 2006-2019 [thoughtbot, inc][thoughtbot-website].
+It is free software, and may be redistributed under the terms specified in the
+[MIT-LICENSE](MIT-LICENSE) file.
+
+[thoughtbot-website]: https://thoughtbot.com