dfect 1.0.0 → 1.1.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/doc/usage.erb CHANGED
@@ -1,142 +1,218 @@
1
1
  %#--
2
- %# Copyright 2009 Suraj N. Kurapati
3
- %# See the LICENSE file for details.
2
+ %# Copyright protects this work.
3
+ %# See LICENSE file for details.
4
4
  %#++
5
5
 
6
6
  % dfect_api = 'api/classes/Dfect.html'
7
7
 
8
+
8
9
  %|chapter "Usage"
10
+
9
11
  Begin by loading <%= $project %> into your program:
10
12
 
11
- <code>
12
- require 'rubygems'
13
- require 'dfect'
14
- </code>
13
+ %|code :ruby
14
+ require 'rubygems' # only necessary if you are using Ruby 1.8
15
+ require 'dfect'
16
+
17
+ You now have access to the [`Dfect` module](<%= dfect_api %>), which provides methods that can be mixed-in or called directly, according to your preference:
15
18
 
16
- You now have access to the [`Dfect` module](<%= dfect_api %>), which provides mixin-able instance methods that are also directly-callable as class methods:
19
+ %|code :ruby
20
+ Dfect.D "hello" do # D() is a class method
21
+ puts "world"
22
+ end
17
23
 
18
- <code>
19
- Dfect.D "hello" do # D() is a not-mixed-in class method
20
- puts "world"
21
- end
24
+ # the above is same as:
22
25
 
23
- # the above is same as:
26
+ include Dfect # mix-in the Dfect API
24
27
 
25
- include Dfect
28
+ D "hello" do # D() is an instance method
29
+ puts "world"
30
+ end
26
31
 
27
- D "hello" do # D() is a mixed-in instance method
28
- puts "world"
29
- end
30
- </code>
32
+ The following sections explain these provided methods in detail. If you are impatient, you can skip to <%= xref "A sample unit test" %> for an illustrative example.
31
33
 
32
- The following sections explain these provided methods in detail.
33
34
 
34
35
  %|section "Assertions"
35
- The following methods take a block parameter and assert something about the result of executing that block. See the [API documentation](<%= dfect_api %>) for examples.
36
36
 
37
- | Method | Description |
38
- | ------ | ----------- |
39
- | F | assert not true (`nil` or `false`) |
40
- | E | assert that an execption is raised |
41
- | C | assert that a symbol is thrown |
42
- | T | assert true (not `nil` and not `false`) |
37
+ The following methods accept a block parameter and assert something about the result of executing that block. They also accept an optional message, which is shown in <%= xref "Failures", "failure reports" %> if they fail.
38
+
39
+ See the [API documentation](<%= api_url %>) for details and examples.
40
+
41
+ %|table
42
+ %|thead
43
+ %|tr
44
+ %|th
45
+ Method
46
+ %|th
47
+ Description
48
+ %|tbody
49
+ %|tr
50
+ %|td
51
+ T
52
+ %|td
53
+ assert true (not `nil` and not `false`)
54
+ %|tr
55
+ %|td
56
+ F
57
+ %|td
58
+ assert not true (`nil` or `false`)
59
+ %|tr
60
+ %|td
61
+ E
62
+ %|td
63
+ assert that an execption is raised
64
+ %|tr
65
+ %|td
66
+ C
67
+ %|td
68
+ assert that a symbol is thrown
69
+
43
70
 
44
71
  %|paragraph "Negation"
72
+
45
73
  These methods are the *opposite* of <%= xref "Assertions", "normal assertions" %>.
46
74
 
47
- | Method | Description |
48
- | ------ | ----------- |
49
- | F! | same as T |
50
- | E! | assert that an execption is *not* raised |
51
- | C! | assert that a symbol is *not* thrown |
52
- | T! | same as F |
75
+ %|table
76
+ %|thead
77
+ %|tr
78
+ %|th
79
+ Method
80
+ %|th
81
+ Description
82
+ %|tbody
83
+ %|tr
84
+ %|td
85
+ T!
86
+ %|td
87
+ same as F
88
+ %|tr
89
+ %|td
90
+ F!
91
+ %|td
92
+ same as T
93
+ %|tr
94
+ %|td
95
+ E!
96
+ %|td
97
+ assert that an exception is *not* raised
98
+ %|tr
99
+ %|td
100
+ C!
101
+ %|td
102
+ assert that a symbol is *not* thrown
103
+
53
104
 
54
105
  %|paragraph "Sampling"
55
- These methods allow you to *check the outcome* of an <%= xref "Assertions", "assertion" %> without the penalty of pass or failure.
56
106
 
57
- | Method | Description |
58
- | ------ | ----------- |
59
- | F? | returns `true` if F passes; `false` otherwise |
60
- | E? | returns `true` if E passes; `false` otherwise |
61
- | C? | returns `true` if C passes; `false` otherwise |
62
- | T? | returns `true` if T passes; `false` otherwise |
107
+ These methods allow you to *check the outcome* of an <%= xref "Assertions", "assertion" %> without including the assertion in the execution report.
108
+
109
+ %|table
110
+ %|thead
111
+ %|tr
112
+ %|th
113
+ Method
114
+ %|th
115
+ Description
116
+ %|tbody
117
+ %|tr
118
+ %|td
119
+ T?
120
+ %|td
121
+ returns `true` if T passes; `false` otherwise
122
+ %|tr
123
+ %|td
124
+ F?
125
+ %|td
126
+ returns `true` if F passes; `false` otherwise
127
+ %|tr
128
+ %|td
129
+ E?
130
+ %|td
131
+ returns `true` if E passes; `false` otherwise
132
+ %|tr
133
+ %|td
134
+ C?
135
+ %|td
136
+ returns `true` if C passes; `false` otherwise
137
+
63
138
 
64
139
  %|section "Failures"
140
+
65
141
  When an assertion fails, details about the failure will be shown:
66
142
 
67
- <pre>
68
- - fail: block must yield true (!nil && !false)
69
- code: |-
70
- [12..22] in test/simple.rb
71
- 12
72
- 13 D "with more nested tests" do
73
- 14 x = 5
74
- 15
75
- 16 T { x > 2 } # passes
76
- => 17 F { x > 2 } # fails
77
- 18 E { x.hello } # passes
78
- 19 end
79
- 20 end
80
- 21
81
- 22 # equivalent of before(:each) or setup()
82
- vars:
83
- x: 5
84
- y: 83
85
- call:
86
- - test/simple.rb:17
87
- - test/simple.rb:3
88
- </pre>
143
+ - fail: block must yield true (!nil && !false)
144
+ code: |-
145
+ [12..22] in test/simple.rb
146
+ 12
147
+ 13 D "with more nested tests" do
148
+ 14 x = 5
149
+ 15
150
+ 16 T { x > 2 } # passes
151
+ => 17 F { x > 2 } # fails
152
+ 18 E { x.hello } # passes
153
+ 19 end
154
+ 20 end
155
+ 21
156
+ 22 # equivalent of before(:each) or setup()
157
+ vars:
158
+ x: 5
159
+ y: 83
160
+ call:
161
+ - test/simple.rb:17
162
+ - test/simple.rb:3
89
163
 
90
164
  You will then be placed into a debugger to investigate the failure if the `:debug` option is enabled in [`Dfect.options`](<%= dfect_api %>).
91
165
 
92
166
  Details about all assertion failures and a trace of all tests executed are stored by <%= $project %> and provided by the [`Dfect.report`](<%= dfect_api %>) method.
93
167
 
168
+
94
169
  %|section "Tests"
170
+
95
171
  The [`D()` method](<%= dfect_api %>) defines a new **test**, which is analagous to the `describe()` environment provided by BDD frameworks like RSpec.
96
172
 
97
173
  A test may also contain nested tests.
98
174
 
99
- <code>
100
- D "outer test" do
101
- # assertions and logic here
175
+ %|code :ruby
176
+ D "outer test" do
177
+ # assertions and logic here
102
178
 
103
- D "inner test" do
104
- # more assertions and logic here
179
+ D "inner test" do
180
+ # more assertions and logic here
181
+ end
105
182
  end
106
- end
107
- </code>
183
+
108
184
 
109
185
  %|section "Hooks"
186
+
110
187
  The [`D()` method](<%= dfect_api %>) provides several entry points (hooks) into the test execution process:
111
188
 
112
- <code>
113
- D "outer test" do
114
- D .< { puts "before each nested test" }
115
- D .> { puts "after each nested test" }
116
- D .<< { puts "before all nested tests" }
117
- D .>> { puts "after all nested tests" }
189
+ %|code :ruby
190
+ D "outer test" do
191
+ D .< { puts "before each nested test" }
192
+ D .> { puts "after each nested test" }
193
+ D .<< { puts "before all nested tests" }
194
+ D .>> { puts "after all nested tests" }
118
195
 
119
- D "inner test" do
120
- # assertions and logic here
196
+ D "inner test" do
197
+ # assertions and logic here
198
+ end
121
199
  end
122
- end
123
- </code>
124
200
 
125
201
  A hook method may be called multiple times. Each call registers additional logic to execute during the hook:
126
202
 
127
- <code>
128
- D .< { puts "do something" }
129
- D .< { puts "do something more!" }
130
- </code>
203
+ %|code :ruby
204
+ D .< { puts "do something" }
205
+ D .< { puts "do something more!" }
206
+
131
207
 
132
208
  %|section "Insulation"
209
+
133
210
  Use the singleton class of a temporary object to shield your test logic from Ruby's global environment, the code being tested, and from other tests:
134
211
 
135
- <code>
136
- class << Object.new
137
- # your test logic here
138
- end
139
- </code>
212
+ %|code :ruby
213
+ class << Object.new
214
+ # your test logic here
215
+ end
140
216
 
141
217
  Inside this insulated environment, you are free to:
142
218
  * mix-in any modules your test logic needs
@@ -144,107 +220,91 @@
144
220
 
145
221
  For example:
146
222
 
147
- <code>
148
- class << Object.new
149
- include SomeModule
150
- extend AnotherModule
223
+ %|code :ruby
224
+ class << Object.new
225
+ include SomeModule
226
+ extend AnotherModule
151
227
 
152
- YOUR_CONSTANT = 123
228
+ YOUR_CONSTANT = 123
153
229
 
154
- D "your tests here" do
155
- # your test logic here
230
+ D "your tests here" do
231
+ # your test logic here
156
232
 
157
- your_helper_method
158
- end
233
+ your_helper_method
234
+ end
159
235
 
160
- def self.your_helper_method
161
- # your helper logic here
236
+ def self.your_helper_method
237
+ # your helper logic here
162
238
 
163
- helper = YourHelperClass.new
164
- helper.do_something_helpful
239
+ helper = YourHelperClass.new
240
+ helper.do_something_helpful
165
241
 
166
- T { 2 + 2 != 5 }
167
- end
242
+ T { 2 + 2 != 5 }
243
+ end
168
244
 
169
- class YourHelperClass
170
- # your helper logic here
245
+ class YourHelperClass
246
+ # your helper logic here
247
+ end
171
248
  end
172
- end
173
- </code>
249
+
174
250
 
175
251
  %|section "Execution"
252
+
176
253
  You can configure test execution using:
177
254
 
178
- <code>
179
- Dfect.options = your_options_hash
180
- </code>
255
+ %|code :ruby
256
+ Dfect.options = your_options_hash
181
257
 
182
258
  You can execute all tests defined thus far using:
183
259
 
184
- <code>
185
- Dfect.run
186
- </code>
260
+ %|code :ruby
261
+ Dfect.run
187
262
 
188
263
  You can stop this execution at any time using:
189
264
 
190
- <code>
191
- Dfect.stop
192
- </code>
265
+ %|code :ruby
266
+ Dfect.stop
193
267
 
194
268
  You can view the results of execution using:
195
269
 
196
- <code>
197
- puts Dfect.report.to_yaml
198
- </code>
270
+ %|code :ruby
271
+ puts Dfect.report.to_yaml
272
+
273
+ See the [API documentation](<%= api_url %>) for details and examples.
199
274
 
200
- See the [API documentation](<%= dfect_api %>) for details and examples.
201
275
 
202
276
  %|section "Automatic test execution"
203
- <code>
204
- require 'rubygems'
205
- require 'dfect/auto' # <== notice the "auto"
206
- </code>
277
+
278
+ %|code :ruby
279
+ require 'rubygems' # only necessary if you are using Ruby 1.8
280
+ require 'dfect/auto' # <== notice the "auto"
207
281
 
208
282
  The above code will mix-in the `Dfect` module into your program and will execute all tests defined by your program before it terminates.
209
283
 
210
- %|example "A sample unit test"
211
- <code>
212
- require 'rubygems'
213
- require 'dfect/auto'
214
284
 
215
- D "a test" do
216
- D "a nested test" do
217
- end
285
+ %|section "Reporting"
218
286
 
219
- D "another nested test" do
220
- end
287
+ You can insert status messages, which can be arbitrary Ruby objects, into the execution report using the `Dfect::S()` method.
221
288
 
222
- D "a complex test" do
223
- y = 83
289
+ See the [API documentation](<%= api_url %>) for details and examples.
224
290
 
225
- D "with more nested tests" do
226
- x = 5
227
291
 
228
- T { x > 2 } # passes
229
- F { x > 2 } # fails
230
- E { x.hello } # passes
231
- end
232
- end
292
+ %|section "Emulation"
233
293
 
234
- D .< do
235
- puts "this is executed before every test in this scope"
236
- end
294
+ Dfect provides emulation layers for several popular testing libraries:
237
295
 
238
- D .> do
239
- puts "this is executed after every test in this scope"
240
- end
296
+ * <tt>dfect/unit</tt> --- Test::Unit
297
+ * <tt>dfect/mini</tt> --- Minitest
298
+ * <tt>dfect/spec</tt> --- RSpec
241
299
 
242
- D .<< do
243
- puts "this is executed once, before all tests in this scope"
244
- end
300
+ Simply `require()` one of these emulation layers into your test suite and you can write your tests using the familiar syntax of that testing library.
245
301
 
246
- D .>> do
247
- puts "this is executed once, after all tests in this scope"
248
- end
249
- end
250
- </code>
302
+ See the [API documentation](<%= api_url %>) for details and examples.
303
+
304
+
305
+ %|example! "A sample unit test"
306
+
307
+ The following code is from Dfect's very own test suite.
308
+
309
+ %|code :ruby
310
+ %< "../test/dfect.rb"
data/lib/dfect/auto.rb CHANGED
@@ -1,11 +1,11 @@
1
- #--
2
- # Copyright 2009 Suraj N. Kurapati
3
- # See the LICENSE file for details.
4
- #++
5
1
  # Provides painless, automatic configuration of Dfect.
6
2
  #
7
3
  # Simply require() this file and Dfect will be available for use anywhere
8
4
  # in your program and will execute all tests before your program exits.
5
+ #--
6
+ # Copyright protects this work.
7
+ # See LICENSE file for details.
8
+ #++
9
9
 
10
10
  require 'dfect'
11
11
 
data/lib/dfect/mini.rb CHANGED
@@ -1,7 +1,7 @@
1
1
  # MiniTest emulation layer.
2
2
  #--
3
- # Copyright 2009 Suraj N. Kurapati
4
- # See the LICENSE file for details.
3
+ # Copyright protects this work.
4
+ # See LICENSE file for details.
5
5
  #++
6
6
 
7
7
  require 'dfect'
@@ -21,6 +21,11 @@ end
21
21
  :wont => :refute,
22
22
  }.
23
23
  each do |outer, inner|
24
+ #
25
+ # XXX: using eval() because Ruby 1.8 does
26
+ # not support default values and
27
+ # block parameters in define_method()
28
+ #
24
29
  file, line = __FILE__, __LINE__ ; eval %{
25
30
  class Object
26
31
  def #{outer}_be_close_to other, message = nil
data/lib/dfect/spec.rb CHANGED
@@ -1,11 +1,10 @@
1
1
  # RSpec emulation layer.
2
2
  #--
3
- # Copyright 2009 Suraj N. Kurapati
4
- # See the LICENSE file for details.
3
+ # Copyright protects this work.
4
+ # See LICENSE file for details.
5
5
  #++
6
6
 
7
7
  require 'dfect'
8
- require 'delegate'
9
8
 
10
9
  module Kernel
11
10
  def describe *args, &block
data/lib/dfect/unit.rb CHANGED
@@ -1,7 +1,7 @@
1
1
  # Test::Unit emulation layer.
2
2
  #--
3
- # Copyright 2009 Suraj N. Kurapati
4
- # See the LICENSE file for details.
3
+ # Copyright protects this work.
4
+ # See LICENSE file for details.
5
5
  #++
6
6
 
7
7
  require 'dfect'
@@ -20,6 +20,11 @@ module Kernel
20
20
  [:assert_not, '!', 'not '],
21
21
  ].
22
22
  each do |prefix, polarity, action|
23
+ #
24
+ # XXX: using eval() because Ruby 1.8 does
25
+ # not support default values and
26
+ # block parameters in define_method()
27
+ #
23
28
  file, line = __FILE__, __LINE__ ; eval %{
24
29
  def #{prefix} boolean, message = nil
25
30
  Dfect.T#{polarity}(message) { boolean }
@@ -34,7 +39,7 @@ module Kernel
34
39
  Dfect.T#{polarity}(message) { collection.empty? }
35
40
  end
36
41
 
37
- def #{prefix}_equal actual, expected, message = nil
42
+ def #{prefix}_equal expected, actual, message = nil
38
43
  message ||= 'actual must #{action}equal expected'
39
44
  Dfect.T#{polarity}(message) { actual == expected }
40
45
  end
@@ -43,7 +48,9 @@ module Kernel
43
48
  message ||= 'actual must #{action}be within delta of expected'
44
49
  delta ||= 0.001
45
50
 
46
- Dfect.T#{polarity}(message) { Math.abs(expected - actual) <= Math.abs(delta) }
51
+ Dfect.T#{polarity}(message) do
52
+ Math.abs(expected - actual) <= Math.abs(delta)
53
+ end
47
54
  end
48
55
 
49
56
  alias #{prefix}_in_epsilon #{prefix}_in_delta
data/lib/dfect.rb CHANGED
@@ -1,6 +1,6 @@
1
1
  #--
2
- # Copyright 2009 Suraj N. Kurapati
3
- # See the LICENSE file for details.
2
+ # Copyright protects this work.
3
+ # See LICENSE file for details.
4
4
  #++
5
5
 
6
6
  require 'yaml'
@@ -524,6 +524,27 @@ module Dfect
524
524
  assert_catch :sample, message, symbol, &block
525
525
  end
526
526
 
527
+ ##
528
+ # Adds the given message to the report inside
529
+ # the section of the currently running test.
530
+ #
531
+ # You can think of "S" as "say" or "status".
532
+ #
533
+ # ==== Parameters
534
+ #
535
+ # [message]
536
+ # Objects to be added to the report.
537
+ #
538
+ # ==== Examples
539
+ #
540
+ # S "establishing connection..."
541
+ #
542
+ # S "beginning calculation...", Math::PI, [1, 2, 3, ['a', 'b', 'c']]
543
+ #
544
+ def S *message
545
+ @exec_trace.concat message
546
+ end
547
+
527
548
  ##
528
549
  # Executes all tests defined thus far and stores the results in #report.
529
550
  #
@@ -914,9 +935,9 @@ module Dfect
914
935
  # Allows before and after hooks to be specified via
915
936
  # the D() method syntax when this module is mixed-in:
916
937
  #
938
+ # D .<< { puts "before all nested tests" }
917
939
  # D .< { puts "before each nested test" }
918
940
  # D .> { puts "after each nested test" }
919
- # D .<< { puts "before all nested tests" }
920
941
  # D .>> { puts "after all nested tests" }
921
942
  #
922
943
  D = self
data/rakefile CHANGED
@@ -1,6 +1,6 @@
1
1
  #--
2
- # Copyright 2009 Suraj N. Kurapati
3
- # See the LICENSE file for details.
2
+ # Copyright protects this work.
3
+ # See LICENSE file for details.
4
4
  #++
5
5
 
6
6
  require 'rubygems'
@@ -8,8 +8,8 @@ gem 'inochi', '~> 1'
8
8
  require 'inochi'
9
9
 
10
10
  Inochi.init :Dfect,
11
- :version => '1.0.0',
12
- :release => '2009-05-03',
11
+ :version => '1.1.0',
12
+ :release => '2009-10-27',
13
13
  :website => 'http://snk.tuxfamily.org/lib/dfect/',
14
14
  :tagline => 'Assertion testing library for Ruby'
15
15
 
data/test/dfect.rb CHANGED
@@ -1,6 +1,6 @@
1
1
  #--
2
- # Copyright 2009 Suraj N. Kurapati
3
- # See the LICENSE file for details.
2
+ # Copyright protects this work.
3
+ # See LICENSE file for details.
4
4
  #++
5
5
 
6
6
  require 'dfect/auto'