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.
Files changed (66) hide show
  1. data/CREDITS +2 -2
  2. data/HISTORY +306 -0
  3. data/INSTALL +35 -0
  4. data/README +95 -0
  5. data/USAGE +393 -0
  6. data/doc/api/Dfect.html +3179 -0
  7. data/doc/api/Object.html +107 -0
  8. data/doc/api/_index.html +107 -0
  9. data/doc/api/class_list.html +36 -0
  10. data/doc/api/css/common.css +1 -0
  11. data/doc/api/css/full_list.css +50 -0
  12. data/doc/api/css/style.css +268 -0
  13. data/doc/api/file.LICENSE.html +73 -0
  14. data/doc/api/file_list.html +38 -0
  15. data/doc/api/frames.html +13 -0
  16. data/doc/api/index.html +72 -13
  17. data/doc/api/js/app.js +99 -0
  18. data/doc/api/js/full_list.js +106 -0
  19. data/doc/api/js/{jquery-1.3.2.min.js → jquery.js} +0 -0
  20. data/doc/api/method_list.html +339 -0
  21. data/doc/api/top-level-namespace.html +87 -0
  22. data/doc/index.erb +16 -9
  23. data/doc/index.html +1057 -726
  24. data/lib/dfect.rb +431 -284
  25. data/lib/dfect/auto.rb +2 -6
  26. data/lib/dfect/inochi.rb +48 -0
  27. data/lib/dfect/inochi.yaml +75 -0
  28. data/lib/dfect/mini.rb +1 -5
  29. data/lib/dfect/spec.rb +6 -13
  30. data/lib/dfect/unit.rb +21 -33
  31. data/test/dfect/inochi_test.rb +17 -0
  32. data/test/{dfect.rb → dfect_test.rb} +167 -7
  33. data/test/runner +25 -0
  34. data/test/test_helper.rb +1 -0
  35. metadata +43 -55
  36. data/doc/api/apple-touch-icon.png +0 -0
  37. data/doc/api/classes/Class.html +0 -73
  38. data/doc/api/classes/Dfect.html +0 -1245
  39. data/doc/api/classes/Kernel.html +0 -322
  40. data/doc/api/classes/Object.html +0 -72
  41. data/doc/api/created.rid +0 -1
  42. data/doc/api/css/main.css +0 -263
  43. data/doc/api/css/panel.css +0 -383
  44. data/doc/api/css/reset.css +0 -53
  45. data/doc/api/favicon.ico +0 -0
  46. data/doc/api/files/CREDITS.html +0 -65
  47. data/doc/api/files/LICENSE.html +0 -76
  48. data/doc/api/files/lib/dfect/auto_rb.html +0 -80
  49. data/doc/api/files/lib/dfect/mini_rb.html +0 -77
  50. data/doc/api/files/lib/dfect/spec_rb.html +0 -73
  51. data/doc/api/files/lib/dfect/unit_rb.html +0 -73
  52. data/doc/api/files/lib/dfect_rb.html +0 -74
  53. data/doc/api/i/arrows.png +0 -0
  54. data/doc/api/i/results_bg.png +0 -0
  55. data/doc/api/i/tree_bg.png +0 -0
  56. data/doc/api/js/jquery-effect.js +0 -593
  57. data/doc/api/js/main.js +0 -22
  58. data/doc/api/js/searchdoc.js +0 -628
  59. data/doc/api/panel/index.html +0 -71
  60. data/doc/api/panel/search_index.js +0 -1
  61. data/doc/api/panel/tree.js +0 -1
  62. data/doc/history.erb +0 -161
  63. data/doc/intro.erb +0 -104
  64. data/doc/setup.erb +0 -107
  65. data/doc/usage.erb +0 -310
  66. data/rakefile +0 -21
data/CREDITS CHANGED
@@ -1,2 +1,2 @@
1
- * [François Beausoleil](http://github.com/francois)
2
- * [Iñaki Baz Castillo](http://github.com/ibc)
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
+