dfect 1.1.0 → 2.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/CREDITS +2 -2
- data/HISTORY +306 -0
- data/INSTALL +35 -0
- data/README +95 -0
- data/USAGE +393 -0
- data/doc/api/Dfect.html +3179 -0
- data/doc/api/Object.html +107 -0
- data/doc/api/_index.html +107 -0
- data/doc/api/class_list.html +36 -0
- data/doc/api/css/common.css +1 -0
- data/doc/api/css/full_list.css +50 -0
- data/doc/api/css/style.css +268 -0
- data/doc/api/file.LICENSE.html +73 -0
- data/doc/api/file_list.html +38 -0
- data/doc/api/frames.html +13 -0
- data/doc/api/index.html +72 -13
- data/doc/api/js/app.js +99 -0
- data/doc/api/js/full_list.js +106 -0
- data/doc/api/js/{jquery-1.3.2.min.js → jquery.js} +0 -0
- data/doc/api/method_list.html +339 -0
- data/doc/api/top-level-namespace.html +87 -0
- data/doc/index.erb +16 -9
- data/doc/index.html +1057 -726
- data/lib/dfect.rb +431 -284
- data/lib/dfect/auto.rb +2 -6
- data/lib/dfect/inochi.rb +48 -0
- data/lib/dfect/inochi.yaml +75 -0
- data/lib/dfect/mini.rb +1 -5
- data/lib/dfect/spec.rb +6 -13
- data/lib/dfect/unit.rb +21 -33
- data/test/dfect/inochi_test.rb +17 -0
- data/test/{dfect.rb → dfect_test.rb} +167 -7
- data/test/runner +25 -0
- data/test/test_helper.rb +1 -0
- metadata +43 -55
- data/doc/api/apple-touch-icon.png +0 -0
- data/doc/api/classes/Class.html +0 -73
- data/doc/api/classes/Dfect.html +0 -1245
- data/doc/api/classes/Kernel.html +0 -322
- data/doc/api/classes/Object.html +0 -72
- data/doc/api/created.rid +0 -1
- data/doc/api/css/main.css +0 -263
- data/doc/api/css/panel.css +0 -383
- data/doc/api/css/reset.css +0 -53
- data/doc/api/favicon.ico +0 -0
- data/doc/api/files/CREDITS.html +0 -65
- data/doc/api/files/LICENSE.html +0 -76
- data/doc/api/files/lib/dfect/auto_rb.html +0 -80
- data/doc/api/files/lib/dfect/mini_rb.html +0 -77
- data/doc/api/files/lib/dfect/spec_rb.html +0 -73
- data/doc/api/files/lib/dfect/unit_rb.html +0 -73
- data/doc/api/files/lib/dfect_rb.html +0 -74
- data/doc/api/i/arrows.png +0 -0
- data/doc/api/i/results_bg.png +0 -0
- data/doc/api/i/tree_bg.png +0 -0
- data/doc/api/js/jquery-effect.js +0 -593
- data/doc/api/js/main.js +0 -22
- data/doc/api/js/searchdoc.js +0 -628
- data/doc/api/panel/index.html +0 -71
- data/doc/api/panel/search_index.js +0 -1
- data/doc/api/panel/tree.js +0 -1
- data/doc/history.erb +0 -161
- data/doc/intro.erb +0 -104
- data/doc/setup.erb +0 -107
- data/doc/usage.erb +0 -310
- data/rakefile +0 -21
data/CREDITS
CHANGED
@@ -1,2 +1,2 @@
|
|
1
|
-
|
2
|
-
|
1
|
+
- François Beausoleil <http://github.com/francois>
|
2
|
+
- Iñaki Baz Castillo <http://github.com/ibc>
|
data/HISTORY
ADDED
@@ -0,0 +1,306 @@
|
|
1
|
+
%# #%
|
2
|
+
%# You can read this document in its full glory by #%
|
3
|
+
%# opening ./doc/index.html in your favorite Web browser. #%
|
4
|
+
%# #%
|
5
|
+
|
6
|
+
%#----------------------------------------------------------------------------
|
7
|
+
%| section "Version 2.0.0 (2010-03-21)"
|
8
|
+
%#----------------------------------------------------------------------------
|
9
|
+
|
10
|
+
This release adds the ability to insulate tests from each other, share code
|
11
|
+
between them, makes the order of parameters consistent in the API, improves
|
12
|
+
user interactivity, fixes some bugs, and revises the user manual.
|
13
|
+
|
14
|
+
%#--------------------------------------------------------------------------
|
15
|
+
%| paragraph "Incompatible changes"
|
16
|
+
%#--------------------------------------------------------------------------
|
17
|
+
|
18
|
+
* Root-level calls to the `Dfect::D()` method are <%=
|
19
|
+
xref "Insulation", "automatically insulated" %> now.
|
20
|
+
|
21
|
+
* The `Dfect::E()` methods now expects its optional message
|
22
|
+
parameter to be the *last parameter* in the parameter list.
|
23
|
+
|
24
|
+
* The `Dfect::C()` methods now expect their first parameter to be a symbol
|
25
|
+
instead of the optional message to be shown in case of assertion failure.
|
26
|
+
|
27
|
+
* The `Dfect::R()` has been renamed to `Dfect::L()`,
|
28
|
+
which is a mnemonic for <%= xref "Logging" %>.
|
29
|
+
|
30
|
+
* Shorten names of hash keys in the execution trace for brevity
|
31
|
+
and rename `:raise` key in report statistics to `:error`.
|
32
|
+
|
33
|
+
* Only the most helpful subset of the failure details is shown before
|
34
|
+
placing the user into a debugger because they can query the omitted
|
35
|
+
information (on demand) inside the debugger.
|
36
|
+
|
37
|
+
* The execution trace is only shown if all tests passed in `Dfect::run()`.
|
38
|
+
|
39
|
+
* The `:debug` option is now set to Ruby's `$DEBUG` global by default.
|
40
|
+
|
41
|
+
%#--------------------------------------------------------------------------
|
42
|
+
%| paragraph "New features"
|
43
|
+
%#--------------------------------------------------------------------------
|
44
|
+
|
45
|
+
* Print failures as they occur instead of waiting until the end.
|
46
|
+
|
47
|
+
* Allow passing condition as argument to true/false assertions instead
|
48
|
+
of requiring the condition to be passed as a code block, and also fall
|
49
|
+
back to the binding of inner-most enclosing test or hook when
|
50
|
+
debugging or constructing a failure report for an assertion that was
|
51
|
+
not given a block.
|
52
|
+
|
53
|
+
This allows you to reduce "line noise" in your tests:
|
54
|
+
|
55
|
+
%|code :ruby
|
56
|
+
D "Lottery" do
|
57
|
+
winning_ticket = rand()
|
58
|
+
|
59
|
+
D "My chances of winning" do
|
60
|
+
my_ticket = rand()
|
61
|
+
F my_ticket == winning_ticket, "I won?! Dream on."
|
62
|
+
end
|
63
|
+
end
|
64
|
+
|
65
|
+
%# XXX: this line protects the following list item from the above code
|
66
|
+
* Add <%= xref "Sharing", "`Dfect::S()` methods" %>
|
67
|
+
for sharing code between tests.
|
68
|
+
|
69
|
+
* Add <%= xref "Insulation", "`Dfect::D!()` method" %>
|
70
|
+
to explicitly insulate a test from other tests, the
|
71
|
+
top-level Ruby environment, and the code being tested.
|
72
|
+
|
73
|
+
* Add `Dfect::info()` method which returns the details of
|
74
|
+
the failure that is currently being debugged by the user.
|
75
|
+
|
76
|
+
* Add instance variables to the `:vars` section of a failure report.
|
77
|
+
|
78
|
+
* Add `setup!()` and `teardown!()` methods for before-all and
|
79
|
+
after-all hooks in the <tt>dfect/unit</tt> emulation library.
|
80
|
+
|
81
|
+
* Add test execution time to statistics hash (under the `:time` key).
|
82
|
+
|
83
|
+
%#--------------------------------------------------------------------------
|
84
|
+
%| paragraph "Bug fixes"
|
85
|
+
%#--------------------------------------------------------------------------
|
86
|
+
|
87
|
+
* Do not print any output when `:quiet` option is active.
|
88
|
+
|
89
|
+
* Allow passing multiple strings/objects to `Dfect::D()` like in RSpec.
|
90
|
+
|
91
|
+
* Make before and after hook methods mixin-able like assertions.
|
92
|
+
|
93
|
+
* Do not assume that `Module#to_s` is the same as `Module#name`.
|
94
|
+
|
95
|
+
%#--------------------------------------------------------------------------
|
96
|
+
%| paragraph "Housekeeping"
|
97
|
+
%#--------------------------------------------------------------------------
|
98
|
+
|
99
|
+
* Upgrade to Inochi 2.0.0 for managing this project.
|
100
|
+
|
101
|
+
* Make emulation libraries modify Dfect module instead of Kernel.
|
102
|
+
|
103
|
+
* Do not pollute the user's output with our `Class#to_yaml` workaround.
|
104
|
+
|
105
|
+
* Remove "Motivation" section from user manual. It was too fanatic!
|
106
|
+
|
107
|
+
%#----------------------------------------------------------------------------
|
108
|
+
%| section "Version 1.1.0 (2009-10-27)"
|
109
|
+
%#----------------------------------------------------------------------------
|
110
|
+
|
111
|
+
This release adds a new method for emitting status messages and does some
|
112
|
+
internal housekeeping.
|
113
|
+
|
114
|
+
%#--------------------------------------------------------------------------
|
115
|
+
%| paragraph "Thank you"
|
116
|
+
%#--------------------------------------------------------------------------
|
117
|
+
|
118
|
+
* Iñaki Baz Castillo used Dfect and suggested new features.
|
119
|
+
|
120
|
+
%#--------------------------------------------------------------------------
|
121
|
+
%| paragraph "New features"
|
122
|
+
%#--------------------------------------------------------------------------
|
123
|
+
|
124
|
+
* Add `Dfect::S()` method for <%= xref "Logging", "adding status
|
125
|
+
messages" %> to the execution report. This feature was [requested
|
126
|
+
by](http://github.com/sunaku/dfect/issues/closed#issue/1) Iñaki Baz
|
127
|
+
Castillo.
|
128
|
+
|
129
|
+
%#--------------------------------------------------------------------------
|
130
|
+
%| paragraph "Housekeeping"
|
131
|
+
%#--------------------------------------------------------------------------
|
132
|
+
|
133
|
+
* Remove unused require of 'delegate' standard library in 'dfect/spec'
|
134
|
+
RSpec emulation layer.
|
135
|
+
|
136
|
+
* Mention <%= xref "Emulation" %> layers for popular testing libraries.
|
137
|
+
|
138
|
+
* Mention that assertions take an optional message parameter.
|
139
|
+
|
140
|
+
* Replace sample unit test with Dfect test suite.
|
141
|
+
|
142
|
+
* Upgrade user manual to ERBook 9.0.0.
|
143
|
+
|
144
|
+
%#----------------------------------------------------------------------------
|
145
|
+
%| section "Version 1.0.1 (2009-10-07)"
|
146
|
+
%#----------------------------------------------------------------------------
|
147
|
+
|
148
|
+
This release fixes a bug in the Test::Unit emulation library and revises the
|
149
|
+
user manual.
|
150
|
+
|
151
|
+
%#--------------------------------------------------------------------------
|
152
|
+
%| paragraph "Bug fixes"
|
153
|
+
%#--------------------------------------------------------------------------
|
154
|
+
|
155
|
+
* The parameters for the `assert_equal()` method in the
|
156
|
+
<tt>dfect/unit</tt> library were in the wrong order.
|
157
|
+
|
158
|
+
%#--------------------------------------------------------------------------
|
159
|
+
%| paragraph "Housekeeping"
|
160
|
+
%#--------------------------------------------------------------------------
|
161
|
+
|
162
|
+
* Revise user manual to better fit jQuery UI tabs.
|
163
|
+
|
164
|
+
* Justify the use of `eval()` in emulation libraries.
|
165
|
+
|
166
|
+
* Use simpler Copyright reminder at the top of every file.
|
167
|
+
|
168
|
+
* Make SLOC count in user manual reflect the *core* library only.
|
169
|
+
|
170
|
+
* Mark code spans with `{:lang=ruby}` instead of HTML `<code/>` tags.
|
171
|
+
|
172
|
+
* Open source is for fun, so [be nice][1] and speak of "related works"
|
173
|
+
instead of "competitors".
|
174
|
+
|
175
|
+
[1]: http://loiclemeur.com/english/2009/03/never-criticize-your-competitors.html
|
176
|
+
|
177
|
+
%#----------------------------------------------------------------------------
|
178
|
+
%| section "Version 1.0.0 (2009-05-03)"
|
179
|
+
%#----------------------------------------------------------------------------
|
180
|
+
|
181
|
+
This release improves default choices, adds emulation layers to mimic other
|
182
|
+
testing libraries, and fixes some bugs.
|
183
|
+
|
184
|
+
%#--------------------------------------------------------------------------
|
185
|
+
%| paragraph "Incompatible changes"
|
186
|
+
%#--------------------------------------------------------------------------
|
187
|
+
|
188
|
+
* The `:debug` option is now enabled by default and is no longer linked to
|
189
|
+
the value of `$DEBUG`.
|
190
|
+
|
191
|
+
* `Dfect.run()` now appends to previous results by default.
|
192
|
+
|
193
|
+
This behavior can be disabled by passing `false` to the method.
|
194
|
+
|
195
|
+
%#--------------------------------------------------------------------------
|
196
|
+
%| paragraph "New features"
|
197
|
+
%#--------------------------------------------------------------------------
|
198
|
+
|
199
|
+
* Add emulation layers to mimic other testing libraries:
|
200
|
+
* <tt>dfect/unit</tt> --- Test::Unit
|
201
|
+
* <tt>dfect/mini</tt> --- Minitest
|
202
|
+
* <tt>dfect/spec</tt> --- RSpec
|
203
|
+
|
204
|
+
%#--------------------------------------------------------------------------
|
205
|
+
%| paragraph "Bug fixes"
|
206
|
+
%#--------------------------------------------------------------------------
|
207
|
+
|
208
|
+
* Do not blindly replace `Class#to_yaml`; it might be fixed someday.
|
209
|
+
|
210
|
+
%#--------------------------------------------------------------------------
|
211
|
+
%| paragraph "Housekeeping"
|
212
|
+
%#--------------------------------------------------------------------------
|
213
|
+
|
214
|
+
* Add "Motivation" section in user manual to promote interactive
|
215
|
+
debugging.
|
216
|
+
|
217
|
+
* Add brief <%= xref "History" %> of this project's inception.
|
218
|
+
|
219
|
+
* Remove redundant assertions for F!() and T!() methods in test suite.
|
220
|
+
|
221
|
+
* Add copyright notice at the top of every file.
|
222
|
+
|
223
|
+
%#----------------------------------------------------------------------------
|
224
|
+
%| section "Version 0.1.0 (2009-04-28)"
|
225
|
+
%#----------------------------------------------------------------------------
|
226
|
+
|
227
|
+
This release adds new variations to assertion methods, fixes several bugs,
|
228
|
+
and improves test coverage.
|
229
|
+
|
230
|
+
%#--------------------------------------------------------------------------
|
231
|
+
%| paragraph "Thank you"
|
232
|
+
%#--------------------------------------------------------------------------
|
233
|
+
|
234
|
+
* François Beausoleil contributed patches for both code *and* tests! :-)
|
235
|
+
|
236
|
+
%#--------------------------------------------------------------------------
|
237
|
+
%| paragraph "New features"
|
238
|
+
%#--------------------------------------------------------------------------
|
239
|
+
|
240
|
+
* Added <%= xref "Negation", "negation (m!)" %> and <%=
|
241
|
+
xref "Sampling", "sampling (m?)" %> variations to <%=
|
242
|
+
xref "Assertions", "assertion methods" %>.
|
243
|
+
|
244
|
+
These new methods implement assertion functionality missing so far
|
245
|
+
(previously we could not assert that a given exception was NOT thrown)
|
246
|
+
and thereby allow us to fully test Dfect using itself.
|
247
|
+
|
248
|
+
* Added documentation on <%= xref "Insulation", "how to insulate tests" %>
|
249
|
+
from the global Ruby namespace.
|
250
|
+
|
251
|
+
%#--------------------------------------------------------------------------
|
252
|
+
%| paragraph "Bug fixes"
|
253
|
+
%#--------------------------------------------------------------------------
|
254
|
+
|
255
|
+
* The `E()` method did not consider the case where a block does not raise
|
256
|
+
anything as a failure. ---*François Beausoleil*
|
257
|
+
|
258
|
+
* When creating a report about an assertion failure, an exception would be
|
259
|
+
thrown if any local variables pointed to an empty array.
|
260
|
+
|
261
|
+
* The `Dfect::<()` method broke the inheritance-checking behavior of the <
|
262
|
+
class method.
|
263
|
+
|
264
|
+
Added a bypass to the originial behavior so that `RCov::XX` can properly
|
265
|
+
generate a report about code that uses Dfect.
|
266
|
+
|
267
|
+
* Added workaround for YAML error when serializing a class object:
|
268
|
+
|
269
|
+
TypeError: can't dump anonymous class Class
|
270
|
+
|
271
|
+
%#--------------------------------------------------------------------------
|
272
|
+
%| paragraph "Housekeeping"
|
273
|
+
%#--------------------------------------------------------------------------
|
274
|
+
|
275
|
+
* Filled the big holes in test coverage. Everything except the runtime
|
276
|
+
debugging logic is now covered by the unit tests.
|
277
|
+
|
278
|
+
%#----------------------------------------------------------------------------
|
279
|
+
%| section "Version 0.0.0 (2009-04-13)"
|
280
|
+
%#----------------------------------------------------------------------------
|
281
|
+
|
282
|
+
For the longest time, I took Test::Unit and [RSpec](http://rspec.info) for
|
283
|
+
granted. They were the epitomy of modern Ruby practice; the insurmountable
|
284
|
+
status quo; immortalized in books, conferences, and blogs alike.
|
285
|
+
|
286
|
+
Why would *anyone* think of using anything remotely different, let alone be
|
287
|
+
foolish enough to write an alternative testing library when these are
|
288
|
+
clearly *good enough*?
|
289
|
+
|
290
|
+
Recent experiments in assertion testing libraries smashed my world view:
|
291
|
+
|
292
|
+
* [assert{ 2.0 }](http://assert2.rubyforge.org)
|
293
|
+
* [Testy](http://github.com/ahoward/testy/tree/master)
|
294
|
+
* [Verify](http://www.ruby-forum.com/topic/183354)
|
295
|
+
|
296
|
+
The status quo was certainly *not* "good enough", as I had so blindly
|
297
|
+
believed all these years. In fact, they were *verbose* behemoths that chose
|
298
|
+
to encode endless permutations of conjecture into methods.
|
299
|
+
|
300
|
+
Empowered by this revelation and inspired by [Sean O'Halpin's musing][1] on
|
301
|
+
alternative names for assertion methods, I rose to challenge the status quo.
|
302
|
+
|
303
|
+
And so I present to you the first public release of "Dfect".
|
304
|
+
|
305
|
+
[1]: http://www.ruby-forum.com/topic/183354#801895
|
306
|
+
|
data/INSTALL
ADDED
@@ -0,0 +1,35 @@
|
|
1
|
+
%# #%
|
2
|
+
%# You can read this document in its full glory by #%
|
3
|
+
%# opening ./doc/index.html in your favorite Web browser. #%
|
4
|
+
%# #%
|
5
|
+
|
6
|
+
%#----------------------------------------------------------------------------
|
7
|
+
%| section "Prerequisites"
|
8
|
+
%#----------------------------------------------------------------------------
|
9
|
+
|
10
|
+
* [Ruby](http://ruby-lang.org) 1.8.6 or newer.
|
11
|
+
|
12
|
+
* [RubyGems](http://rubygems.org) 1.3.6 or newer.
|
13
|
+
|
14
|
+
* [ruby-debug](http://www.datanoise.com/ruby-debug) will
|
15
|
+
be used if it is available. Otherwise the standard
|
16
|
+
interactive Ruby shell (IRB) will be used instead.
|
17
|
+
|
18
|
+
%#----------------------------------------------------------------------------
|
19
|
+
%| section "Installing"
|
20
|
+
%#----------------------------------------------------------------------------
|
21
|
+
|
22
|
+
%|command! "gem install dfect"
|
23
|
+
|
24
|
+
%#----------------------------------------------------------------------------
|
25
|
+
%| section "Upgrading"
|
26
|
+
%#----------------------------------------------------------------------------
|
27
|
+
|
28
|
+
%|command! "gem update dfect"
|
29
|
+
|
30
|
+
%#----------------------------------------------------------------------------
|
31
|
+
%| section "Uninstalling"
|
32
|
+
%#----------------------------------------------------------------------------
|
33
|
+
|
34
|
+
%|command! "gem uninstall dfect"
|
35
|
+
|
data/README
ADDED
@@ -0,0 +1,95 @@
|
|
1
|
+
%# #%
|
2
|
+
%# You can read this document in its full glory by #%
|
3
|
+
%# opening ./doc/index.html in your favorite Web browser. #%
|
4
|
+
%# #%
|
5
|
+
|
6
|
+
%#----------------------------------------------------------------------------
|
7
|
+
%| project_summary
|
8
|
+
%#----------------------------------------------------------------------------
|
9
|
+
|
10
|
+
Dfect is an assertion testing library for Ruby that emphasizes a simple
|
11
|
+
assertion vocabulary, instant debuggability of failures, and flexibility in
|
12
|
+
composing tests.
|
13
|
+
|
14
|
+
%#----------------------------------------------------------------------------
|
15
|
+
%| paragraph "Resources"
|
16
|
+
%#----------------------------------------------------------------------------
|
17
|
+
|
18
|
+
* <%= xref "History", "What's new?" %> ---
|
19
|
+
release notes and project history.
|
20
|
+
|
21
|
+
* [Issue tracker](<%= issue_tracker_url %>) ---
|
22
|
+
report bugs, request features, or ask for help.
|
23
|
+
|
24
|
+
* [Source code](<%= source_code_url %>) ---
|
25
|
+
browse online or obtain using <%= source_code_tool %>
|
26
|
+
|
27
|
+
* [API reference](<%= api_reference_url %>) ---
|
28
|
+
documentation for source code.
|
29
|
+
|
30
|
+
* [Project home](<%= Dfect::WEBSITE %>) ---
|
31
|
+
the official project home page.
|
32
|
+
|
33
|
+
%#----------------------------------------------------------------------------
|
34
|
+
%| section "Features"
|
35
|
+
%#----------------------------------------------------------------------------
|
36
|
+
|
37
|
+
Dfect is exciting because:
|
38
|
+
|
39
|
+
* There are only 5 methods to remember: D F E C T.
|
40
|
+
|
41
|
+
* It lets you debug assertion failures interactively.
|
42
|
+
|
43
|
+
* It keeps a detailed report of assertion failures.
|
44
|
+
|
45
|
+
* It lets you nest tests and execution hooks.
|
46
|
+
|
47
|
+
* Its core consists of a mere <%= `sloccount lib/dfect.rb`[/^\d+/] %> lines
|
48
|
+
of code.
|
49
|
+
|
50
|
+
%#----------------------------------------------------------------------------
|
51
|
+
%| section "Etymology"
|
52
|
+
%#----------------------------------------------------------------------------
|
53
|
+
|
54
|
+
Dfect is named after the D F E C T methods it provides.
|
55
|
+
|
56
|
+
The name is also play on the word "defect", whereby the intentional
|
57
|
+
misspelling of "defect" as "dfect" is a defect in itself! ;-)
|
58
|
+
|
59
|
+
This wordplay is similar to [Mnesia][1]'s play on the word "amnesia",
|
60
|
+
whereby the intentional omission of the letter "A" indicates
|
61
|
+
forgetfulness---the key characteristic of having amnesia. Clever!
|
62
|
+
|
63
|
+
[1]: http://www.erlang.org/doc/apps/mnesia/index.html
|
64
|
+
|
65
|
+
%#----------------------------------------------------------------------------
|
66
|
+
%| section "License"
|
67
|
+
%#----------------------------------------------------------------------------
|
68
|
+
|
69
|
+
%# See the file named "LICENSE" for details.
|
70
|
+
%< "LICENSE"
|
71
|
+
|
72
|
+
%#----------------------------------------------------------------------------
|
73
|
+
%| section "Credits"
|
74
|
+
%#----------------------------------------------------------------------------
|
75
|
+
|
76
|
+
Dfect is made possible by <%= xref "History",
|
77
|
+
"contributions" %> from users like you:
|
78
|
+
|
79
|
+
%# See the file named "CREDITS" for details.
|
80
|
+
%< "CREDITS"
|
81
|
+
|
82
|
+
%#----------------------------------------------------------------------------
|
83
|
+
%| section "Related works"
|
84
|
+
%#----------------------------------------------------------------------------
|
85
|
+
|
86
|
+
* [assert{ 2.0 }](http://assert2.rubyforge.org)
|
87
|
+
* [Bacon](http://chneukirchen.org/repos/bacon/README)
|
88
|
+
* [Context](http://github.com/jeremymcanally/context)
|
89
|
+
* [minitest](http://blog.zenspider.com/minitest)
|
90
|
+
* [RSpec](http://rspec.info)
|
91
|
+
* [Shoulda](http://thoughtbot.com/projects/shoulda)
|
92
|
+
* [test-spec](http://test-spec.rubyforge.org/test-spec)
|
93
|
+
* [Test::Unit](http://www.ruby-doc.org/stdlib/libdoc/test/unit/rdoc/)
|
94
|
+
* [Testy](http://github.com/ahoward/testy/tree/master)
|
95
|
+
* [Verify](http://www.ruby-forum.com/topic/183354)
|
data/USAGE
ADDED
@@ -0,0 +1,393 @@
|
|
1
|
+
%# #%
|
2
|
+
%# You can read this document in its full glory by #%
|
3
|
+
%# opening ./doc/index.html in your favorite Web browser. #%
|
4
|
+
%# #%
|
5
|
+
|
6
|
+
% def example_dfect_test *example_node_args, &block_containing_code_to_run
|
7
|
+
% code_to_run = __block_content__(&block_containing_code_to_run).join
|
8
|
+
% code_to_run.insert 0, "require 'dfect/auto'\n\n"
|
9
|
+
|
10
|
+
%|example! *example_node_args
|
11
|
+
When the following test is run:
|
12
|
+
|
13
|
+
<%
|
14
|
+
code :ruby do
|
15
|
+
code_to_run
|
16
|
+
end
|
17
|
+
%>
|
18
|
+
|
19
|
+
Dfect will output the following:
|
20
|
+
|
21
|
+
<%
|
22
|
+
text do
|
23
|
+
IO.popen('ruby -Ilib 2>&1', 'w+') do |ruby|
|
24
|
+
ruby.write code_to_run
|
25
|
+
ruby.close_write
|
26
|
+
ruby.read
|
27
|
+
end
|
28
|
+
end
|
29
|
+
%>
|
30
|
+
|
31
|
+
Begin by loading Dfect into your program:
|
32
|
+
|
33
|
+
%|code :ruby
|
34
|
+
require 'rubygems' # only necessary if you are using Ruby 1.8
|
35
|
+
require 'dfect'
|
36
|
+
|
37
|
+
You now have access to the `Dfect` module, which provides methods that can be
|
38
|
+
either mixed-in or called directly, according to your preference:
|
39
|
+
|
40
|
+
%|code :ruby
|
41
|
+
Dfect.D "hello" do # D() is a class method
|
42
|
+
puts "world"
|
43
|
+
end
|
44
|
+
|
45
|
+
# the above is same as:
|
46
|
+
|
47
|
+
include Dfect # mix-in the Dfect API
|
48
|
+
|
49
|
+
D "hello" do # D() is an instance method
|
50
|
+
puts "world"
|
51
|
+
end
|
52
|
+
|
53
|
+
%#----------------------------------------------------------------------------
|
54
|
+
%| section "Assertions"
|
55
|
+
%#----------------------------------------------------------------------------
|
56
|
+
|
57
|
+
The following methods accept a block parameter and assert something about
|
58
|
+
the result of executing that block. They also accept an optional message,
|
59
|
+
which is shown in <%= xref "Failures", "failure reports" %> if they fail.
|
60
|
+
|
61
|
+
See the <%= api_reference %> for more details and examples.
|
62
|
+
|
63
|
+
%|table
|
64
|
+
%|thead
|
65
|
+
%|tr
|
66
|
+
%|th
|
67
|
+
Method
|
68
|
+
%|th
|
69
|
+
Description
|
70
|
+
%|tbody
|
71
|
+
%|tr
|
72
|
+
%|td
|
73
|
+
T
|
74
|
+
%|td
|
75
|
+
assert true (not `nil` and not `false`)
|
76
|
+
%|tr
|
77
|
+
%|td
|
78
|
+
F
|
79
|
+
%|td
|
80
|
+
assert not true (`nil` or `false`)
|
81
|
+
%|tr
|
82
|
+
%|td
|
83
|
+
E
|
84
|
+
%|td
|
85
|
+
assert that an execption is raised
|
86
|
+
%|tr
|
87
|
+
%|td
|
88
|
+
C
|
89
|
+
%|td
|
90
|
+
assert that a symbol is thrown
|
91
|
+
|
92
|
+
%#--------------------------------------------------------------------------
|
93
|
+
%| section "Negation"
|
94
|
+
%#--------------------------------------------------------------------------
|
95
|
+
|
96
|
+
These methods are the *opposite* of
|
97
|
+
<%= xref "Assertions", "normal assertions" %>.
|
98
|
+
|
99
|
+
%|table
|
100
|
+
%|thead
|
101
|
+
%|tr
|
102
|
+
%|th
|
103
|
+
Method
|
104
|
+
%|th
|
105
|
+
Description
|
106
|
+
%|tbody
|
107
|
+
%|tr
|
108
|
+
%|td
|
109
|
+
T!
|
110
|
+
%|td
|
111
|
+
same as F
|
112
|
+
%|tr
|
113
|
+
%|td
|
114
|
+
F!
|
115
|
+
%|td
|
116
|
+
same as T
|
117
|
+
%|tr
|
118
|
+
%|td
|
119
|
+
E!
|
120
|
+
%|td
|
121
|
+
assert that an exception is *not* raised
|
122
|
+
%|tr
|
123
|
+
%|td
|
124
|
+
C!
|
125
|
+
%|td
|
126
|
+
assert that a symbol is *not* thrown
|
127
|
+
|
128
|
+
%#--------------------------------------------------------------------------
|
129
|
+
%| section "Sampling"
|
130
|
+
%#--------------------------------------------------------------------------
|
131
|
+
|
132
|
+
These methods allow you to *check the outcome* of an assertion without
|
133
|
+
recording a success or failure for that assertion in the execution report.
|
134
|
+
|
135
|
+
%|table
|
136
|
+
%|thead
|
137
|
+
%|tr
|
138
|
+
%|th
|
139
|
+
Method
|
140
|
+
%|th
|
141
|
+
Description
|
142
|
+
%|tbody
|
143
|
+
%|tr
|
144
|
+
%|td
|
145
|
+
T?
|
146
|
+
%|td
|
147
|
+
returns `true` if T passes; `false` otherwise
|
148
|
+
%|tr
|
149
|
+
%|td
|
150
|
+
F?
|
151
|
+
%|td
|
152
|
+
returns `true` if F passes; `false` otherwise
|
153
|
+
%|tr
|
154
|
+
%|td
|
155
|
+
E?
|
156
|
+
%|td
|
157
|
+
returns `true` if E passes; `false` otherwise
|
158
|
+
%|tr
|
159
|
+
%|td
|
160
|
+
C?
|
161
|
+
%|td
|
162
|
+
returns `true` if C passes; `false` otherwise
|
163
|
+
|
164
|
+
%#--------------------------------------------------------------------------
|
165
|
+
%| section "Failures"
|
166
|
+
%#--------------------------------------------------------------------------
|
167
|
+
|
168
|
+
When an assertion fails, details about the failure will be shown:
|
169
|
+
|
170
|
+
- fail: block must yield true (!nil && !false)
|
171
|
+
code: |-
|
172
|
+
[12..22] in test/simple.rb
|
173
|
+
12
|
174
|
+
13 D "with more nested tests" do
|
175
|
+
14 x = 5
|
176
|
+
15
|
177
|
+
16 T { x > 2 } # passes
|
178
|
+
=> 17 F { x > 2 } # fails
|
179
|
+
18 E { x.hello } # passes
|
180
|
+
19 end
|
181
|
+
20 end
|
182
|
+
21
|
183
|
+
22 # equivalent of before(:each) or setup()
|
184
|
+
vars:
|
185
|
+
x: 5
|
186
|
+
y: 83
|
187
|
+
call:
|
188
|
+
- test/simple.rb:17
|
189
|
+
- test/simple.rb:3
|
190
|
+
|
191
|
+
You will then be placed into a debugger to investigate the failure if the
|
192
|
+
`:debug` option is enabled in the `Dfect.options` hash.
|
193
|
+
|
194
|
+
Details about all assertion failures and a trace of all tests executed are
|
195
|
+
stored by Dfect and provided by the `Dfect.report()` method.
|
196
|
+
|
197
|
+
%#--------------------------------------------------------------------------
|
198
|
+
%| section "Emulation"
|
199
|
+
%#--------------------------------------------------------------------------
|
200
|
+
|
201
|
+
Dfect provides emulation layers for several popular testing libraries:
|
202
|
+
|
203
|
+
* <tt>dfect/unit</tt> --- Test::Unit
|
204
|
+
* <tt>dfect/mini</tt> --- Minitest
|
205
|
+
* <tt>dfect/spec</tt> --- RSpec
|
206
|
+
|
207
|
+
Simply `require()` one of these emulation layers into your test suite and
|
208
|
+
you can write your tests using the familiar syntax of that testing
|
209
|
+
library. See [their source code](<%= source_code_url
|
210
|
+
%>/tree/master/lib/dfect/) for more details.
|
211
|
+
|
212
|
+
%#----------------------------------------------------------------------------
|
213
|
+
%| section "Tests"
|
214
|
+
%#----------------------------------------------------------------------------
|
215
|
+
|
216
|
+
The `D()` method defines a new Dfect **test**, which is analagous to the
|
217
|
+
concept of **test case** in xUnit or **describe** in rSpec. A test may
|
218
|
+
contain nested tests.
|
219
|
+
|
220
|
+
%|code :ruby
|
221
|
+
D "outer test" do
|
222
|
+
# assertions and logic here
|
223
|
+
|
224
|
+
D "inner test" do
|
225
|
+
# more assertions and logic here
|
226
|
+
end
|
227
|
+
end
|
228
|
+
|
229
|
+
%#--------------------------------------------------------------------------
|
230
|
+
%| section "Execution"
|
231
|
+
%#--------------------------------------------------------------------------
|
232
|
+
|
233
|
+
Tests are executed in depth-first order.
|
234
|
+
|
235
|
+
You can configure the test execution process using:
|
236
|
+
|
237
|
+
%|code :ruby
|
238
|
+
Dfect.options = your_options_hash
|
239
|
+
|
240
|
+
You can execute all tests defined thus far using:
|
241
|
+
|
242
|
+
%|code :ruby
|
243
|
+
Dfect.run
|
244
|
+
|
245
|
+
You can stop the execution at any time using:
|
246
|
+
|
247
|
+
%|code :ruby
|
248
|
+
Dfect.stop
|
249
|
+
|
250
|
+
You can view the results of execution using:
|
251
|
+
|
252
|
+
%|code :ruby
|
253
|
+
puts Dfect.report.to_yaml
|
254
|
+
|
255
|
+
See the <%= api_reference %> for details and examples.
|
256
|
+
|
257
|
+
%#------------------------------------------------------------------------
|
258
|
+
%| paragraph "Automatic test execution"
|
259
|
+
%#------------------------------------------------------------------------
|
260
|
+
|
261
|
+
To mix-in the `Dfect` module into your program and execute all tests
|
262
|
+
defined by your program before it terminates, simply add the following
|
263
|
+
line at the top of your program:
|
264
|
+
|
265
|
+
%|code :ruby
|
266
|
+
require 'dfect/auto'
|
267
|
+
|
268
|
+
%#------------------------------------------------------------------------
|
269
|
+
%| section "Hooks"
|
270
|
+
%#------------------------------------------------------------------------
|
271
|
+
|
272
|
+
The `D()` method provides several entry points (hooks) into the test
|
273
|
+
execution process:
|
274
|
+
|
275
|
+
%|code :ruby
|
276
|
+
D "outer test" do
|
277
|
+
D .< { puts "before each nested test" }
|
278
|
+
D .> { puts "after each nested test" }
|
279
|
+
D .<< { puts "before all nested tests" }
|
280
|
+
D .>> { puts "after all nested tests" }
|
281
|
+
|
282
|
+
D "inner test" do
|
283
|
+
# assertions and logic here
|
284
|
+
end
|
285
|
+
end
|
286
|
+
|
287
|
+
A hook method may be called multiple times. Each call registers
|
288
|
+
additional logic to execute during the hook:
|
289
|
+
|
290
|
+
%|code :ruby
|
291
|
+
D .< { puts "do something" }
|
292
|
+
D .< { puts "do something more!" }
|
293
|
+
|
294
|
+
%#------------------------------------------------------------------------
|
295
|
+
%| section "Logging"
|
296
|
+
%#------------------------------------------------------------------------
|
297
|
+
|
298
|
+
The `L()` method lets you insert log messages, composed of arbitrary
|
299
|
+
Ruby objects, into the test execution report.
|
300
|
+
|
301
|
+
%|example_dfect_test "Logging information in the execution report"
|
302
|
+
D 'Wizard' do
|
303
|
+
L 'Preparing spell to defeat mortal foes...'
|
304
|
+
end
|
305
|
+
|
306
|
+
D 'Magician' do
|
307
|
+
L 'Preparing rabbits to pull from hat...', rand(15)
|
308
|
+
end
|
309
|
+
|
310
|
+
D 'Calculator' do
|
311
|
+
L Math::PI, [1, 2, 3, ['a', 'b', 'c']], {:foo => 'bar!'}
|
312
|
+
end
|
313
|
+
|
314
|
+
%#--------------------------------------------------------------------------
|
315
|
+
%| section "Sharing"
|
316
|
+
%#--------------------------------------------------------------------------
|
317
|
+
|
318
|
+
The `S()` method is a mechanism for sharing code. When called with a
|
319
|
+
block, it shares the given block (under a given identifier) for injection
|
320
|
+
into other tests. When called without a block, it injects a previously
|
321
|
+
shared block (under a given identifier) into the environment where it is
|
322
|
+
called.
|
323
|
+
|
324
|
+
The `S!()` method is a combination of the two uses of the `S()` method: it
|
325
|
+
lets you simultaneously share a block of code while injecting it into the
|
326
|
+
environment where that method is called.
|
327
|
+
|
328
|
+
The `S?()` method simply checks whether any code has been shared under a
|
329
|
+
given identifier.
|
330
|
+
|
331
|
+
%|example_dfect_test "Sharing code between tests"
|
332
|
+
S :knowledge do
|
333
|
+
L 'Knowledge is power!'
|
334
|
+
end
|
335
|
+
|
336
|
+
D 'Healer' do
|
337
|
+
S :knowledge
|
338
|
+
end
|
339
|
+
|
340
|
+
D 'Warrior' do
|
341
|
+
S! :strength do
|
342
|
+
L 'Strength is power!'
|
343
|
+
end
|
344
|
+
end
|
345
|
+
|
346
|
+
D 'Wizard' do
|
347
|
+
S :knowledge
|
348
|
+
S :strength
|
349
|
+
end
|
350
|
+
|
351
|
+
D 'King' do
|
352
|
+
T { S? :knowledge }
|
353
|
+
T { S? :strength }
|
354
|
+
F { S? :power }
|
355
|
+
L 'Power is power!'
|
356
|
+
end
|
357
|
+
|
358
|
+
%#--------------------------------------------------------------------------
|
359
|
+
%| section "Insulation"
|
360
|
+
%#--------------------------------------------------------------------------
|
361
|
+
|
362
|
+
The `D!()` method defines a new test that is explicitly insulated from the
|
363
|
+
tests that contain it and also from the top-level Ruby environment.
|
364
|
+
Root-level calls to the `D()` method are insulated by default.
|
365
|
+
|
366
|
+
Inside an insulated test, you are free to:
|
367
|
+
* mix-in any modules your test logic needs
|
368
|
+
* define your own constants, methods, and classes
|
369
|
+
|
370
|
+
%|example_dfect_test "Insulated and uninsulated tests"
|
371
|
+
D "a root-level test" do
|
372
|
+
@outside = 1
|
373
|
+
T { defined? @outside }
|
374
|
+
T { @outside == 1 }
|
375
|
+
|
376
|
+
D "an inner, non-insulated test" do
|
377
|
+
T { defined? @outside }
|
378
|
+
T { @outside == 1 }
|
379
|
+
end
|
380
|
+
|
381
|
+
D! "an inner, insulated test" do
|
382
|
+
F { defined? @outside }
|
383
|
+
F { @outside == 1 }
|
384
|
+
|
385
|
+
@inside = 2
|
386
|
+
T { defined? @inside }
|
387
|
+
T { @inside == 2 }
|
388
|
+
end
|
389
|
+
|
390
|
+
F { defined? @inside }
|
391
|
+
F { @inside == 2 }
|
392
|
+
end
|
393
|
+
|