Permalink
Browse files

Improve cuke narratives.

I'm not a fan of the connextra format for these sorts
of documentation-focused cukes. Freeform narrative works
better, IMO.

Also, renamed `expect_change` to `change` and
`expect_error` to `raise_error` to align with
the matcher name.
  • Loading branch information...
1 parent a6b663a commit a00f8362d1b666e68b264c0a626b311e58e6107a @myronmarston myronmarston committed Feb 20, 2014
View
@@ -9,8 +9,8 @@
- be_within.feature
- equality.feature
- exist.feature
- - expect_change.feature
- - expect_error.feature
+ - change.feature
+ - raise_error.feature
- have.feature
- include.feature
- match.feature
@@ -1,6 +1,14 @@
-Feature: expect change
+Feature: change matcher
- Expect the execution of a block of code to change the state of an object.
+ The `change` matcher is used to specify that a block of code changes
+ some mutable state. You can specify what will change using either of
+ two forms:
+
+ * `expect { do_something }.to change(object, :attribute)`
+ * `expect { do_something }.to change { object.attribute }`
+
+ You can further qualify the change by chaining `by`, `by_at_most`,
+ `by_at_least`, `from` and/or `to`.
Background:
Given a file named "lib/counter.rb" with:
@@ -9,7 +9,6 @@ Feature: comparison matchers
expect(1).to be < 6
```
-
Scenario: numeric operator matchers
Given a file named "numeric_operator_matchers_spec.rb" with:
"""ruby
@@ -1,7 +1,7 @@
Feature: match matcher
- The match matcher calls #match on the object, passing if #match returns a
- truthy (not false or nil) value. Regexp and String both provide a #match
+ The match matcher calls `#match` on the object, passing if `#match` returns a
+ truthy (not `false` or `nil`) value. Regexp and String both provide a `#match`
method.
```ruby
@@ -11,8 +11,8 @@ Feature: match matcher
expect(/foo/).to match("drinks") # fails
```
- This is equivalent to using the =~ matcher (see the operator matchers
- feature for more details).
+ You can also use this matcher to match nested data structures when
+ composing matchers.
Scenario: string usage
Given a file named "string_match_spec.rb" with:
@@ -1,13 +1,9 @@
Feature: access running example
- In order to take advantage of services that are available
- in my examples when I'm writing matchers
- As a spec author
- I want to call methods on the running example
-
- If the method exists in the context of the example, it gets
- called. If not, a NoMethodError is raised on the Matcher itself
- (not the example).
+ In the context of a custom matcher, you can call helper methods that are
+ available from the current example's example group. This is used, for example,
+ by rspec-rails in order to wrap rails' built-in assertions (which depend on
+ helper methods available in the test context).
Scenario: call method defined on example from matcher
Given a file named "example_spec.rb" with:
@@ -1,8 +1,8 @@
Feature: define matcher
- In order to express my domain clearly in my code examples
- As an RSpec user
- I want a shortcut to define custom matchers
+ rspec-expectations provides a DSL for defining custom matchers.
+ These are often useful for expressing expectations in the domain
+ of your application.
Scenario: define a matcher with default messages
Given a file named "matcher_with_default_message_spec.rb" with:
@@ -1,8 +1,6 @@
Feature: define matcher outside rspec
- In order to express my domain clearly in my code examples
- As a non-rspec user
- I want a shortcut to define custom matchers
+ You can define custom matchers when using rspec-expectations outside of rspec-core.
Scenario: define a matcher with default messages
Given a file named "test_multiples.rb" with:
@@ -1,6 +1,6 @@
Feature: define matcher with fluent interface
- Use the chain() method to define matchers with a fluent interface.
+ Use the `chain` method to define matchers with a fluent interface.
Scenario: chained method with argument
Given a file named "between_spec.rb" with:
@@ -1,20 +1,26 @@
Feature: implicit docstrings
- As an RSpec user
- I want examples to generate their own names
- So that I can reduce duplication between example names and example code
+ When you use rspec-expectations with rspec-core, RSpec is able to
+ auto-generate the docstrings for examples for you based on the last
+ expectation in the example. This can be handy when the matcher expresses
+ exactly what you would write in your example docstring, but it can also
+ be easily abused. We find that the freeform nature of the docstring
+ provides a lot of value when used well (e.g. to document the "why" of
+ a particular behavior), and you lose that kind of flexibility when you rely
+ on the matcher to generate the docstring for you.
+
+ In general, we recommend only using this feature when the matcher aligns
+ _exactly_ with the docstring you would write. Even then, many users prefer
+ the explicitness of the full docstring, so use this feature with care
+ (if at all).
Scenario: run passing examples
Given a file named "implicit_docstrings_spec.rb" with:
"""ruby
describe "Examples with no docstrings generate their own:" do
-
specify { expect(3).to be < 5 }
-
specify { expect([1,2,3]).to include(2) }
-
specify { expect([1,2,3]).to respond_to(:size) }
-
end
"""
@@ -28,19 +34,15 @@ Feature: implicit docstrings
Given a file named "failing_implicit_docstrings_spec.rb" with:
"""ruby
describe "Failing examples with no descriptions" do
-
# description is auto-generated as "to equal(5)" based on the last #expect
it do
expect(3).to equal(2)
expect(5).to equal(5)
end
it { expect(3).to be > 5 }
-
it { expect([1,2,3]).to include(4) }
-
it { expect([1,2,3]).not_to respond_to(:size) }
-
end
"""

0 comments on commit a00f836

Please sign in to comment.