ae 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- data/HISTORY +12 -0
- data/LICENSE +677 -0
- data/MANIFEST +39 -0
- data/README +84 -0
- data/demo/01_overview.rdoc +97 -0
- data/demo/02_assertion.rdoc +1 -0
- data/demo/03_assert.rdoc +230 -0
- data/demo/04_subjunctive.rdoc +127 -0
- data/doc/qedoc/index.html +704 -0
- data/doc/qedoc/jquery.js +19 -0
- data/lib/ae.rb +7 -0
- data/lib/ae/assert.rb +57 -0
- data/lib/ae/assertion.rb +27 -0
- data/lib/ae/assertor.rb +104 -0
- data/lib/ae/core_ext.rb +202 -0
- data/lib/ae/subjunctive.rb +73 -0
- data/lib/ae/subjunctive/must.rb +48 -0
- data/lib/ae/subjunctive/should.rb +49 -0
- data/meta/authors +1 -0
- data/meta/contact +1 -0
- data/meta/created +1 -0
- data/meta/description +2 -0
- data/meta/homepage +1 -0
- data/meta/license +1 -0
- data/meta/package +1 -0
- data/meta/project +1 -0
- data/meta/released +1 -0
- data/meta/repository +1 -0
- data/meta/ruby +2 -0
- data/meta/summary +1 -0
- data/meta/title +1 -0
- data/meta/version +1 -0
- metadata +96 -0
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
= Subjunctives
|
|
2
|
+
|
|
3
|
+
Okay. I can hear the BDDers rumbling, "where's the 'should'?"
|
|
4
|
+
Well, AE has nothing against 'should', but there are different
|
|
5
|
+
approaches for utilizing should nomenclature in specifications,
|
|
6
|
+
and AE wants to be open to these techniques. One of which
|
|
7
|
+
it the way Shoulda (http://shoulda.rubyforge.org) utilizes
|
|
8
|
+
+should+ in a way analogous to RSpec's use of +it+.
|
|
9
|
+
|
|
10
|
+
Even so, AE provides a an optional mixin called Subjunctive which
|
|
11
|
+
can be used to create assertor methods using English subjunctive
|
|
12
|
+
terms such as +should+ (or +must+, +shall+ and +will+. Whatever you like.)
|
|
13
|
+
To load this library use:
|
|
14
|
+
|
|
15
|
+
require 'ae/subjunctive'
|
|
16
|
+
|
|
17
|
+
Then all that is required it to define your subjunctive method for all
|
|
18
|
+
objects. For example:
|
|
19
|
+
|
|
20
|
+
def will(*args, &block)
|
|
21
|
+
Assertor.new(self, :backtrace=>caller).be(*args,&block)
|
|
22
|
+
end
|
|
23
|
+
|
|
24
|
+
It's that easy. Because of their popularity AE provides two such terms,
|
|
25
|
+
+should+ and +must+ as optional add-ons.
|
|
26
|
+
|
|
27
|
+
require 'ae/subjunctive/should'
|
|
28
|
+
require 'ae/subjunctive/must'
|
|
29
|
+
|
|
30
|
+
We will use these two methods interchangeable for the rest of this
|
|
31
|
+
demonstration, but to be clear they both work exactly the same way,
|
|
32
|
+
and almost exactly like #assert.
|
|
33
|
+
|
|
34
|
+
Keep in mind, AE "conical" functionality does not entail subjunctive
|
|
35
|
+
forms, or +should+ or +must+ assertor methods. These are simply options
|
|
36
|
+
you can load via your test_helper.rb, or similar script, if you prefer
|
|
37
|
+
or need to support these nomenclatures.
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
== Fluent Notation and Antonyms
|
|
41
|
+
|
|
42
|
+
Like +assert+, +should+ and +must+ can be used as a higher order function.
|
|
43
|
+
|
|
44
|
+
4.should == 4
|
|
45
|
+
4.must == 4
|
|
46
|
+
|
|
47
|
+
With the antonym of +should!+ (read as "should not") or +shouldnt+, and for
|
|
48
|
+
+must+, +must!+ or +wont+.
|
|
49
|
+
|
|
50
|
+
4.should! == 5
|
|
51
|
+
4.shouldnt == 5
|
|
52
|
+
|
|
53
|
+
4.must! == 5
|
|
54
|
+
4.wont == 5
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
== To Be
|
|
58
|
+
|
|
59
|
+
On occasions where the English readability of a specification is
|
|
60
|
+
hindered, +be+ can be used.
|
|
61
|
+
|
|
62
|
+
StandardError.must.be.raised? do
|
|
63
|
+
unknown_method
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
The +be+ method is the same as +assert+ with the single exception
|
|
67
|
+
that it will compare a lone argument to the receiver using +equate?+,
|
|
68
|
+
unlike +assert+ which simply check to see that the argument evalutates
|
|
69
|
+
as true.
|
|
70
|
+
|
|
71
|
+
10.should.be 10
|
|
72
|
+
10.should.be 10.0
|
|
73
|
+
10.should.be Numeric
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
== Indefinite Articles
|
|
77
|
+
|
|
78
|
+
Addtional anglogic forms are 'a' and 'an', equivalent to 'be' except
|
|
79
|
+
that they use +case?+ instead of +equate?+,
|
|
80
|
+
|
|
81
|
+
"hi".must.be.a String
|
|
82
|
+
|
|
83
|
+
Otherwise they are interchangeble.
|
|
84
|
+
|
|
85
|
+
"hi".must.be.an.instance_of?(String)
|
|
86
|
+
|
|
87
|
+
The indefinite articles work well when a noun follow as an arguments.
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
palindrome = lambda{ |x| x == x.reverse }
|
|
91
|
+
|
|
92
|
+
"abracarba".must.be.a palindrome
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
== Verifying Object State
|
|
96
|
+
|
|
97
|
+
The block notation of the subjunctive form is similar to +assert+, with
|
|
98
|
+
the important exception that the block is is evaluated in the scope of the
|
|
99
|
+
receiver via #instance_eval, if no block parameter is designated.
|
|
100
|
+
This can be also be used to test the state of an object.
|
|
101
|
+
|
|
102
|
+
class X
|
|
103
|
+
attr :a
|
|
104
|
+
def initialize(a); @a = a; end
|
|
105
|
+
end
|
|
106
|
+
|
|
107
|
+
x = X.new(4)
|
|
108
|
+
|
|
109
|
+
x.must do
|
|
110
|
+
4 == @a
|
|
111
|
+
end
|
|
112
|
+
|
|
113
|
+
And should it fail...
|
|
114
|
+
|
|
115
|
+
Assertion.assert.raised? do
|
|
116
|
+
x.must do
|
|
117
|
+
5 == @a
|
|
118
|
+
end
|
|
119
|
+
end
|
|
120
|
+
|
|
121
|
+
For some this might seem controversial --to test underlying
|
|
122
|
+
implementation. And you will get no argument here, it should be used
|
|
123
|
+
thoughtfully, but there are occasions when such validations are
|
|
124
|
+
necessary.
|
|
125
|
+
|
|
126
|
+
QED.
|
|
127
|
+
|
|
@@ -0,0 +1,704 @@
|
|
|
1
|
+
<html>
|
|
2
|
+
<head>
|
|
3
|
+
<title>Assertive Expressive</title>
|
|
4
|
+
|
|
5
|
+
<style>
|
|
6
|
+
#container{ margin: 0 auto; width: 800px; }
|
|
7
|
+
|
|
8
|
+
/* Debug borders */
|
|
9
|
+
/* p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 { border: 1px solid red; } */
|
|
10
|
+
|
|
11
|
+
body { font-size: 16px; line-height: 20px; margin: 1em 5% 1em 5%; font-family: Verdana, Arial, Helvetica, sans-serif; }
|
|
12
|
+
a { color: #336; text-decoration: underline; }
|
|
13
|
+
a:visited { color: #334; }
|
|
14
|
+
em { font-style: italic; }
|
|
15
|
+
strong { font-weight: bold; }
|
|
16
|
+
tt { color: navy; }
|
|
17
|
+
|
|
18
|
+
h1, h2, h3, h4, h5, h6 { color: #223; margin-top: 1.2em; margin-bottom: 0.5em; line-height: 1.3; }
|
|
19
|
+
h1 { border-bottom: 2px solid silver; }
|
|
20
|
+
h2 { border-bottom: 2px solid silver; padding-top: 0.5em; }
|
|
21
|
+
|
|
22
|
+
hr { border: 1px solid silver; }
|
|
23
|
+
|
|
24
|
+
p { color: #222; text-align: justify; margin-top: 0.5em; margin-bottom: 0.5em; line-height: 1.4em; }
|
|
25
|
+
|
|
26
|
+
pre { padding: 10; margin: 0; font-family: monospace; font-size: 0.9em; }
|
|
27
|
+
pre.pass { color: green; }
|
|
28
|
+
pre.fail { color: red; }
|
|
29
|
+
pre.error { color: red; font-weight: bold; }
|
|
30
|
+
|
|
31
|
+
span#author { color: #527bbd; font-weight: bold; font-size: 1.1em; }
|
|
32
|
+
span#email { }
|
|
33
|
+
span#revision { }
|
|
34
|
+
|
|
35
|
+
div#footer { font-size: small; border-top: 2px solid silver; padding-top: 0.5em; margin-top: 4.0em; }
|
|
36
|
+
div#footer-text { float: left; padding-bottom: 0.5em; }
|
|
37
|
+
div#footer-badges { float: right; padding-bottom: 0.5em; }
|
|
38
|
+
|
|
39
|
+
/* Block element content. */
|
|
40
|
+
div.content { padding: 0; }
|
|
41
|
+
|
|
42
|
+
/* Block element titles. */
|
|
43
|
+
h1.title { font-weight: bold; text-align: left; font-size: 3em; margin-top: 1.0em; margin-bottom: 0.5em; }
|
|
44
|
+
|
|
45
|
+
/* Block element titles. */
|
|
46
|
+
div.title, caption.title { font-weight: bold; text-align: left; margin-top: 1.0em; margin-bottom: 0.5em; }
|
|
47
|
+
div.title + * { margin-top: 0; }
|
|
48
|
+
td div.title:first-child { margin-top: 0.0em; }
|
|
49
|
+
div.content div.title:first-child { margin-top: 0.0em; }
|
|
50
|
+
div.content + div.title { margin-top: 0.0em; }
|
|
51
|
+
div.sidebarblock > div.content { background: #ffffee; border: 1px solid silver; padding: 0.5em; }
|
|
52
|
+
|
|
53
|
+
img { border-style: none; }
|
|
54
|
+
|
|
55
|
+
dl { margin-top: 0.8em; margin-bottom: 0.8em; }
|
|
56
|
+
dt { margin-top: 0.5em; margin-bottom: 0; font-style: italic; }
|
|
57
|
+
dd > *:first-child { margin-top: 0; }
|
|
58
|
+
ul, ol { list-style-position: outside; }
|
|
59
|
+
|
|
60
|
+
thead { font-weight: bold; }
|
|
61
|
+
tfoot { font-weight: bold; }
|
|
62
|
+
</style>
|
|
63
|
+
|
|
64
|
+
<!-- TODO: only include if these files exists -->
|
|
65
|
+
<link href="../assets/styles/spec.css" type="text/css" rel="stylesheet">
|
|
66
|
+
<!-- spec.css might be a problem with clobber -->
|
|
67
|
+
<link href="spec.css" type="text/css" rel="stylesheet">
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
<!-- JQuery is needed -->
|
|
72
|
+
<script src="jquery.js" type="text/javascript" language="javascript"></script>
|
|
73
|
+
|
|
74
|
+
</head>
|
|
75
|
+
|
|
76
|
+
<body>
|
|
77
|
+
|
|
78
|
+
<!-- Side Table of Contents -->
|
|
79
|
+
<div id="sidebar" style="position: fixed; top: 10; right: 10; background: white;">
|
|
80
|
+
<a href="javascript: toc_toggle();">
|
|
81
|
+
<img src="img/icon/book.jpg" height="30px;" style="border: none;" alt="TOC" align="right"/>
|
|
82
|
+
</a>
|
|
83
|
+
|
|
84
|
+
<div id="toc_side" class="toc">
|
|
85
|
+
</div>
|
|
86
|
+
</div>
|
|
87
|
+
|
|
88
|
+
<div id="container">
|
|
89
|
+
<div id="header">
|
|
90
|
+
<img src="img/icon/book.jpg" align="left" style="padding-right: 10px;" alt=""/>
|
|
91
|
+
|
|
92
|
+
<h1 class="title">Assertive Expressive</h1>
|
|
93
|
+
|
|
94
|
+
<h1>Table of Contents</h1>
|
|
95
|
+
|
|
96
|
+
<div class="toc">
|
|
97
|
+
</div>
|
|
98
|
+
</div>
|
|
99
|
+
|
|
100
|
+
<div id="content">
|
|
101
|
+
<h1>Introduction</h1>
|
|
102
|
+
<p>
|
|
103
|
+
AE is an assertions framework for Ruby. It’s designed around the
|
|
104
|
+
concept of an Assertor. The Assertor is an Assertion Functor, or
|
|
105
|
+
Higher-Order Function, which reroutes method calls while monitoring them
|
|
106
|
+
for failing conditions.
|
|
107
|
+
</p>
|
|
108
|
+
<h2>What’s Provided</h2>
|
|
109
|
+
<p>
|
|
110
|
+
Requiring the AE library.
|
|
111
|
+
</p>
|
|
112
|
+
<pre>
|
|
113
|
+
require 'ae'
|
|
114
|
+
</pre>
|
|
115
|
+
<p>
|
|
116
|
+
Loads two classes, <tt>Assertion</tt> and <tt>Assertor</tt>, the Kernel
|
|
117
|
+
method <tt>assert</tt> and it’s ancillaries +assert!+ and
|
|
118
|
+
<tt>refute</tt> and a set of core extensions that make writing certain
|
|
119
|
+
types of assertions easier.
|
|
120
|
+
</p>
|
|
121
|
+
<h2>Assertion and Assertor Classes</h2>
|
|
122
|
+
<p>
|
|
123
|
+
The <tt>Assertion</tt> class is a subclass of <tt>Exception</tt>. It is the
|
|
124
|
+
error raised when an assertion fails.
|
|
125
|
+
</p>
|
|
126
|
+
<p>
|
|
127
|
+
The <tt>Assertion</tt> class is at the heart of AE. All other AE method
|
|
128
|
+
resolve by… The <tt>Assertion</tt> class is at subclass of Exception.
|
|
129
|
+
When an assertion is made, and fails, it is an instance of Assertion that
|
|
130
|
+
is raised.
|
|
131
|
+
</p>
|
|
132
|
+
<pre>
|
|
133
|
+
Assertion.assert.raised? do
|
|
134
|
+
msg = "my failure message"
|
|
135
|
+
assert false, msg
|
|
136
|
+
end
|
|
137
|
+
</pre>
|
|
138
|
+
<p>
|
|
139
|
+
Like any raised exception, the last Assertion message is available via
|
|
140
|
+
+$!+.
|
|
141
|
+
</p>
|
|
142
|
+
<p>
|
|
143
|
+
(FYI, in Test::Unit the equivalent class was called AssertionFailureError.
|
|
144
|
+
AE has adopted the shortened term for my fingers sake ;) Also, recently it
|
|
145
|
+
was discoverd to be the choosen term in minitest —proving good ideas
|
|
146
|
+
find their way to the top.)
|
|
147
|
+
</p>
|
|
148
|
+
<p>
|
|
149
|
+
Assertions themsevles are not generally used in creating tests or behavior
|
|
150
|
+
specifications. Rather they are used to create additonal types of assertion
|
|
151
|
+
methods.
|
|
152
|
+
</p>
|
|
153
|
+
<p>
|
|
154
|
+
As mentioned above the <tt>Assertor</tt> class is a type of Functor, or
|
|
155
|
+
Higher-Order function, which intercedes with a normal message invocation to
|
|
156
|
+
monitor for failed conditions, upon which is raises Assertion exceptions.
|
|
157
|
+
</p>
|
|
158
|
+
<h2>Assertion Methods</h2>
|
|
159
|
+
<p>
|
|
160
|
+
The three methods, <tt>assert</tt>, +assert!+ and <tt>refute</tt> all
|
|
161
|
+
return an Assertor instance when used fluidly, i.e. magic-dot notation,
|
|
162
|
+
higher-order notation, functor notation, whatever you prefer to call it.
|
|
163
|
+
</p>
|
|
164
|
+
<pre>
|
|
165
|
+
assert(Assertor === assert)
|
|
166
|
+
</pre>
|
|
167
|
+
<p>
|
|
168
|
+
This allows us to write statements like:
|
|
169
|
+
</p>
|
|
170
|
+
<pre>
|
|
171
|
+
1.assert == 1
|
|
172
|
+
</pre>
|
|
173
|
+
<p>
|
|
174
|
+
If the operation evaluates to false or nil, then an Assertion error is
|
|
175
|
+
raised.
|
|
176
|
+
</p>
|
|
177
|
+
<pre>
|
|
178
|
+
Assertion.assert.raised? do
|
|
179
|
+
1.assert == 2
|
|
180
|
+
end
|
|
181
|
+
</pre>
|
|
182
|
+
<p>
|
|
183
|
+
The methods +assert!+ and <tt>refute</tt> are just like <tt>assert</tt>
|
|
184
|
+
expect they purport the negative condition. Patterned after Ruby’s
|
|
185
|
+
own use of +!+ as meaning <tt>not</tt>, +assert!+ should be read
|
|
186
|
+
"assert not". While <tt>refute</tt> exists for the sake of those
|
|
187
|
+
that find the use of a "bang method" for this purpose unsuited to
|
|
188
|
+
them.
|
|
189
|
+
</p>
|
|
190
|
+
<h2>How It All Works</h2>
|
|
191
|
+
<p>
|
|
192
|
+
An Assertor essentially sits in wait for a method call (via
|
|
193
|
+
method_missing). When that happens it applies the method to the original
|
|
194
|
+
receiver, but wrapped in a clause that raises an Assertion should the
|
|
195
|
+
statement fail. If we wanted to be pedantic, we could write our assertions
|
|
196
|
+
like:
|
|
197
|
+
</p>
|
|
198
|
+
<pre>
|
|
199
|
+
raise Assertion.new("1 != 1") unless 1 == 1
|
|
200
|
+
</pre>
|
|
201
|
+
<p>
|
|
202
|
+
Instead of
|
|
203
|
+
</p>
|
|
204
|
+
<pre>
|
|
205
|
+
1.assert == 1
|
|
206
|
+
</pre>
|
|
207
|
+
<p>
|
|
208
|
+
Obviously using Assertor methods are whole lot more concise.
|
|
209
|
+
</p>
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
<h1>Assert Method</h1>
|
|
213
|
+
<h2>Compatible with Test::Unit</h2>
|
|
214
|
+
<p>
|
|
215
|
+
The +#assert+ method is designed to be backward compatible with the same
|
|
216
|
+
method in +Test::Unit+.
|
|
217
|
+
</p>
|
|
218
|
+
<p>
|
|
219
|
+
Using an argument, #assert will check that an argument evaluates to true.
|
|
220
|
+
Optionally one can send along a meaningful message should the assertion
|
|
221
|
+
fail.
|
|
222
|
+
</p>
|
|
223
|
+
<pre>
|
|
224
|
+
assert(true, "Not true!")
|
|
225
|
+
|
|
226
|
+
Assertion.assert.raised? do
|
|
227
|
+
assert(false, "Not true!")
|
|
228
|
+
end
|
|
229
|
+
</pre>
|
|
230
|
+
<h2>Assert with a Block</h2>
|
|
231
|
+
<p>
|
|
232
|
+
In addition #assert has been extended to accept a block. Like the case of
|
|
233
|
+
the argument, the block is expected to return something that evaluates as
|
|
234
|
+
true.
|
|
235
|
+
</p>
|
|
236
|
+
<pre>
|
|
237
|
+
assert do
|
|
238
|
+
true
|
|
239
|
+
end
|
|
240
|
+
|
|
241
|
+
Assertion.assert.raised? do
|
|
242
|
+
assert do
|
|
243
|
+
false
|
|
244
|
+
end
|
|
245
|
+
end
|
|
246
|
+
</pre>
|
|
247
|
+
<p>
|
|
248
|
+
We should also mention that, while probably not very useful, since the
|
|
249
|
+
arity of a block can be checked, one can also pass the receiver into the
|
|
250
|
+
block as a block argument.
|
|
251
|
+
</p>
|
|
252
|
+
<pre>
|
|
253
|
+
"hi".assert do |s|
|
|
254
|
+
/h/ =~ s
|
|
255
|
+
end
|
|
256
|
+
</pre>
|
|
257
|
+
<h2>Antonyms for Assert</h2>
|
|
258
|
+
<p>
|
|
259
|
+
We can state the opposite assertion using #assert!
|
|
260
|
+
</p>
|
|
261
|
+
<pre>
|
|
262
|
+
10.assert! == 9
|
|
263
|
+
</pre>
|
|
264
|
+
<p>
|
|
265
|
+
Or, because some people do not like the use of a bang method, +#refute+.
|
|
266
|
+
</p>
|
|
267
|
+
<pre>
|
|
268
|
+
10.refute == 9
|
|
269
|
+
</pre>
|
|
270
|
+
<p>
|
|
271
|
+
These terms can be used just as #assert is used in all examples, but with
|
|
272
|
+
the opposite inference.
|
|
273
|
+
</p>
|
|
274
|
+
<p>
|
|
275
|
+
Another way to get the opposite inference, is to use #not.
|
|
276
|
+
</p>
|
|
277
|
+
<pre>
|
|
278
|
+
10.assert.not == 9
|
|
279
|
+
</pre>
|
|
280
|
+
<h2>Identity Assertions</h2>
|
|
281
|
+
<p>
|
|
282
|
+
Rather then the general form:
|
|
283
|
+
</p>
|
|
284
|
+
<pre>
|
|
285
|
+
x = 10
|
|
286
|
+
x.assert.object_id == x.object_id
|
|
287
|
+
</pre>
|
|
288
|
+
<p>
|
|
289
|
+
We can use Ruby’s own +equal?+ method.
|
|
290
|
+
</p>
|
|
291
|
+
<pre>
|
|
292
|
+
x.assert.equal?(x)
|
|
293
|
+
</pre>
|
|
294
|
+
<p>
|
|
295
|
+
AE provides +identical?+ method as an alternative to make it a bit more
|
|
296
|
+
clear.
|
|
297
|
+
</p>
|
|
298
|
+
<pre>
|
|
299
|
+
x.assert.identical?(x)
|
|
300
|
+
</pre>
|
|
301
|
+
<h2>Equality Assertions</h2>
|
|
302
|
+
<p>
|
|
303
|
+
The most common assertion is that of value equality (+==_), as we have seen
|
|
304
|
+
throughout this document. But other forms of equality can be verified as
|
|
305
|
+
easily. We have already mentioned identity. In addition there is *Type
|
|
306
|
+
Equality*.
|
|
307
|
+
</p>
|
|
308
|
+
<pre>
|
|
309
|
+
17.assert.eql? 17
|
|
310
|
+
|
|
311
|
+
Assertion.assert.raised? do
|
|
312
|
+
17.assert.eql? 17.0
|
|
313
|
+
end
|
|
314
|
+
</pre>
|
|
315
|
+
<p>
|
|
316
|
+
And there is *Case Equality*.
|
|
317
|
+
</p>
|
|
318
|
+
<pre>
|
|
319
|
+
Numeric.assert === 3
|
|
320
|
+
</pre>
|
|
321
|
+
<h2>Checking Equality with a Block</h2>
|
|
322
|
+
<p>
|
|
323
|
+
Because operators can not take blocks, and at times blocks can be
|
|
324
|
+
convenient means of supplying a value to an assertion, AE has defined
|
|
325
|
+
alternate renditions of the equality methods. For equal? and eql?, the
|
|
326
|
+
method name remains the same, they simply can take a block instead of
|
|
327
|
+
argument if need be.
|
|
328
|
+
</p>
|
|
329
|
+
<p>
|
|
330
|
+
For *Value Equality*, +==+, the method is called +eq?+.
|
|
331
|
+
</p>
|
|
332
|
+
<pre>
|
|
333
|
+
10.assert.eq? do
|
|
334
|
+
10.0
|
|
335
|
+
end
|
|
336
|
+
</pre>
|
|
337
|
+
<p>
|
|
338
|
+
And should it fail…
|
|
339
|
+
</p>
|
|
340
|
+
<pre>
|
|
341
|
+
Assertion.assert.raised? do
|
|
342
|
+
10.assert.eq? do
|
|
343
|
+
20
|
|
344
|
+
end
|
|
345
|
+
end
|
|
346
|
+
</pre>
|
|
347
|
+
<p>
|
|
348
|
+
For *Case Equality, +===+, it is +case?+.
|
|
349
|
+
</p>
|
|
350
|
+
<pre>
|
|
351
|
+
Numeric.assert.case? do
|
|
352
|
+
"3".to_i
|
|
353
|
+
end
|
|
354
|
+
|
|
355
|
+
Assertion.assert.raised? do
|
|
356
|
+
Numeric.assert.case? do
|
|
357
|
+
"3"
|
|
358
|
+
end
|
|
359
|
+
end
|
|
360
|
+
</pre>
|
|
361
|
+
<h2>Exception Assertions</h2>
|
|
362
|
+
<p>
|
|
363
|
+
Validating errors is easy too, as has already been shown in the document to
|
|
364
|
+
verify assertion failures.
|
|
365
|
+
</p>
|
|
366
|
+
<pre>
|
|
367
|
+
StandardError.assert.raised? do
|
|
368
|
+
unknown_method
|
|
369
|
+
end
|
|
370
|
+
</pre>
|
|
371
|
+
<h2>Assertions on Object State</h2>
|
|
372
|
+
<p>
|
|
373
|
+
While testing or specifying the internal state of an object is generally
|
|
374
|
+
considered poor form, there are times when it is necessay. Assert combined
|
|
375
|
+
with <tt>instance_eval</tt> makes it easy too.
|
|
376
|
+
</p>
|
|
377
|
+
<pre>
|
|
378
|
+
class X
|
|
379
|
+
attr :a
|
|
380
|
+
def initialize(a); @a = a; end
|
|
381
|
+
end
|
|
382
|
+
|
|
383
|
+
x = X.new(1)
|
|
384
|
+
|
|
385
|
+
x.assert.instance_eval do
|
|
386
|
+
@a == 1
|
|
387
|
+
end
|
|
388
|
+
</pre>
|
|
389
|
+
<h2>Catch/Try Assertions</h2>
|
|
390
|
+
<p>
|
|
391
|
+
Catch/Try throws can be tested via +Symbol#thrown?+.
|
|
392
|
+
</p>
|
|
393
|
+
<pre>
|
|
394
|
+
:hookme.assert.thrown? do
|
|
395
|
+
throw :hookme
|
|
396
|
+
end
|
|
397
|
+
</pre>
|
|
398
|
+
<p>
|
|
399
|
+
Alternatively, a lambda containing the potential throw can be the receiver
|
|
400
|
+
using +throws?+.
|
|
401
|
+
</p>
|
|
402
|
+
<pre>
|
|
403
|
+
hook = lambda{ throw :hookme }
|
|
404
|
+
|
|
405
|
+
hook.assert.throws?(:hookme)
|
|
406
|
+
</pre>
|
|
407
|
+
<h2>Assertions on Proc Changes</h2>
|
|
408
|
+
<p>
|
|
409
|
+
I have to admit I’m not sure how this is useful, but I found it in
|
|
410
|
+
the Bacon API and ported it over just for sake of thoroughness.
|
|
411
|
+
</p>
|
|
412
|
+
<pre>
|
|
413
|
+
a = 0
|
|
414
|
+
|
|
415
|
+
l = lambda{ a }
|
|
416
|
+
|
|
417
|
+
l.assert.change?{ a +=1 }
|
|
418
|
+
</pre>
|
|
419
|
+
<h2>Assertion on literal True, False and Nil</h2>
|
|
420
|
+
<p>
|
|
421
|
+
Ruby already provides the #nil? method.
|
|
422
|
+
</p>
|
|
423
|
+
<pre>
|
|
424
|
+
nil.assert.nil?
|
|
425
|
+
</pre>
|
|
426
|
+
<p>
|
|
427
|
+
AE add true? and false? which acts accordingly.
|
|
428
|
+
</p>
|
|
429
|
+
<pre>
|
|
430
|
+
true.assert.true?
|
|
431
|
+
false.assert.false?
|
|
432
|
+
</pre>
|
|
433
|
+
<h2>Send Assertions</h2>
|
|
434
|
+
<p>
|
|
435
|
+
Assert that a method can be successfully called.
|
|
436
|
+
</p>
|
|
437
|
+
<pre>
|
|
438
|
+
"STRING".assert.send?(:upcase)
|
|
439
|
+
</pre>
|
|
440
|
+
<h2>Numeric Delta and Epsilon</h2>
|
|
441
|
+
<p>
|
|
442
|
+
You may wish to assert that a numeric value is with some range.
|
|
443
|
+
</p>
|
|
444
|
+
<pre>
|
|
445
|
+
3.in_delta?(1,5)
|
|
446
|
+
</pre>
|
|
447
|
+
<p>
|
|
448
|
+
Or minimum range.
|
|
449
|
+
</p>
|
|
450
|
+
<pre>
|
|
451
|
+
3.in_epsilon?(3,5)
|
|
452
|
+
</pre>
|
|
453
|
+
<h2>Custom Lambda Assertions</h2>
|
|
454
|
+
<p>
|
|
455
|
+
Passing a lambda to the subjunctive method, will use it as if it were a
|
|
456
|
+
block of the method. This allows for a simple way to quickly create
|
|
457
|
+
reusable assertions.
|
|
458
|
+
</p>
|
|
459
|
+
<pre>
|
|
460
|
+
palindrome = lambda{ |x| x == x.reverse }
|
|
461
|
+
|
|
462
|
+
"abracarba".assert palindrome
|
|
463
|
+
</pre>
|
|
464
|
+
<p>
|
|
465
|
+
QED.
|
|
466
|
+
</p>
|
|
467
|
+
|
|
468
|
+
<h1>Subjunctives</h1>
|
|
469
|
+
<p>
|
|
470
|
+
Okay. I can hear the BDDers rumbling, "where’s the
|
|
471
|
+
‘should’?" Well, AE has nothing against
|
|
472
|
+
‘should’, but there are different approaches for utilizing
|
|
473
|
+
should nomenclature in specifications, and AE wants to be open to these
|
|
474
|
+
techniques. One of which it the way Shoulda (http://shoulda.rubyforge.org)
|
|
475
|
+
utilizes <tt>should</tt> in a way analogous to RSpec’s use of
|
|
476
|
+
<tt>it</tt>.
|
|
477
|
+
</p>
|
|
478
|
+
<p>
|
|
479
|
+
Even so, AE provides a an optional mixin called Subjunctive which can be
|
|
480
|
+
used to create assertor methods using English subjunctive terms such as
|
|
481
|
+
<tt>should</tt> (or <tt>must</tt>, <tt>shall</tt> and <tt>will</tt>.
|
|
482
|
+
Whatever you like.) To load this library use:
|
|
483
|
+
</p>
|
|
484
|
+
<pre>
|
|
485
|
+
require 'ae/subjunctive'
|
|
486
|
+
</pre>
|
|
487
|
+
<p>
|
|
488
|
+
Then all that is required it to define your subjunctive method for all
|
|
489
|
+
objects. For example:
|
|
490
|
+
</p>
|
|
491
|
+
<pre>
|
|
492
|
+
def will(*args, &block)
|
|
493
|
+
Assertor.new(self, :backtrace=>caller).be(*args,&block)
|
|
494
|
+
end
|
|
495
|
+
</pre>
|
|
496
|
+
<p>
|
|
497
|
+
It’s that easy. Because of their popularity AE provides two such
|
|
498
|
+
terms, <tt>should</tt> and <tt>must</tt> as optional add-ons.
|
|
499
|
+
</p>
|
|
500
|
+
<pre>
|
|
501
|
+
require 'ae/subjunctive/should'
|
|
502
|
+
require 'ae/subjunctive/must'
|
|
503
|
+
</pre>
|
|
504
|
+
<p>
|
|
505
|
+
We will use these two methods interchangeable for the rest of this
|
|
506
|
+
demonstration, but to be clear they both work exactly the same way, and
|
|
507
|
+
almost exactly like #assert.
|
|
508
|
+
</p>
|
|
509
|
+
<p>
|
|
510
|
+
Keep in mind, AE "conical" functionality does not entail
|
|
511
|
+
subjunctive forms, or <tt>should</tt> or <tt>must</tt> assertor methods.
|
|
512
|
+
These are simply options you can load via your test_helper.rb, or similar
|
|
513
|
+
script, if you prefer or need to support these nomenclatures.
|
|
514
|
+
</p>
|
|
515
|
+
<h2>Fluent Notation and Antonyms</h2>
|
|
516
|
+
<p>
|
|
517
|
+
Like <tt>assert</tt>, <tt>should</tt> and <tt>must</tt> can be used as a
|
|
518
|
+
higher order function.
|
|
519
|
+
</p>
|
|
520
|
+
<pre>
|
|
521
|
+
4.should == 4
|
|
522
|
+
4.must == 4
|
|
523
|
+
</pre>
|
|
524
|
+
<p>
|
|
525
|
+
With the antonym of +should!+ (read as "should not") or
|
|
526
|
+
<tt>shouldnt</tt>, and for <tt>must</tt>, +must!+ or <tt>wont</tt>.
|
|
527
|
+
</p>
|
|
528
|
+
<pre>
|
|
529
|
+
4.should! == 5
|
|
530
|
+
4.shouldnt == 5
|
|
531
|
+
|
|
532
|
+
4.must! == 5
|
|
533
|
+
4.wont == 5
|
|
534
|
+
</pre>
|
|
535
|
+
<h2>To Be</h2>
|
|
536
|
+
<p>
|
|
537
|
+
On occasions where the English readability of a specification is hindered,
|
|
538
|
+
<tt>be</tt> can be used.
|
|
539
|
+
</p>
|
|
540
|
+
<pre>
|
|
541
|
+
StandardError.must.be.raised? do
|
|
542
|
+
unknown_method
|
|
543
|
+
end
|
|
544
|
+
</pre>
|
|
545
|
+
<p>
|
|
546
|
+
The <tt>be</tt> method is the same as <tt>assert</tt> with the single
|
|
547
|
+
exception that it will compare a lone argument to the receiver using
|
|
548
|
+
+equate?+, unlike <tt>assert</tt> which simply check to see that the
|
|
549
|
+
argument evalutates as true.
|
|
550
|
+
</p>
|
|
551
|
+
<pre>
|
|
552
|
+
10.should.be 10
|
|
553
|
+
10.should.be 10.0
|
|
554
|
+
10.should.be Numeric
|
|
555
|
+
</pre>
|
|
556
|
+
<h2>Indefinite Articles</h2>
|
|
557
|
+
<p>
|
|
558
|
+
Addtional anglogic forms are ‘a’ and ‘an’,
|
|
559
|
+
equivalent to ‘be’ except that they use +case?+ instead of
|
|
560
|
+
+equate?+,
|
|
561
|
+
</p>
|
|
562
|
+
<pre>
|
|
563
|
+
"hi".must.be.a String
|
|
564
|
+
</pre>
|
|
565
|
+
<p>
|
|
566
|
+
Otherwise they are interchangeble.
|
|
567
|
+
</p>
|
|
568
|
+
<pre>
|
|
569
|
+
"hi".must.be.an.instance_of?(String)
|
|
570
|
+
</pre>
|
|
571
|
+
<p>
|
|
572
|
+
The indefinite articles work well when a noun follow as an arguments.
|
|
573
|
+
</p>
|
|
574
|
+
<pre>
|
|
575
|
+
palindrome = lambda{ |x| x == x.reverse }
|
|
576
|
+
|
|
577
|
+
"abracarba".must.be.a palindrome
|
|
578
|
+
</pre>
|
|
579
|
+
<h2>Verifying Object State</h2>
|
|
580
|
+
<p>
|
|
581
|
+
The block notation of the subjunctive form is similar to <tt>assert</tt>,
|
|
582
|
+
with the important exception that the block is is evaluated in the scope of
|
|
583
|
+
the receiver via #instance_eval, if no block parameter is designated. This
|
|
584
|
+
can be also be used to test the state of an object.
|
|
585
|
+
</p>
|
|
586
|
+
<pre>
|
|
587
|
+
class X
|
|
588
|
+
attr :a
|
|
589
|
+
def initialize(a); @a = a; end
|
|
590
|
+
end
|
|
591
|
+
|
|
592
|
+
x = X.new(4)
|
|
593
|
+
|
|
594
|
+
x.must do
|
|
595
|
+
4 == @a
|
|
596
|
+
end
|
|
597
|
+
</pre>
|
|
598
|
+
<p>
|
|
599
|
+
And should it fail…
|
|
600
|
+
</p>
|
|
601
|
+
<pre>
|
|
602
|
+
Assertion.assert.raised? do
|
|
603
|
+
x.must do
|
|
604
|
+
5 == @a
|
|
605
|
+
end
|
|
606
|
+
end
|
|
607
|
+
</pre>
|
|
608
|
+
<p>
|
|
609
|
+
For some this might seem controversial —to test underlying
|
|
610
|
+
implementation. And you will get no argument here, it should be used
|
|
611
|
+
thoughtfully, but there are occasions when such validations are necessary.
|
|
612
|
+
</p>
|
|
613
|
+
<p>
|
|
614
|
+
QED.
|
|
615
|
+
</p>
|
|
616
|
+
|
|
617
|
+
|
|
618
|
+
</div>
|
|
619
|
+
</div>
|
|
620
|
+
|
|
621
|
+
</body>
|
|
622
|
+
|
|
623
|
+
</html>
|
|
624
|
+
|
|
625
|
+
<script src="../assets/scripts/spec.js" type="text/javascript" language="javascript"></script>
|
|
626
|
+
|
|
627
|
+
<script type="text/javascript" language="javascript">
|
|
628
|
+
/*****************************************************************
|
|
629
|
+
* $.toc()
|
|
630
|
+
* by rebecca murphey
|
|
631
|
+
* rmurphey gmail com
|
|
632
|
+
*
|
|
633
|
+
* This function is called on its own and takes as an argument
|
|
634
|
+
* a list of selectors with which it will build a table of
|
|
635
|
+
* contents.
|
|
636
|
+
*
|
|
637
|
+
* The first selector will make up the top level of the TOC;
|
|
638
|
+
* the second selector will make up the second level of the TOC;
|
|
639
|
+
* etc.
|
|
640
|
+
*
|
|
641
|
+
* This function returns a div containing nested unordered lists;
|
|
642
|
+
* each list item is linked to an anchor tag added before the item
|
|
643
|
+
* on the page.
|
|
644
|
+
*
|
|
645
|
+
* usage: $.toc('h1,h2,h3').prependTo('body');
|
|
646
|
+
************************************************************************/
|
|
647
|
+
(function($) {
|
|
648
|
+
$.toc = function(tocList) {
|
|
649
|
+
$(tocList).addClass('jquery-toc');
|
|
650
|
+
var tocListArray = tocList.split(',');
|
|
651
|
+
$.each(tocListArray, function(i,v) { tocListArray[i] = $.trim(v); });
|
|
652
|
+
var $elements = $('.jquery-toc');
|
|
653
|
+
$('body').append('<div></div>');
|
|
654
|
+
var $toc = $('body div:last');
|
|
655
|
+
var lastLevel = 1;
|
|
656
|
+
$toc.append('<ul class="jquery-toc-1"></ul>');
|
|
657
|
+
$elements.each(function() {
|
|
658
|
+
var $e = $(this);
|
|
659
|
+
var text = $e.text();
|
|
660
|
+
var anchor = text.replace(/ /g,'-');
|
|
661
|
+
$e.before('<a name="' + anchor + '"></a>');
|
|
662
|
+
var level;
|
|
663
|
+
$.each(tocListArray, function(i,v) {
|
|
664
|
+
if (v.match(' ')) {
|
|
665
|
+
var vArray = v.split(' ');
|
|
666
|
+
var e = vArray[vArray.length - 1];
|
|
667
|
+
} else { e = v; }
|
|
668
|
+
if ($e.is(e)) { level = i+1; }
|
|
669
|
+
});
|
|
670
|
+
var className = 'jquery-toc-' + level;
|
|
671
|
+
var li = '<li><a href="#' + anchor + '">' + text + '</a></li>';
|
|
672
|
+
if (level == lastLevel) {
|
|
673
|
+
$('ul.' + className + ':last',$toc).append(li);
|
|
674
|
+
} else if (level > lastLevel) {
|
|
675
|
+
var parentLevel = level - 1;
|
|
676
|
+
var parentClassName = 'jquery-toc-' + parentLevel;
|
|
677
|
+
$('ul.' + parentClassName + ':last',$toc).
|
|
678
|
+
append('<ul class="' + className + '"></ul>');
|
|
679
|
+
$('ul.' + className + ':last',$toc).append(li);
|
|
680
|
+
} else if (level < lastLevel) {
|
|
681
|
+
$('ul.' + className + ':last',$toc).append(li);
|
|
682
|
+
}
|
|
683
|
+
lastLevel = level;
|
|
684
|
+
});
|
|
685
|
+
var $toc_ul = $('ul.jquery-toc-1',$toc);
|
|
686
|
+
$toc.remove();
|
|
687
|
+
return($toc_ul);
|
|
688
|
+
}
|
|
689
|
+
})(jQuery);
|
|
690
|
+
</script>
|
|
691
|
+
|
|
692
|
+
<script>
|
|
693
|
+
function toc_toggle() {
|
|
694
|
+
$('#toc_side').toggle();
|
|
695
|
+
$("pre").addClass("pass");
|
|
696
|
+
$("pre:contains('FAIL:')").addClass("fail");
|
|
697
|
+
$("pre:contains('ERROR:')").addClass("error");
|
|
698
|
+
};
|
|
699
|
+
|
|
700
|
+
$.toc('#content h1,h2,h3,h4').appendTo('.toc');
|
|
701
|
+
|
|
702
|
+
toc_toggle();
|
|
703
|
+
</script>
|
|
704
|
+
|