r_spec-clone 1.1.0 → 1.2.3

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 6d314d17896138ce2ff2b6d7eb389a1ba2316690f40923684c68632227692a5f
4
- data.tar.gz: af8efe2d9ab1b773db062263503221dd56b6b7a604e73d5f1a84baf0ccbf2b35
3
+ metadata.gz: 5c76f25e186a2f835a2a006e3b3add6c7b94d4b070bd3a81b866747edff8291f
4
+ data.tar.gz: e9203508514fde39e690e145172dd417d2dcd20eb6badc44a1cb34fc3dc7335a
5
5
  SHA512:
6
- metadata.gz: a57d31c77a3da5d120651efbbc1f6d28f808fa47d9c7184e04f79723273df0ce6d84ba08628bc2f60c98c7756a0f2cf1d46774f42d1c505ca9f4e522f418e404
7
- data.tar.gz: 2b2cb13a1620fd98107b3f82e8d7427ae11eb054e9e4bd8c36fe21402efc9dc38af0f6aa41850dc65c05eeba9cfc918a23dfcdea743658963459ef9e5b35c689
6
+ metadata.gz: 30681f5232bef7c695e05b169ce5fcf3882277bf981174898d586a01c756b0eec3ca88c9eecf6c02c3deae7d515e84f3bbd404202cb1aef59f63b70fa901f6ca
7
+ data.tar.gz: 0e4e21aa8f6aa8d6f281ce99add7018ea6d163fab13fd8cd04863104884244a74566b11d665d3e7a7e5c0e683e474b479d18383b0cf8e7f192b7986cd7947d26
data/README.md CHANGED
@@ -6,6 +6,7 @@ A minimalist __RSpec clone__ with all the essentials.
6
6
 
7
7
  ## Status
8
8
 
9
+ [![Home](https://img.shields.io/badge/Home-r--spec.dev-00af8b)](https://r-spec.dev/)
9
10
  [![Version](https://img.shields.io/github/v/tag/cyril/r_spec-clone.rb?label=Version&logo=github)](https://github.com/cyril/r_spec-clone.rb/releases)
10
11
  [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/cyril/r_spec-clone.rb/main)
11
12
  [![CI](https://github.com/cyril/r_spec-clone.rb/workflows/CI/badge.svg?branch=main)](https://github.com/cyril/r_spec-clone.rb/actions?query=workflow%3Aci+branch%3Amain)
@@ -14,17 +15,16 @@ A minimalist __RSpec clone__ with all the essentials.
14
15
 
15
16
  ## Project goals
16
17
 
17
- 1. Keep a low level of code complexity and ensure thread safety.
18
- 2. The interface must translate into atomic and simple Ruby objects.
18
+ 1. Keep a low level of code complexity, avoid false negatives and false positives.
19
+ 2. Translate specification documents into atomic and thread safe Ruby objects.
19
20
  3. Avoid overloading the interface with additional alternative syntaxes.
20
21
  4. Provide most of RSpec's DSL to express expected outcomes of a code example.
21
22
 
22
23
  ## Some differences
23
24
 
24
- * Spec files can be executed with `ruby` directly.
25
25
  * There is no option to activate monkey-patching.
26
- * It does not rely on hacks such as [`at_exit` hook](https://blog.arkency.com/2013/06/are-we-abusing-at-exit/) to trigger the tests.
27
- * Built-in matchers [do not trust _actual_](https://asciinema.org/a/29172?autoplay=1&speed=2) and do not send it messages.
26
+ * It does not rely on [hacks such as `at_exit` hook](https://blog.arkency.com/2013/06/are-we-abusing-at-exit/) to trigger the tests.
27
+ * Malicious _actual values_ cannot [hack results](https://asciinema.org/a/423547?autoplay=1&speed=2).
28
28
  * If no `subject` has been explicitly determined, none is defined.
29
29
  * If no described class is set, `described_class` is undefined instead of `nil`.
30
30
  * Expectations cannot be added inside a `before` block.
@@ -32,7 +32,7 @@ A minimalist __RSpec clone__ with all the essentials.
32
32
  * The `let` method defines a helper method rather than a memoized helper method.
33
33
  * The one-liner `is_expected` syntax also works with block expectations.
34
34
  * `subject`, `before`, `after` and `let` definitions must come before examples.
35
- * Groups and examples are _executed in subprocesses_ the order they are defined.
35
+ * Runs much faster.
36
36
 
37
37
  ## Installation
38
38
 
@@ -68,7 +68,7 @@ A basic spec looks something like this:
68
68
 
69
69
  ### Anatomy of a spec file
70
70
 
71
- To use the `RSpec` module and its DSL, you need to add `require "r_spec/clone"` to your spec files.
71
+ To use the `RSpec` module and its DSL, you need to add `require "r_spec"` to your spec files.
72
72
  Many projects use a custom spec helper which organizes these includes.
73
73
 
74
74
  Concrete test cases are defined in `it` blocks.
@@ -79,6 +79,8 @@ Test cases that have been defined or outlined but are not yet expected to work c
79
79
  An `it` block contains an example that should invoke the code to be tested and define what is expected of it.
80
80
  Each example can contain multiple expectations, but it should test only one specific behaviour.
81
81
 
82
+ The `its` method can also be used to generate a nested example group with a single example that specifies the expected value (or the block expectations) of an attribute of the subject using `is_expected`.
83
+
82
84
  To express an expectation, wrap an object or block in `expect`, call `to` (or `not_to`) and pass it a matcher object.
83
85
  If the expectation is met, code execution continues.
84
86
  Otherwise the example has _failed_ and other code will not be executed.
@@ -94,6 +96,27 @@ For unit tests, it is recommended to follow the conventions for method names:
94
96
 
95
97
  To establish certain contexts — think _empty array_ versus _array with elements_ — the `context` method may be used to communicate this to the reader.
96
98
 
99
+ To execute unit tests while isolating side effects in a sub-process, declined methods can be used: `describe!`, `context!`, `it!`, `its!`. Here is an example:
100
+
101
+ ```ruby
102
+ app = "foo"
103
+
104
+ RSpec.describe "Side effects per example" do
105
+ it! "runs the example in isolation" do
106
+ expect { app.gsub!("foo", "bar") }.to eq "bar"
107
+ expect(app).to eq "bar"
108
+ end
109
+
110
+ it "runs the example" do
111
+ expect(app).to eq "foo"
112
+ end
113
+ end
114
+
115
+ # Success: expected to eq "bar".
116
+ # Success: expected to eq "bar".
117
+ # Success: expected to eq "foo".
118
+ ```
119
+
97
120
  ### Expectations
98
121
 
99
122
  Expectations define if the value being tested (_actual_) matches a certain value or specific criteria.
@@ -211,9 +234,15 @@ bundle exec rake
211
234
 
212
235
  ### Boot time
213
236
 
214
- Benchmark against [100 executions of a file containing one expectation](https://github.com/cyril/r_spec-clone.rb/blob/main/benchmark/) (lower is better).
237
+ Benchmark against [100 executions of a file containing 1 expectation](https://github.com/cyril/r_spec-clone.rb/blob/main/benchmark/boot_time/) (lower is better).
238
+
239
+ ![Boot time](https://r-spec.dev/benchmark-boot-time.svg)
240
+
241
+ ### Run time
242
+
243
+ Benchmark against [1 execution of a file containing 1,000,000 expectations](https://github.com/cyril/r_spec-clone.rb/blob/main/benchmark/run_time/) (lower is better).
215
244
 
216
- ![Runtime](https://r-spec.dev/benchmark-boot-time.svg)
245
+ ![Run time](https://r-spec.dev/benchmark-run-time.svg)
217
246
 
218
247
  ## Test suite
219
248
 
@@ -223,6 +252,7 @@ __RSpec clone__'s specifications are self-described here: [spec/](https://github
223
252
 
224
253
  * Home page: [https://r-spec.dev/](https://r-spec.dev/)
225
254
  * Cheatsheet: [https://r-spec.dev/cheatsheet.html](https://r-spec.dev/cheatsheet.html)
255
+ * Blog post: [https://batman.buzz/introducing-a-new-rspec-850d48c0f901](https://batman.buzz/introducing-a-new-rspec-850d48c0f901)
226
256
  * Source code: [https://github.com/cyril/r_spec-clone.rb](https://github.com/cyril/r_spec-clone.rb)
227
257
  * API Doc: [https://rubydoc.info/gems/r_spec-clone](https://rubydoc.info/gems/r_spec-clone)
228
258
  * Twitter: [https://twitter.com/cyri\_](https://twitter.com/cyri\_)
data/lib/r_spec.rb CHANGED
@@ -5,7 +5,7 @@ require_relative File.join("r_spec", "clone", "dsl")
5
5
  # Top level namespace for the RSpec clone.
6
6
  #
7
7
  # @example The true from the false
8
- # require "r_spec/clone"
8
+ # require "r_spec"
9
9
  #
10
10
  # RSpec.describe "The true from the false" do
11
11
  # it { expect(false).not_to be true }
@@ -15,7 +15,7 @@ require_relative File.join("r_spec", "clone", "dsl")
15
15
  # # Success: expected false not to be true.
16
16
  #
17
17
  # @example The basic behavior of arrays
18
- # require "r_spec/clone"
18
+ # require "r_spec"
19
19
  #
20
20
  # RSpec.describe Array do
21
21
  # describe "#size" do
@@ -41,7 +41,7 @@ require_relative File.join("r_spec", "clone", "dsl")
41
41
  # # Success: expected false to be false.
42
42
  #
43
43
  # @example An inherited definition of let
44
- # require "r_spec/clone"
44
+ # require "r_spec"
45
45
  #
46
46
  # RSpec.describe Integer do
47
47
  # let(:answer) { 42 }
@@ -69,7 +69,7 @@ module RSpec
69
69
  # array_ versus _array with elements_.
70
70
  #
71
71
  # @example
72
- # require "r_spec/clone"
72
+ # require "r_spec"
73
73
  #
74
74
  # RSpec.context "when divided by zero" do
75
75
  # subject { 42 / 0 }
@@ -83,20 +83,62 @@ module RSpec
83
83
  # @param description [String] A description that usually begins with "when",
84
84
  # "with" or "without".
85
85
  # @param block [Proc] The block to define the specs.
86
- #
87
- # @api public
88
86
  def self.context(description, &block)
89
87
  Clone::Dsl.context(description, &block)
90
88
  end
91
89
 
90
+ # :nocov:
91
+
92
+ # Runs a context example group in a subprocess to isolate side effects.
93
+ #
94
+ # @example
95
+ # str = "Hello, world!"
96
+ #
97
+ # require "r_spec"
98
+ #
99
+ # RSpec.context! "when a string becomes uppercase" do
100
+ # before do
101
+ # str.upcase!
102
+ # end
103
+ #
104
+ # it { expect(str).to eq "HELLO, WORLD!" }
105
+ # end
106
+ #
107
+ # # Output to the console
108
+ # # Success: expected to eq "HELLO, WORLD!".
109
+ #
110
+ # RSpec.it { expect(str).to eq "Hello, world!" }
111
+ #
112
+ # # Output to the console
113
+ # # Success: expected to eq "Hello, world!".
114
+ #
115
+ # @param (see #context)
116
+ def self.context!(description, &block)
117
+ Clone::Dsl.context!(description, &block)
118
+ end
119
+
120
+ # :nocov:
121
+
92
122
  # Defines an example group that describes a unit to be tested.
93
123
  #
94
124
  # @example
95
- # require "r_spec/clone"
125
+ # require "r_spec"
96
126
  #
97
127
  # RSpec.describe String do
128
+ # it { expect(described_class).to be String }
129
+ # end
130
+ #
131
+ # # Output to the console
132
+ # # Success: expected to be String.
133
+ #
134
+ # @example
135
+ # require "r_spec"
136
+ #
137
+ # RSpec.describe String do
138
+ # let(:foo) { "foo" }
139
+ #
98
140
  # describe "+" do
99
- # it("concats") { expect("foo" + "bar").to eq "foobar" }
141
+ # it("concats") { expect(foo + "bar").to eq "foobar" }
100
142
  # end
101
143
  # end
102
144
  #
@@ -105,18 +147,48 @@ module RSpec
105
147
  #
106
148
  # @param const [Module, String] A module to include in block context.
107
149
  # @param block [Proc] The block to define the specs.
108
- #
109
- # @api public
110
150
  def self.describe(const, &block)
111
151
  Clone::Dsl.describe(const, &block)
112
152
  end
113
153
 
154
+ # :nocov:
155
+
156
+ # Runs a describe example group in a subprocess to isolate side effects.
157
+ #
158
+ # @example
159
+ # $app = "foo"
160
+ #
161
+ # require "r_spec"
162
+ #
163
+ # RSpec.describe! "#gsub!" do
164
+ # before do
165
+ # $app.gsub!("o", "0")
166
+ # end
167
+ #
168
+ # it { expect($app).to eq "f00" }
169
+ # end
170
+ #
171
+ # # Output to the console
172
+ # # Success: expected to eq "f00".
173
+ #
174
+ # RSpec.it { expect($app).to eq "foo" }
175
+ #
176
+ # # Output to the console
177
+ # # Success: expected to eq "foo".
178
+ #
179
+ # @param (see #describe)
180
+ def self.describe!(const, &block)
181
+ Clone::Dsl.describe!(const, &block)
182
+ end
183
+
184
+ # :nocov:
185
+
114
186
  # Defines a concrete test case.
115
187
  #
116
188
  # The test is performed by the block supplied to &block.
117
189
  #
118
190
  # @example The integer after 41
119
- # require "r_spec/clone"
191
+ # require "r_spec"
120
192
  #
121
193
  # RSpec.it { expect(41.next).to be 42 }
122
194
  #
@@ -129,21 +201,48 @@ module RSpec
129
201
  # @param name [String, nil] The name of the spec.
130
202
  # @param block [Proc] An expectation to evaluate.
131
203
  #
132
- # @raise (see RSpec::ExpectationTarget::Base#result)
133
- # @return (see RSpec::ExpectationTarget::Base#result)
134
- #
135
- # @api public
204
+ # @raise (see RSpec::Clone::ExpectationTarget::Base#result)
205
+ # @return (see RSpec::Clone::ExpectationTarget::Base#result)
136
206
  def self.it(name = nil, &block)
137
207
  Clone::Dsl.it(name, &block)
138
208
  end
139
209
 
210
+ # :nocov:
211
+
212
+ # Runs a concrete test case in a subprocess to isolate side effects.
213
+ #
214
+ # @example
215
+ # app = "Hello, world!"
216
+ #
217
+ # require "r_spec"
218
+ #
219
+ # RSpec.it! { expect(app.gsub!("world", "Alice")).to eq "Hello, Alice!" }
220
+ #
221
+ # # Output to the console
222
+ # # Success: expected to eq "Hello, Alice!".
223
+ #
224
+ # RSpec.it { expect(app).to eq "Hello, world!" }
225
+ #
226
+ # # Output to the console
227
+ # # Success: expected to eq "Hello, world!".
228
+ #
229
+ # @param (see #it)
230
+ #
231
+ # @raise (see ExpectationTarget::Base#result)
232
+ # @return (see ExpectationTarget::Base#result)
233
+ def self.it!(name = nil, &block)
234
+ Clone::Dsl.it!(name, &block)
235
+ end
236
+
237
+ # :nocov:
238
+
140
239
  # Defines a pending test case.
141
240
  #
142
241
  # `&block` is never evaluated. It can be used to describe behaviour that is
143
242
  # not yet implemented.
144
243
  #
145
244
  # @example
146
- # require "r_spec/clone"
245
+ # require "r_spec"
147
246
  #
148
247
  # RSpec.pending "is implemented but waiting" do
149
248
  # expect something to be finished
@@ -161,8 +260,6 @@ module RSpec
161
260
  # @param message [String] The reason why the example is pending.
162
261
  #
163
262
  # @return [nil] Write a message to STDOUT.
164
- #
165
- # @api public
166
263
  def self.pending(message)
167
264
  Clone::Dsl.pending(message)
168
265
  end
@@ -3,8 +3,6 @@
3
3
  module RSpec
4
4
  module Clone
5
5
  # Send log messages to the console.
6
- #
7
- # @api private
8
6
  module Console
9
7
  # @param report [::Expresenter::Pass] Passed expectation result presenter.
10
8
  #
@@ -16,7 +16,7 @@ module RSpec
16
16
  # Executes the given block before each spec in the current context runs.
17
17
  #
18
18
  # @example
19
- # require "r_spec/clone"
19
+ # require "r_spec"
20
20
  #
21
21
  # RSpec.describe Integer do
22
22
  # before do
@@ -42,6 +42,8 @@ module RSpec
42
42
  # # Success: expected to be 123.
43
43
  #
44
44
  # @param block [Proc] The content to execute at the class initialization.
45
+ #
46
+ # @api public
45
47
  def self.before(&block)
46
48
  define_method(BEFORE_METHOD) do
47
49
  super()
@@ -54,7 +56,7 @@ module RSpec
54
56
  # Executes the given block after each spec in the current context runs.
55
57
  #
56
58
  # @example
57
- # require "r_spec/clone"
59
+ # require "r_spec"
58
60
  #
59
61
  # RSpec.describe Integer do
60
62
  # after do
@@ -69,6 +71,8 @@ module RSpec
69
71
  # # That is the answer to everything.
70
72
  #
71
73
  # @param block [Proc] The content to execute at the class initialization.
74
+ #
75
+ # @api public
72
76
  def self.after(&block)
73
77
  define_method(AFTER_METHOD) do
74
78
  instance_exec(&block)
@@ -81,7 +85,7 @@ module RSpec
81
85
  # Sets a user-defined property.
82
86
  #
83
87
  # @example
84
- # require "r_spec/clone"
88
+ # require "r_spec"
85
89
  #
86
90
  # RSpec.describe "Name stories" do
87
91
  # let(:name) { "Bob" }
@@ -103,6 +107,8 @@ module RSpec
103
107
  # @param block [Proc] The content of the method to define.
104
108
  #
105
109
  # @return [Symbol] A private method that define the block content.
110
+ #
111
+ # @api public
106
112
  def self.let(name, *args, **kwargs, &block)
107
113
  raise Error::ReservedMethod if [BEFORE_METHOD, AFTER_METHOD].include?(name.to_sym)
108
114
 
@@ -112,7 +118,7 @@ module RSpec
112
118
  # Sets a user-defined property named {#subject}.
113
119
  #
114
120
  # @example
115
- # require "r_spec/clone"
121
+ # require "r_spec"
116
122
  #
117
123
  # RSpec.describe Array do
118
124
  # subject { [1, 2, 3] }
@@ -120,13 +126,23 @@ module RSpec
120
126
  # it "has the prescribed elements" do
121
127
  # expect(subject).to eq([1, 2, 3])
122
128
  # end
129
+ #
130
+ # it { is_expected.to be_an_instance_of described_class }
131
+ #
132
+ # its(:size) { is_expected.to be 3 }
133
+ # its(:downcase) { is_expected.to raise_exception NoMethodError }
123
134
  # end
124
135
  #
125
136
  # # Output to the console
126
137
  # # Success: expected to eq [1, 2, 3].
138
+ # # Success: expected [1, 2, 3] to be an instance of Array.
139
+ # # Success: expected to be 3.
140
+ # # Success: undefined method `downcase' for [1, 2, 3]:Array.
127
141
  #
128
142
  # @param block [Proc] The subject to set.
129
143
  # @return [Symbol] A {#subject} method that define the block content.
144
+ #
145
+ # @api public
130
146
  def self.subject(&block)
131
147
  let(__method__, &block)
132
148
  end
@@ -134,7 +150,7 @@ module RSpec
134
150
  # Defines an example group that describes a unit to be tested.
135
151
  #
136
152
  # @example
137
- # require "r_spec/clone"
153
+ # require "r_spec"
138
154
  #
139
155
  # RSpec.describe String do
140
156
  # describe "+" do
@@ -147,17 +163,62 @@ module RSpec
147
163
  #
148
164
  # @param const [Module, String] A module to include in block context.
149
165
  # @param block [Proc] The block to define the specs.
166
+ #
167
+ # @api public
150
168
  def self.describe(const, &block)
151
169
  desc = ::Class.new(self)
152
170
  desc.let(:described_class) { const } if const.is_a?(::Module)
153
- fork! { desc.instance_eval(&block) }
171
+ desc.instance_eval(&block)
154
172
  end
155
173
 
174
+ # :nocov:
175
+
176
+ # Runs a describe example group in a subprocess to isolate side effects.
177
+ #
178
+ # @example
179
+ # $app = "foo"
180
+ #
181
+ # require "r_spec"
182
+ #
183
+ # RSpec.describe "Scoped side effects" do
184
+ # describe! "#gsub!" do
185
+ # before do
186
+ # $app.gsub!("o", "0")
187
+ # end
188
+ #
189
+ # context! "when isolated in the context" do
190
+ # before do
191
+ # $app.gsub!("f", "F")
192
+ # end
193
+ #
194
+ # it { expect($app).to eq "F00" }
195
+ # end
196
+ #
197
+ # it { expect($app).to eq "f00" }
198
+ # end
199
+ #
200
+ # it { expect($app).to eq "foo" }
201
+ # end
202
+ #
203
+ # # Output to the console
204
+ # # Success: expected to eq "F00".
205
+ # # Success: expected to eq "f00".
206
+ # # Success: expected to eq "foo".
207
+ #
208
+ # @param (see #describe)
209
+ #
210
+ # @api public
211
+ def self.describe!(const, &block)
212
+ fork! { describe(const, &block) }
213
+ end
214
+
215
+ # :nocov:
216
+
156
217
  # Defines an example group that establishes a specific context, like
157
218
  # _empty array_ versus _array with elements_.
158
219
  #
159
220
  # @example
160
- # require "r_spec/clone"
221
+ # require "r_spec"
161
222
  #
162
223
  # RSpec.describe "web resource" do
163
224
  # context "when resource is not found" do
@@ -176,17 +237,63 @@ module RSpec
176
237
  # @param _description [String] A description that usually begins with
177
238
  # "when", "with" or "without".
178
239
  # @param block [Proc] The block to define the specs.
240
+ #
241
+ # @api public
179
242
  def self.context(_description, &block)
180
243
  desc = ::Class.new(self)
181
- fork! { desc.instance_eval(&block) }
244
+ desc.instance_eval(&block)
245
+ end
246
+
247
+ # :nocov:
248
+
249
+ # Runs a context example group in a subprocess to isolate side effects.
250
+ #
251
+ # @example
252
+ # app = "Hello, world!"
253
+ #
254
+ # require "r_spec"
255
+ #
256
+ # RSpec.describe String do
257
+ # subject do
258
+ # app
259
+ # end
260
+ #
261
+ # before do
262
+ # subject.gsub!("world", person)
263
+ # end
264
+ #
265
+ # context! "when Alice is greeted" do
266
+ # let(:person) { "Alice" }
267
+ #
268
+ # it { is_expected.to eq "Hello, Alice!" }
269
+ # end
270
+ #
271
+ # context! "when Bob is greeted" do
272
+ # let(:person) { "Bob" }
273
+ #
274
+ # it { is_expected.to eq "Hello, Bob!" }
275
+ # end
276
+ # end
277
+ #
278
+ # # Output to the console
279
+ # # Success: expected to eq "Hello, Alice!".
280
+ # # Success: expected to eq "Hello, Bob!".
281
+ #
282
+ # @param (see #context)
283
+ #
284
+ # @api public
285
+ def self.context!(description, &block)
286
+ fork! { context(description, &block) }
182
287
  end
183
288
 
289
+ # :nocov:
290
+
184
291
  # Defines a concrete test case.
185
292
  #
186
293
  # The test is performed by the block supplied to `&block`.
187
294
  #
188
295
  # @example The integer after 41
189
- # require "r_spec/clone"
296
+ # require "r_spec"
190
297
  #
191
298
  # RSpec.describe Integer do
192
299
  # it { expect(41.next).to be 42 }
@@ -196,7 +303,7 @@ module RSpec
196
303
  # # Success: expected to be 42.
197
304
  #
198
305
  # @example A division by zero
199
- # require "r_spec/clone"
306
+ # require "r_spec"
200
307
  #
201
308
  # RSpec.describe Integer do
202
309
  # subject { 41 }
@@ -219,17 +326,54 @@ module RSpec
219
326
  #
220
327
  # @raise (see ExpectationTarget::Base#result)
221
328
  # @return (see ExpectationTarget::Base#result)
329
+ #
330
+ # @api public
222
331
  def self.it(_name = nil, &block)
223
- example = ::Class.new(self) { include ExpectationHelper::It }.new
224
- fork! { run(example, &block) }
332
+ run(example_without_attribute.new, &block)
333
+ end
334
+
335
+ # :nocov:
336
+
337
+ # Runs a concrete test case in a subprocess to isolate side effects.
338
+ #
339
+ # @example
340
+ # app = "foo"
341
+ #
342
+ # require "r_spec"
343
+ #
344
+ # RSpec.describe "Side effects per example" do
345
+ # it! "runs the example in isolation" do
346
+ # expect { app.gsub!("foo", "bar") }.to eq "bar"
347
+ # expect(app).to eq "bar"
348
+ # end
349
+ #
350
+ # it "runs the example" do
351
+ # expect(app).to eq "foo"
352
+ # end
353
+ # end
354
+ #
355
+ # # Output to the console
356
+ # # Success: expected to eq "bar".
357
+ # # Success: expected to eq "bar".
358
+ # # Success: expected to eq "foo".
359
+ #
360
+ # @param (see #it)
361
+ #
362
+ # @raise (see ExpectationTarget::Base#result)
363
+ # @return (see ExpectationTarget::Base#result)
364
+ #
365
+ # @api public
366
+ def self.it!(name = nil, &block)
367
+ fork! { it(name, &block) }
225
368
  end
226
369
 
227
- # Use the {.its} method to define a single spec that specifies the actual
228
- # value of an attribute of the subject using
229
- # {ExpectationHelper::Its#is_expected}.
370
+ # :nocov:
371
+
372
+ # Defines a single concrete test case that specifies the actual value of
373
+ # an attribute of the subject using {ExpectationHelper::Its#is_expected}.
230
374
  #
231
375
  # @example The integer after 41
232
- # require "r_spec/clone"
376
+ # require "r_spec"
233
377
  #
234
378
  # RSpec.describe Integer do
235
379
  # subject { 41 }
@@ -241,7 +385,7 @@ module RSpec
241
385
  # # Success: expected to be 42.
242
386
  #
243
387
  # @example A division by zero
244
- # require "r_spec/clone"
388
+ # require "r_spec"
245
389
  #
246
390
  # RSpec.describe Integer do
247
391
  # subject { 41 }
@@ -253,10 +397,10 @@ module RSpec
253
397
  # # Success: divided by 0.
254
398
  #
255
399
  # @example A spec without subject
256
- # require "r_spec/clone"
400
+ # require "r_spec"
257
401
  #
258
402
  # RSpec.describe Integer do
259
- # its(:boom) { is_expected.to raise_exception RSpec::Error::UndefinedSubject }
403
+ # its(:abs) { is_expected.to raise_exception RSpec::Clone::Error::UndefinedSubject }
260
404
  # end
261
405
  #
262
406
  # # Output to the console
@@ -269,25 +413,57 @@ module RSpec
269
413
  #
270
414
  # @raise (see ExpectationTarget::Base#result)
271
415
  # @return (see ExpectationTarget::Base#result)
416
+ #
417
+ # @api public
272
418
  def self.its(attribute, *args, **kwargs, &block)
273
- example = ::Class.new(self) do
274
- include ExpectationHelper::Its
419
+ run(example_with_attribute(attribute, *args, **kwargs).new, &block)
420
+ end
275
421
 
276
- define_method(:actual) do
277
- subject.public_send(attribute, *args, **kwargs)
278
- end
279
- end.new
422
+ # :nocov:
280
423
 
281
- fork! { run(example, &block) }
424
+ # Runs a single concrete test case in a subprocess to isolate side
425
+ # effects.
426
+ #
427
+ # @example
428
+ # app = "foo"
429
+ #
430
+ # require "r_spec"
431
+ #
432
+ # RSpec.describe "Isolated side effect" do
433
+ # subject do
434
+ # app
435
+ # end
436
+ #
437
+ # its!(:upcase) { is_expected.to eq "FOO" }
438
+ #
439
+ # it "tests the original value" do
440
+ # expect(app).to eq "foo"
441
+ # end
442
+ # end
443
+ #
444
+ # # Output to the console
445
+ # # Success: expected to eq "FOO".
446
+ # # Success: expected to eq "foo".
447
+ #
448
+ # @param (see #it)
449
+ #
450
+ # @raise (see ExpectationTarget::Base#result)
451
+ # @return (see ExpectationTarget::Base#result)
452
+ #
453
+ # @api public
454
+ def self.its!(attribute, *args, **kwargs, &block)
455
+ fork! { its(attribute, *args, **kwargs, &block) }
282
456
  end
283
457
 
458
+ # :nocov:
459
+
284
460
  # Defines a pending test case.
285
461
  #
286
462
  # `&block` is never evaluated. It can be used to describe behaviour that
287
463
  # is not yet implemented.
288
464
  #
289
465
  # @example
290
- # require "r_spec/clone"
466
+ # require "r_spec"
291
467
  #
292
468
  # RSpec.describe "an example" do
293
469
  # pending "is implemented but waiting" do
@@ -310,6 +486,25 @@ module RSpec
310
486
  Console.passed_spec Error::PendingExpectation.result(message)
311
487
  end
312
488
 
489
+ # Example class for concrete test case.
490
+ def self.example_without_attribute
491
+ ::Class.new(self) do
492
+ prepend ExpectationHelper::It
493
+ end
494
+ end
495
+
496
+ # Example class for concrete test case that specifies the actual value of
497
+ # an attribute of the subject.
498
+ def self.example_with_attribute(attribute, *args, **kwargs)
499
+ ::Class.new(self) do
500
+ prepend ExpectationHelper::Its
501
+
502
+ define_method(:actual) do
503
+ subject.public_send(attribute, *args, **kwargs)
504
+ end
505
+ end
506
+ end
507
+
313
508
  # Creates a subprocess and runs the block inside.
314
509
  def self.fork!(&block)
315
510
  pid = fork(&block)
@@ -329,15 +524,18 @@ module RSpec
329
524
  example&.send(AFTER_METHOD)
330
525
  end
331
526
 
332
- private_class_method :fork!, :run
527
+ private_class_method :example_without_attribute, :example_with_attribute, :fork!, :run
333
528
 
334
529
  private
335
530
 
531
+ # If the first argument to a {.describe} definition is a class (or a
532
+ # module), this method will be overridden to return it.
336
533
  def described_class
337
534
  raise Error::UndefinedDescribedClass,
338
535
  "the first argument to at least one example group must be a module"
339
536
  end
340
537
 
538
+ # If a subject is defined, this method will be overridden to return it.
341
539
  def subject
342
540
  raise Error::UndefinedSubject, "subject not explicitly defined"
343
541
  end
@@ -8,8 +8,6 @@ require_relative File.join("error", "undefined_subject")
8
8
  module RSpec
9
9
  module Clone
10
10
  # Namespace for exceptions.
11
- #
12
- # @api private
13
11
  module Error
14
12
  end
15
13
  end
@@ -6,8 +6,6 @@ module RSpec
6
6
  module Clone
7
7
  module Error
8
8
  # Exception for pending expectations.
9
- #
10
- # @api private
11
9
  class PendingExpectation < ::RuntimeError
12
10
  # @param message [String] The not implemented expectation description.
13
11
  #
@@ -4,8 +4,6 @@ module RSpec
4
4
  module Clone
5
5
  module Error
6
6
  # Exception for reserved methods.
7
- #
8
- # @api private
9
7
  class ReservedMethod < ::RuntimeError
10
8
  end
11
9
  end
@@ -4,8 +4,6 @@ module RSpec
4
4
  module Clone
5
5
  module Error
6
6
  # Exception for undefined described classes.
7
- #
8
- # @api private
9
7
  class UndefinedDescribedClass < ::RuntimeError
10
8
  end
11
9
  end
@@ -4,8 +4,6 @@ module RSpec
4
4
  module Clone
5
5
  module Error
6
6
  # Exception for undefined subjects.
7
- #
8
- # @api private
9
7
  class UndefinedSubject < ::RuntimeError
10
8
  end
11
9
  end
@@ -18,8 +18,8 @@ module RSpec
18
18
  # @return [Block, Value] The wrapped target of an expectation.
19
19
  #
20
20
  # @example
21
- # expect("foo") # => #<RSpec::ExpectationTarget::Value:0x00007fb6b823 @actual="foo">
22
- # expect { Boom } # => #<RSpec::ExpectationTarget::Block:0x00007fb6b826 @callable=#<Proc:0x00007fb6b826>>
21
+ # expect("foo") # => #<RSpec::Clone::ExpectationTarget::Value:0x00007f @actual="foo">
22
+ # expect { Boom } # => #<RSpec::Clone::ExpectationTarget::Block:0x00007f @callable=#<Proc:0x00007f>>
23
23
  #
24
24
  # @api public
25
25
  def expect(value = self.class.superclass, &block)
@@ -31,7 +31,7 @@ module RSpec
31
31
  # @return [Block] The wrapped target of an expectation.
32
32
  #
33
33
  # @example
34
- # is_expected # => #<RSpec::ExpectationTarget::Block:0x00007fb6b8263df8 @callable=#<Proc:0x00007fb6b8263e20>>
34
+ # is_expected # => #<RSpec::Clone::ExpectationTarget::Block:0x00007fb6b8 @callable=#<Proc:0x00007fb6b8>>
35
35
  #
36
36
  # @api public
37
37
  def is_expected
@@ -15,7 +15,7 @@ module RSpec
15
15
  # @return [Block] The wrapped target of an expectation.
16
16
  #
17
17
  # @example
18
- # is_expected # => #<RSpec::ExpectationTarget::Block:0x00007fb6b8263df8 @callable=#<Proc:0x00007fb6b8263e20>>
18
+ # is_expected # => #<RSpec::Clone::ExpectationTarget::Block:0x00007f @callable=#<Proc:0x00007f>>
19
19
  #
20
20
  # @api public
21
21
  def is_expected
@@ -1,16 +1,15 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require "matchi/rspec"
4
-
5
- require_relative File.join("..", "error", "pending_expectation")
4
+ require "matchi/helper"
6
5
 
7
6
  module RSpec
8
7
  module Clone
9
8
  module ExpectationHelper
10
9
  # Abstract expectation helper base module.
11
10
  #
12
- # This module defines a number of methods to create expectations, which are
13
- # automatically included into examples.
11
+ # This module defines a number of methods to create expectations, which
12
+ # are automatically included into examples.
14
13
  #
15
14
  # It also includes a collection of expectation matchers 🤹
16
15
  #
@@ -6,12 +6,10 @@ require_relative File.join("expectation_target", "value")
6
6
  module RSpec
7
7
  module Clone
8
8
  # Wraps the target of an expectation.
9
- #
10
- # @api private
11
9
  module ExpectationTarget
12
10
  # @param undefined_value A sentinel value to be able to tell when the user
13
- # did not pass an argument. We can't use `nil` for that because `nil` is a
14
- # valid value to pass.
11
+ # did not pass an argument. We can't use `nil` for that because `nil` is
12
+ # a valid value to pass.
15
13
  # @param value [#object_id, nil] An actual value.
16
14
  # @param block [#call, nil] A code to evaluate.
17
15
  #
@@ -10,14 +10,14 @@ module RSpec
10
10
  module ExpectationTarget
11
11
  # Abstract expectation target base class.
12
12
  #
13
- # @note `RSpec::ExpectationTarget::Base` is not intended to be instantiated
14
- # directly by users. Use `expect` instead.
13
+ # @note `RSpec::Clone::ExpectationTarget::Base` is not intended to be
14
+ # instantiated directly by users. Use `expect` instead.
15
15
  class Base
16
16
  # Instantiate a new expectation target.
17
17
  #
18
- # @param actual [#object_id] The actual value of the code to evaluate.
19
- def initialize(actual)
20
- @actual = actual
18
+ # @param input [#object_id, Proc] The code to evaluate.
19
+ def initialize(input)
20
+ @input = input
21
21
  end
22
22
 
23
23
  # Runs the given expectation, passing if `matcher` returns true.
@@ -52,6 +52,36 @@ module RSpec
52
52
 
53
53
  protected
54
54
 
55
+ # @param test [::TestTube::Base] The state of the experiment.
56
+ # @param matcher [#matches?] The matcher.
57
+ # @param negate [Boolean] The assertion is positive or negative.
58
+ #
59
+ # @return [nil] Write a message to STDOUT.
60
+ #
61
+ # @raise [SystemExit] Terminate execution immediately by calling
62
+ # `Kernel.exit(false)` with a failure message written to STDERR.
63
+ def absolute_requirement(test, matcher:, negate:)
64
+ result(
65
+ passed?(test),
66
+ actual: test.actual,
67
+ error: test.error,
68
+ got: test.got,
69
+ matcher: matcher,
70
+ negate: negate
71
+ )
72
+ end
73
+
74
+ # Code experiment result.
75
+ #
76
+ # @param test [::TestTube::Base] The state of the experiment.
77
+ #
78
+ # @see https://github.com/fixrb/test_tube
79
+ #
80
+ # @return [Boolean] The result of the test (passed or failed).
81
+ def passed?(test)
82
+ test.got.equal?(true)
83
+ end
84
+
55
85
  # @param passed [Boolean] The high expectation passed or failed.
56
86
  # @param actual [#object_id] The actual value.
57
87
  # @param error [Exception, nil] Any raised exception.
@@ -63,8 +93,6 @@ module RSpec
63
93
  #
64
94
  # @raise [SystemExit] Terminate execution immediately by calling
65
95
  # `Kernel.exit(false)` with a failure message written to STDERR.
66
- #
67
- # @api private
68
96
  def result(passed, actual:, error:, got:, matcher:, negate:)
69
97
  Console.passed_spec ::Expresenter.call(passed).with(
70
98
  actual: actual,
@@ -16,31 +16,20 @@ module RSpec
16
16
  # # with `not_to`
17
17
  # expect { actual }.not_to be(4)
18
18
  #
19
- # @note `RSpec::ExpectationTarget::Block` is not intended to be instantiated
20
- # directly by users. Use `expect` instead.
19
+ # @note `RSpec::Clone::ExpectationTarget::Block` is not intended to be
20
+ # instantiated directly by users. Use `expect` instead.
21
21
  class Block < Base
22
22
  protected
23
23
 
24
24
  # @param matcher [#matches?] The matcher.
25
25
  # @param negate [Boolean] The assertion is positive or negative.
26
26
  #
27
- # @return [nil] Write a message to STDOUT.
27
+ # @return (see Base#absolute_requirement)
28
28
  #
29
- # @raise [SystemExit] Terminate execution immediately by calling
30
- # `Kernel.exit(false)` with a failure message written to STDERR.
29
+ # @raise (see Base#absolute_requirement)
31
30
  def absolute_requirement(matcher:, negate:)
32
- experiment = ::TestTube.invoke(
33
- @actual,
34
- isolation: false,
35
- matcher: matcher,
36
- negate: negate
37
- )
38
-
39
- result(
40
- experiment.got.equal?(true),
41
- actual: experiment.actual,
42
- error: experiment.error,
43
- got: experiment.got,
31
+ super(
32
+ ::TestTube.invoke(isolation: false, matcher: matcher, negate: negate, &@input),
44
33
  matcher: matcher,
45
34
  negate: negate
46
35
  )
@@ -16,30 +16,20 @@ module RSpec
16
16
  # # with `not_to`
17
17
  # expect(actual).not_to be(4)
18
18
  #
19
- # @note `RSpec::ExpectationTarget::Value` is not intended to be instantiated
20
- # directly by users. Use `expect` instead.
19
+ # @note `RSpec::Clone::ExpectationTarget::Value` is not intended to be
20
+ # instantiated directly by users. Use `expect` instead.
21
21
  class Value < Base
22
22
  protected
23
23
 
24
24
  # @param matcher [#matches?] The matcher.
25
25
  # @param negate [Boolean] The assertion is positive or negative.
26
26
  #
27
- # @return [nil] Write a message to STDOUT.
27
+ # @return (see Base#absolute_requirement)
28
28
  #
29
- # @raise [SystemExit] Terminate execution immediately by calling
30
- # `Kernel.exit(false)` with a failure message written to STDERR.
29
+ # @raise (see Base#absolute_requirement)
31
30
  def absolute_requirement(matcher:, negate:)
32
- experiment = ::TestTube.pass(
33
- @actual,
34
- matcher: matcher,
35
- negate: negate
36
- )
37
-
38
- result(
39
- experiment.got.equal?(true),
40
- actual: experiment.actual,
41
- error: experiment.error,
42
- got: experiment.got,
31
+ super(
32
+ ::TestTube.pass(@input, matcher: matcher, negate: negate),
43
33
  matcher: matcher,
44
34
  negate: negate
45
35
  )
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: r_spec-clone
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.1.0
4
+ version: 1.2.3
5
5
  platform: ruby
6
6
  authors:
7
7
  - Cyril Kato
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2021-06-30 00:00:00.000000000 Z
11
+ date: 2021-07-15 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: expresenter
@@ -30,28 +30,28 @@ dependencies:
30
30
  requirements:
31
31
  - - "~>"
32
32
  - !ruby/object:Gem::Version
33
- version: 1.1.2
33
+ version: 1.2.0
34
34
  type: :runtime
35
35
  prerelease: false
36
36
  version_requirements: !ruby/object:Gem::Requirement
37
37
  requirements:
38
38
  - - "~>"
39
39
  - !ruby/object:Gem::Version
40
- version: 1.1.2
40
+ version: 1.2.0
41
41
  - !ruby/object:Gem::Dependency
42
42
  name: test_tube
43
43
  requirement: !ruby/object:Gem::Requirement
44
44
  requirements:
45
45
  - - "~>"
46
46
  - !ruby/object:Gem::Version
47
- version: 1.1.0
47
+ version: 2.0.0
48
48
  type: :runtime
49
49
  prerelease: false
50
50
  version_requirements: !ruby/object:Gem::Requirement
51
51
  requirements:
52
52
  - - "~>"
53
53
  - !ruby/object:Gem::Version
54
- version: 1.1.0
54
+ version: 2.0.0
55
55
  - !ruby/object:Gem::Dependency
56
56
  name: bundler
57
57
  requirement: !ruby/object:Gem::Requirement