Permalink
Browse files

add note that explicit ref to subject is not recommended

  • Loading branch information...
1 parent aefb25c commit 5dc18725bf3db18ddfddac3c5ac4f5aa1af23f8c @dchelimsky dchelimsky committed Feb 16, 2012
@@ -1,10 +1,12 @@
Feature: attribute of subject
- Use the its() method as a short-hand to generate a nested example group with
+ WARNING: `its` will be extracted from rspec-core-3.0 into its own gem.
@nbibler

nbibler May 8, 2012

its will be extracted from rspec-core-3.0 into its own gem.

Is the intention that its will still be a core-stack gem, named something like "rspec-attributes" or "rspec-subject", but still continuing to be installed with gem install rspec? Or, will it be removed from the rspec default installation entirely and live on as a separate, community-run, supplemental gem?

@nbibler

nbibler May 8, 2012

Ahh, I found an issue discussion that mentions this briefly, and the related its gem. So, I take it the latter of the questions above is the most likely path forward .. being an entirely separate, community-run RSpec extension gem.

+
+ Use the `its` method as a short-hand to generate a nested example group with
a single example that specifies the expected value of an attribute of the
subject. This can be used with an implicit or explicit subject.
- its() accepts a symbol or a string, and a block representing the example.
+ `its` accepts a symbol or a string, and a block representing the example.
its(:size) { should eq(1) }
its("length") { should eq(1) }
@@ -1,7 +1,11 @@
Feature: explicit subject
- Use subject() in the group scope to explicitly define the value that is
- returned by the subject() method in the example scope.
+ Use `subject` in the group scope to explicitly define the value that is
+ returned by the `subject` method in the example scope.
+
+ Note that while the examples below demonstrate how `subject` can be used as a
+ user-facing concept, we recommend that you reserve it for support of custom
+ matchers and/or extension libraries that hide its use from examples.
Scenario: subject in top level group
Given a file named "top_level_subject_spec.rb" with:
@@ -1,6 +1,6 @@
Feature: implicit receiver
- When should() is called in an example without an explicit receiver, it is
+ When `should` is called in an example without an explicit receiver, it is
invoked against the subject (explicit or implicit).
Scenario: implicit subject
@@ -1,14 +1,18 @@
-Feature: implicit subject
+Feature: implicitly defined subject
If the first argument to the outermost example group is a class, an instance
- of that class is exposed to each example via the subject() method.
+ of that class is exposed to each example via the `subject` method.
+
+ While the examples below demonstrate how `subject` can be used as a
+ user-facing concept, we recommend that you reserve it for support of custom
+ matchers and/or extension libraries that hide its use from examples.
- Scenario: subject in top level group
+ Scenario: subject exposed in top level group
Given a file named "top_level_subject_spec.rb" with:
"""
- describe Array, "when first created" do
- it "should be empty" do
- subject.should eq([])
+ describe Array do
+ it "should be empty when first created" do
+ subject.should be_empty
end
end
"""
@@ -21,7 +25,36 @@ Feature: implicit subject
describe Array do
describe "when first created" do
it "should be empty" do
- subject.should eq([])
+ subject.should be_empty
+ end
+ end
+ end
+ """
+ When I run `rspec nested_subject_spec.rb`
+ Then the examples should all pass
+
+ Scenario: subject in a nested group with a different class (outermost wins)
+ Given a file named "nested_subject_spec.rb" with:
+ """
+ class ArrayWithOneElement < Array
+ def initialize(*)
+ super
+ unshift "first element"
+ end
+ end
+
+ describe Array do
+ describe ArrayWithOneElement do
+ context "referenced as subject" do
+ it "should be empty (because it is the Array declared at the top)" do
+ subject.should be_empty
+ end
+ end
+
+ context "created in the example" do
+ it "should not be empty" do
+ ArrayWithOneElement.new.should_not be_empty
+ end
end
end
end

0 comments on commit 5dc1872

Please sign in to comment.