| 1 |
@oneliner-should |
| 2 |
Feature: One-liner syntax |
| 3 |
|
| 4 |
RSpec supports a one-liner syntax for setting an expectation on the |
| 5 |
`subject`. RSpec will give the examples a doc string that is auto- |
| 6 |
generated from the matcher used in the example. This is designed specifically |
| 7 |
to help avoid duplication in situations where the doc string and the matcher |
| 8 |
used in the example mirror each other exactly. When used excessively, it can |
| 9 |
produce documentation output that does not read well or contribute to |
| 10 |
understanding the object you are describing. |
| 11 |
|
| 12 |
This comes in two flavors: |
| 13 |
|
| 14 |
* `is_expected` is defined simply as `expect(subject)` and is designed for |
| 15 |
when you are using rspec-expectations with its newer expect-based syntax. |
| 16 |
* `should` was designed back when rspec-expectations only had a should-based |
| 17 |
syntax. However, it continues to be available and work even if the |
| 18 |
`:should` syntax is disabled (since that merely removes `Object#should` |
| 19 |
but this is `RSpec::Core::ExampleGroup#should`). |
| 20 |
|
| 21 |
Notes: |
| 22 |
|
| 23 |
* This feature is only available when using rspec-expectations. |
| 24 |
* Examples defined using this one-liner syntax cannot be directly selected from the command line using the [`--example` option](../command-line/example-option). |
| 25 |
* The one-liner syntax only works with non-block expectations (e.g. `expect(obj).to eq`, etc) and it cannot be used with block expectations (e.g. `expect { object }`). |
| 26 |
|
| 27 |
Scenario: Implicit subject |
| 28 |
Given a file named "example_spec.rb" with: |
| 29 |
"""ruby |
| 30 |
RSpec.describe Array do |
| 31 |
describe "when first created" do |
| 32 |
# Rather than: |
| 33 |
# it "should be empty" do |
| 34 |
# subject.should be_empty |
| 35 |
# end |
| 36 |
|
| 37 |
it { should be_empty } |
| 38 |
# or |
| 39 |
it { is_expected.to be_empty } |
| 40 |
end |
| 41 |
end |
| 42 |
""" |
| 43 |
When I run `rspec example_spec.rb --format doc` |
| 44 |
Then the examples should all pass |
| 45 |
And the output should contain: |
| 46 |
""" |
| 47 |
Array |
| 48 |
when first created |
| 49 |
is expected to be empty |
| 50 |
is expected to be empty |
| 51 |
""" |
| 52 |
|
| 53 |
Scenario: Explicit subject |
| 54 |
Given a file named "example_spec.rb" with: |
| 55 |
"""ruby |
| 56 |
RSpec.describe Array do |
| 57 |
describe "with 3 items" do |
| 58 |
subject { [1,2,3] } |
| 59 |
it { should_not be_empty } |
| 60 |
# or |
| 61 |
it { is_expected.not_to be_empty } |
| 62 |
end |
| 63 |
end |
| 64 |
""" |
| 65 |
When I run `rspec example_spec.rb --format doc` |
| 66 |
Then the examples should all pass |
| 67 |
And the output should contain: |
| 68 |
""" |
| 69 |
Array |
| 70 |
with 3 items |
| 71 |
is expected not to be empty |
| 72 |
is expected not to be empty |
| 73 |
""" |