Debian Codegraph @

rspec-core/features/subject/explicit_subject.feature

raw
1 Feature: Explicit Subject
2
3 Use `subject` in the group scope to explicitly define the value that is returned by the
4 `subject` method in the example scope.
5
6 Note that while the examples below demonstrate how the `subject` helper can be used
7 as a user-facing concept, we recommend that you reserve it for support of custom
8 matchers and/or extension libraries that hide its use from examples.
9
10 A named `subject` improves on the explicit `subject` by assigning it a contextually
11 semantic name. Since a named `subject` is an explicit `subject`, it still defines the value
12 that is returned by the `subject` method in the example scope. However, it defines an
13 additional helper method with the provided name. This helper method is memoized.
14 The value is cached across multiple calls in the same example but not across examples.
15
16 We recommend using the named helper method over `subject` in examples.
17
18 For more information about declaring a `subject` see the [API docs](http://rubydoc.info/github/rspec/rspec-core/RSpec/Core/MemoizedHelpers/ClassMethods#subject-instance_method).
19
20 Scenario: A `subject` can be defined and used in the top level group scope
21 Given a file named "top_level_subject_spec.rb" with:
22 """ruby
23 RSpec.describe Array, "with some elements" do
24 subject { [1, 2, 3] }
25
26 it "has the prescribed elements" do
27 expect(subject).to eq([1, 2, 3])
28 end
29 end
30 """
31 When I run `rspec top_level_subject_spec.rb`
32 Then the examples should all pass
33
34 Scenario: The `subject` defined in an outer group is available to inner groups
35 Given a file named "nested_subject_spec.rb" with:
36 """ruby
37 RSpec.describe Array do
38 subject { [1, 2, 3] }
39
40 describe "has some elements" do
41 it "which are the prescribed elements" do
42 expect(subject).to eq([1, 2, 3])
43 end
44 end
45 end
46 """
47 When I run `rspec nested_subject_spec.rb`
48 Then the examples should all pass
49
50 Scenario: The `subject` is memoized within an example but not across examples
51 **Note:** This scenario shows mutation being performed in a `subject` definition block. This
52 behavior is generally discouraged as it makes it more difficult to understand the specs.
53 This is technique is used simply as a tool to demonstrate how the memoization occurs.
54 Given a file named "memoized_subject_spec.rb" with:
55 """ruby
56 RSpec.describe Array do
57 # This uses a context local variable. As you can see from the
58 # specs, it can mutate across examples. Use with caution.
59 element_list = [1, 2, 3]
60
61 subject { element_list.pop }
62
63 it "is memoized across calls (i.e. the block is invoked once)" do
64 expect {
65 3.times { subject }
66 }.to change{ element_list }.from([1, 2, 3]).to([1, 2])
67 expect(subject).to eq(3)
68 end
69
70 it "is not memoized across examples" do
71 expect{ subject }.to change{ element_list }.from([1, 2]).to([1])
72 expect(subject).to eq(2)
73 end
74 end
75 """
76 When I run `rspec memoized_subject_spec.rb`
77 Then the examples should all pass
78
79 Scenario: The `subject` is available in `before` hooks
80 Given a file named "before_hook_subject_spec.rb" with:
81 """ruby
82 RSpec.describe Array, "with some elements" do
83 subject { [] }
84
85 before { subject.push(1, 2, 3) }
86
87 it "has the prescribed elements" do
88 expect(subject).to eq([1, 2, 3])
89 end
90 end
91 """
92 When I run `rspec before_hook_subject_spec.rb`
93 Then the examples should all pass
94
95 Scenario: Helper methods can be invoked from a `subject` definition block
96 Given a file named "helper_subject_spec.rb" with:
97 """ruby
98 RSpec.describe Array, "with some elements" do
99 def prepared_array
100 [1, 2, 3]
101 end
102
103 subject { prepared_array }
104
105 it "has the prescribed elements" do
106 expect(subject).to eq([1, 2, 3])
107 end
108 end
109 """
110 When I run `rspec helper_subject_spec.rb`
111 Then the examples should all pass
112
113 Scenario: Use the `subject!` bang method to call the definition block before the example
114 Given a file named "subject_bang_spec.rb" with:
115 """ruby
116 RSpec.describe "eager loading with subject!" do
117 subject! { element_list.push(99) }
118
119 let(:element_list) { [1, 2, 3] }
120
121 it "calls the definition block before the example" do
122 element_list.push(5)
123 expect(element_list).to eq([1, 2, 3, 99, 5])
124 end
125 end
126 """
127 When I run `rspec subject_bang_spec.rb`
128 Then the examples should all pass
129
130 Scenario: Use `subject(:name)` to define a memoized helper method
131 **Note:** While a global variable is used in the examples below, this behavior is strongly
132 discouraged in actual specs. It is used here simply to demonstrate the value will be
133 cached across multiple calls in the same example but not across examples.
134 Given a file named "named_subject_spec.rb" with:
135 """ruby
136 $count = 0
137
138 RSpec.describe "named subject" do
139 subject(:global_count) { $count += 1 }
140
141 it "is memoized across calls (i.e. the block is invoked once)" do
142 expect {
143 2.times { global_count }
144 }.not_to change{ global_count }.from(1)
145 end
146
147 it "is not cached across examples" do
148 expect(global_count).to eq(2)
149 end
150
151 it "is still available using the subject method" do
152 expect(subject).to eq(3)
153 end
154
155 it "works with the one-liner syntax" do
156 is_expected.to eq(4)
157 end
158
159 it "the subject and named helpers return the same object" do
160 expect(global_count).to be(subject)
161 end
162
163 it "is set to the block return value (i.e. the global $count)" do
164 expect(global_count).to be($count)
165 end
166 end
167 """
168 When I run `rspec named_subject_spec.rb`
169 Then the examples should all pass
170
171 Scenario: Use `subject!(:name)` to define a helper method called before the example
172 Given a file named "named_subject_bang_spec.rb" with:
173 """ruby
174 RSpec.describe "eager loading using a named subject!" do
175 subject!(:updated_list) { element_list.push(99) }
176
177 let(:element_list) { [1, 2, 3] }
178
179 it "calls the definition block before the example" do
180 element_list.push(5)
181 expect(element_list).to eq([1, 2, 3, 99, 5])
182 expect(updated_list).to be(element_list)
183 end
184 end
185 """
186 When I run `rspec named_subject_bang_spec.rb`
187 Then the examples should all pass