rspec-given 2.3.0 → 2.3.1.beta.1
Sign up to get free protection for your applications and to get access to all the features.
- data/README.md +56 -49
- data/Rakefile +7 -0
- data/examples/example_helper.rb +1 -1
- data/examples/integration/then_spec.rb +1 -1
- data/lib/rspec/given/extensions.rb +3 -0
- data/lib/rspec/given/have_failed.rb +2 -0
- data/lib/rspec/given/module_methods.rb +9 -0
- data/lib/rspec/given/monkey.rb +1 -0
- data/lib/rspec/given/natural_assertion.rb +9 -4
- data/lib/rspec/given/rspec1_given.rb +2 -1
- data/lib/rspec/given/version.rb +2 -1
- metadata +5 -21
data/README.md
CHANGED
@@ -1,6 +1,6 @@
|
|
1
1
|
# rspec-given
|
2
2
|
|
3
|
-
Covering rspec-given, version 2.3.
|
3
|
+
Covering rspec-given, version 2.3.1.beta.1.
|
4
4
|
|
5
5
|
rspec-given is an RSpec extension to allow Given/When/Then notation in
|
6
6
|
RSpec specifications. It is a natural extension of the experimental
|
@@ -17,7 +17,7 @@ RSpec specifications.
|
|
17
17
|
|
18
18
|
## Status
|
19
19
|
|
20
|
-
|
20
|
+
rspec-given is ready for production use.
|
21
21
|
|
22
22
|
## Example
|
23
23
|
|
@@ -118,7 +118,7 @@ for side effects. Since there is no accessor, the code block is
|
|
118
118
|
executed immediately (i.e. no lazy evaluation).
|
119
119
|
|
120
120
|
The preconditions are run in order of definition. Nested contexts
|
121
|
-
will inherit the preconditions from the enclosing context, with
|
121
|
+
will inherit the preconditions from the enclosing context, with outer
|
122
122
|
preconditions running before inner preconditions.
|
123
123
|
|
124
124
|
#### Given examples:
|
@@ -127,8 +127,8 @@ preconditions running before inner preconditions.
|
|
127
127
|
Given(:stack) { Stack.new }
|
128
128
|
```
|
129
129
|
|
130
|
-
The block for the given clause is lazily run
|
131
|
-
|
130
|
+
The block for the given clause is lazily run and its value bound to
|
131
|
+
'stack' if 'stack' is ever referenced in the test.
|
132
132
|
The first reference to 'stack' in the specification will cause the
|
133
133
|
code block to execute. Futher references to 'stack' will reuse the
|
134
134
|
previously generated value.
|
@@ -259,7 +259,7 @@ be empty. If it is not empty, the test will fail.
|
|
259
259
|
|
260
260
|
The _And_ clause is similar to _Then_, but does not form its own RSpec
|
261
261
|
example. This means that _And_ clauses reuse the setup from a sibling
|
262
|
-
_Then_ clause. Using a single _Then_
|
262
|
+
_Then_ clause. Using a single _Then_ and multiple _And_ clauses in an
|
263
263
|
example group means the setup for that group is run only once (for the
|
264
264
|
_Then_ clause) and reused for all the _And_ clauses. This can be a
|
265
265
|
significant speed savings where the setup for an example group is
|
@@ -267,30 +267,30 @@ expensive.
|
|
267
267
|
|
268
268
|
Some things to keep in mind about _And_ clauses:
|
269
269
|
|
270
|
-
|
271
|
-
|
272
|
-
|
270
|
+
* There must be at least one _Then_ in the example group and it must
|
271
|
+
be declared before the _And_ clauses. Forgetting the _Then_ clause
|
272
|
+
is an error.
|
273
273
|
|
274
|
-
|
275
|
-
|
274
|
+
* The code in the _And_ clause is run immediately after the first
|
275
|
+
(executed) _Then_ of an example group.
|
276
276
|
|
277
|
-
|
278
|
-
|
277
|
+
* An assertion failure in a _Then_ clause or an _And_ clause will
|
278
|
+
cause all the subsequent _And_ clauses to be skipped.
|
279
279
|
|
280
|
-
|
281
|
-
|
282
|
-
|
283
|
-
|
284
|
-
|
280
|
+
* Since _And_ clauses do not form their own RSpec examples, they are
|
281
|
+
not represented in the formatted output of RSpec. That means _And_
|
282
|
+
clauses do not produce dots in the Progress format, nor do they
|
283
|
+
appear in the documentation, html or textmate formats (options
|
284
|
+
-fhtml, -fdoc, or -ftextmate).
|
285
285
|
|
286
|
-
|
287
|
-
|
288
|
-
|
286
|
+
* Like _Then_ clauses, _And_ clauses must be idempotent. That means
|
287
|
+
they should not execute any code that changes global program state.
|
288
|
+
(See the section on the _Then_ clause).
|
289
289
|
|
290
290
|
The choice to use an _And_ clause is primarily a speed consideration.
|
291
291
|
If an example group has expensive setup and there are a lot of _Then_
|
292
292
|
clauses, then choosing to make some of the _Then_ clauses into _And_
|
293
|
-
|
293
|
+
clauses will speed up the spec. Otherwise it is probably better to
|
294
294
|
stick with _Then_ clauses.
|
295
295
|
|
296
296
|
#### Then/And examples:
|
@@ -326,18 +326,19 @@ used in contexts that define that accessor.
|
|
326
326
|
|
327
327
|
Notes:
|
328
328
|
|
329
|
-
|
330
|
-
|
331
|
-
|
329
|
+
* Since Invariants do not form their own RSpec example, they are not
|
330
|
+
represented in the RSpec formatted output (e.g. the '--format html'
|
331
|
+
option).
|
332
332
|
|
333
333
|
## Execution Ordering
|
334
334
|
|
335
335
|
When running the test for a specific _Then_ clause, the following will
|
336
336
|
be true:
|
337
337
|
|
338
|
-
* The _Given_ clauses will be run in the order that they are
|
338
|
+
* The non-lazy _Given_ clauses will be run in the order that they are
|
339
339
|
specified, from the outermost scope to the innermost scope
|
340
|
-
containing the _Then_.
|
340
|
+
containing the _Then_. (The lazy _Given_ clauses will be run upon
|
341
|
+
demand).
|
341
342
|
|
342
343
|
* All of the _Given_ clauses in all of the relevant scopes will run
|
343
344
|
before the first (outermost) _When_ clause in those same scopes.
|
@@ -347,21 +348,22 @@ be true:
|
|
347
348
|
|
348
349
|
* _When_ clauses and RSpec _before_ blocks will be executed in the
|
349
350
|
order that they are specified, from the outermost block to the
|
350
|
-
innermost block.
|
351
|
-
|
352
|
-
|
351
|
+
innermost block. This makes _before_ blocks an excellent choice when
|
352
|
+
writing narrative tests to specify actions that happen between the
|
353
|
+
"whens" of a narrative-style test.
|
353
354
|
|
354
355
|
Note that the ordering between _Given_ clauses and _before_ blocks are
|
355
|
-
|
356
|
-
|
357
|
-
|
358
|
-
the
|
359
|
-
order dependent code between _Given_
|
356
|
+
not strongly specified. Hoisting a _When_ clause out of an inner scope
|
357
|
+
to an outer scope may change the order of execution between related
|
358
|
+
_Given_ clauses and any _before_ blocks (hoisting the _When_ clause
|
359
|
+
might cause the related _Given_ clauses to possibly run earlier).
|
360
|
+
Because of this, do not split order dependent code between _Given_
|
361
|
+
clauses and _before_ blocks.
|
360
362
|
|
361
363
|
## Natural Assertions
|
362
364
|
|
363
|
-
**NOTE:** <em>Natural assertions are an experimental feature
|
364
|
-
RSpec/Given. They are currently disabled by default
|
365
|
+
**NOTE:** <em>Natural assertions are currently an experimental feature
|
366
|
+
of RSpec/Given. They are currently disabled by default, but can be
|
365
367
|
enabled by a simple configuration option (see "use_natural_assertions"
|
366
368
|
below).</em>
|
367
369
|
|
@@ -380,6 +382,10 @@ natural assertions:
|
|
380
382
|
Natural assertions must be enabled, either globally or on a per
|
381
383
|
context basis, to be recognized.
|
382
384
|
|
385
|
+
Here's a heads up: If you use natural assertions, but fail to enable
|
386
|
+
them, all your specs will mysteriously pass. This is why the **red**
|
387
|
+
part of _Red/Green/Refactor_ is so important.
|
388
|
+
|
383
389
|
### Failure Messages with Natural Assertions
|
384
390
|
|
385
391
|
Since natural assertions do not depend upon matchers, you don't get
|
@@ -418,26 +424,26 @@ broken down into subexpressions and values for each subexpression.
|
|
418
424
|
This gives you all the information you need to figure out exactly what
|
419
425
|
part of the expression is causing the failure.
|
420
426
|
|
421
|
-
Natural
|
427
|
+
Natural assertions will give additional information (e.g. "expected:
|
422
428
|
3 to equal: 2") for top level expressions involving any of the
|
423
429
|
comparison operators (==, !=, <, <=, >, >=) or matching operators (=~,
|
424
430
|
!~).
|
425
431
|
|
426
432
|
### Caveats on Natural Assertions
|
427
433
|
|
428
|
-
Keep the following in mind when using
|
434
|
+
Keep the following in mind when using natural assertions.
|
429
435
|
|
430
436
|
* Only a single expression/assertion per _Then_. The single expression
|
431
437
|
of the _Then_ block will be considered when determining pass/fail
|
432
438
|
for the assertion. If you _want_ to express a complex condition for
|
433
439
|
the _Then_, you need to use ||, && or some other logical operation
|
434
440
|
to join the conditions into a single expression (and the failure
|
435
|
-
message will
|
441
|
+
message will break down the values for each part).
|
436
442
|
|
437
443
|
* Then clauses need be **idempotent**. This is true in general, but it
|
438
|
-
is particularly important for
|
444
|
+
is particularly important for natural assertions to obey this
|
439
445
|
restriction. This means that assertions in a Then clause should not
|
440
|
-
change anything. Since the
|
446
|
+
change anything. Since the Natural Assertion error message contains
|
441
447
|
the values of all the subexpressions, the expression and its
|
442
448
|
subexpressions will be evaluated multiple times. If the Then clause
|
443
449
|
is not idempotent, you will get changing answers as the
|
@@ -458,8 +464,8 @@ initially return 1). But when the error message is formated, the
|
|
458
464
|
system reports that <code>ary.delete(1)</code> returns nil. You will
|
459
465
|
scratch your head over that for a good while.
|
460
466
|
|
461
|
-
Instead, move the state changing code into a
|
462
|
-
assert what you need about
|
467
|
+
Instead, move the state changing code into a _When(:result)_ block, then
|
468
|
+
assert what you need to about :result. Something
|
463
469
|
like this is good:
|
464
470
|
|
465
471
|
```ruby
|
@@ -510,7 +516,7 @@ when an assertion is not met. Natural assertions provide
|
|
510
516
|
self-explanatory failure messages for most things without requiring
|
511
517
|
any special matchers from the programmer.
|
512
518
|
|
513
|
-
In the rare case that some extra information would be
|
519
|
+
In the rare case that some extra information would be helpful, it is
|
514
520
|
useful to create special objects that respond to the == operator.
|
515
521
|
|
516
522
|
#### Asserting Nearly Equal
|
@@ -520,7 +526,7 @@ exactly equal, therefore it is useful to assert that two floating
|
|
520
526
|
point numbers are nearly equal.
|
521
527
|
|
522
528
|
For example, the following asserts that the square root of 10 is about
|
523
|
-
3.1523 with an accuracy of
|
529
|
+
3.1523 with an accuracy of 1 percent.
|
524
530
|
|
525
531
|
```ruby
|
526
532
|
Then { Math.sqrt(10) == about(3.1623).percent(1) }
|
@@ -562,7 +568,8 @@ For example, the following two Then clauses are equivalent:
|
|
562
568
|
|
563
569
|
### Processing Natural Assertions
|
564
570
|
|
565
|
-
When natural assertions are enabled, they are only used if
|
571
|
+
When natural assertions are enabled, they are only used if all of the
|
572
|
+
following are true:
|
566
573
|
|
567
574
|
1. The block does not throw an RSpec assertion failure (or any other
|
568
575
|
exception for that matter).
|
@@ -588,8 +595,8 @@ Conover](http://rubygems.org/profiles/sconoversf).
|
|
588
595
|
Just require 'rspec/given' in the spec helper of your project and it
|
589
596
|
is ready to go.
|
590
597
|
|
591
|
-
If the RSpec format option document, html or textmate
|
592
|
-
RSpec/Given will automatically add
|
598
|
+
If the RSpec format option document, html or textmate is chosen,
|
599
|
+
RSpec/Given will automatically add additional source code information to
|
593
600
|
the examples to produce better looking output. If you don't care about
|
594
601
|
the pretty output and wish to disable source code caching
|
595
602
|
unconditionally, then add the following line to your spec helper file:
|
data/Rakefile
CHANGED
@@ -93,6 +93,13 @@ task :verify_rspec2 do
|
|
93
93
|
end
|
94
94
|
end
|
95
95
|
|
96
|
+
task :load_check do
|
97
|
+
SRC_FILES = FileList['lib/rspec/given/*.rb'].exclude(/rspec1/)
|
98
|
+
SRC_FILES.each do |fn|
|
99
|
+
sh %{ruby -Ilib -e 'load "#{fn}"'}
|
100
|
+
end
|
101
|
+
end
|
102
|
+
|
96
103
|
# Formatting the README ----------------------------------------------
|
97
104
|
|
98
105
|
directory 'html'
|
data/examples/example_helper.rb
CHANGED
@@ -206,6 +206,8 @@ module RSpec
|
|
206
206
|
begin
|
207
207
|
_rg_establish_givens
|
208
208
|
instance_eval(&block)
|
209
|
+
rescue RSpec::Core::Pending::PendingDeclaredInExample => ex
|
210
|
+
raise
|
209
211
|
rescue Exception => ex
|
210
212
|
Failure.new(ex)
|
211
213
|
end
|
@@ -252,6 +254,7 @@ module RSpec
|
|
252
254
|
end
|
253
255
|
|
254
256
|
def use_natural_assertions(enabled=true)
|
257
|
+
RSpec::Given.ok_to_use_natural_assertions(enabled)
|
255
258
|
_rgc_context_info[:natural_assertions_enabled] = enabled
|
256
259
|
end
|
257
260
|
end
|
@@ -1,5 +1,7 @@
|
|
1
1
|
module RSpec
|
2
2
|
module Given
|
3
|
+
NATURAL_ASSERTIONS_SUPPORTED = ! defined?(JRUBY_VERSION)
|
4
|
+
|
3
5
|
def self.matcher_called
|
4
6
|
@matcher_called
|
5
7
|
end
|
@@ -22,9 +24,16 @@ module RSpec
|
|
22
24
|
end
|
23
25
|
|
24
26
|
def self.use_natural_assertions(enabled=true)
|
27
|
+
ok_to_use_natural_assertions(enabled)
|
25
28
|
@natural_assertions_enabled = enabled
|
26
29
|
end
|
27
30
|
|
31
|
+
def self.ok_to_use_natural_assertions(enabled)
|
32
|
+
if enabled && ! NATURAL_ASSERTIONS_SUPPORTED
|
33
|
+
fail ArgumentError, "Natural Assertions are disabled for JRuby"
|
34
|
+
end
|
35
|
+
end
|
36
|
+
|
28
37
|
def self.natural_assertions_enabled?
|
29
38
|
@natural_assertions_enabled
|
30
39
|
end
|
data/lib/rspec/given/monkey.rb
CHANGED
@@ -1,6 +1,11 @@
|
|
1
|
-
require '
|
2
|
-
require '
|
3
|
-
|
1
|
+
require 'rspec'
|
2
|
+
require 'rspec/given/module_methods'
|
3
|
+
|
4
|
+
if RSpec::Given::NATURAL_ASSERTIONS_SUPPORTED
|
5
|
+
require 'ripper'
|
6
|
+
require 'sorcerer'
|
7
|
+
require 'rspec/given/monkey'
|
8
|
+
end
|
4
9
|
|
5
10
|
module RSpec
|
6
11
|
module Given
|
@@ -160,7 +165,7 @@ module RSpec
|
|
160
165
|
width = suggest_width(pairs)
|
161
166
|
pairs.each do |x, v|
|
162
167
|
fmt = (v.size > WRAP_WIDTH) ?
|
163
|
-
|
168
|
+
" %-#{width+2}s\n #{' '*(width+2)} <- %s\n" :
|
164
169
|
" %-#{width+2}s <- %s\n"
|
165
170
|
@output << sprintf(fmt, v, x)
|
166
171
|
end
|
data/lib/rspec/given/version.rb
CHANGED
metadata
CHANGED
@@ -1,15 +1,15 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: rspec-given
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 2.3.
|
5
|
-
prerelease:
|
4
|
+
version: 2.3.1.beta.1
|
5
|
+
prerelease: 6
|
6
6
|
platform: ruby
|
7
7
|
authors:
|
8
8
|
- Jim Weirich
|
9
9
|
autorequire:
|
10
10
|
bindir: bin
|
11
11
|
cert_chain: []
|
12
|
-
date: 2013-01-
|
12
|
+
date: 2013-01-24 00:00:00.000000000 Z
|
13
13
|
dependencies:
|
14
14
|
- !ruby/object:Gem::Dependency
|
15
15
|
name: rspec
|
@@ -27,22 +27,6 @@ dependencies:
|
|
27
27
|
- - ! '>='
|
28
28
|
- !ruby/object:Gem::Version
|
29
29
|
version: '2.11'
|
30
|
-
- !ruby/object:Gem::Dependency
|
31
|
-
name: sorcerer
|
32
|
-
requirement: !ruby/object:Gem::Requirement
|
33
|
-
none: false
|
34
|
-
requirements:
|
35
|
-
- - ! '>='
|
36
|
-
- !ruby/object:Gem::Version
|
37
|
-
version: 0.3.7
|
38
|
-
type: :runtime
|
39
|
-
prerelease: false
|
40
|
-
version_requirements: !ruby/object:Gem::Requirement
|
41
|
-
none: false
|
42
|
-
requirements:
|
43
|
-
- - ! '>='
|
44
|
-
- !ruby/object:Gem::Version
|
45
|
-
version: 0.3.7
|
46
30
|
- !ruby/object:Gem::Dependency
|
47
31
|
name: bluecloth
|
48
32
|
requirement: !ruby/object:Gem::Requirement
|
@@ -154,9 +138,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
|
|
154
138
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
155
139
|
none: false
|
156
140
|
requirements:
|
157
|
-
- - ! '
|
141
|
+
- - ! '>'
|
158
142
|
- !ruby/object:Gem::Version
|
159
|
-
version:
|
143
|
+
version: 1.3.1
|
160
144
|
requirements: []
|
161
145
|
rubyforge_project: given
|
162
146
|
rubygems_version: 1.8.24
|