dfect 0.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/doc/intro.erb ADDED
@@ -0,0 +1,78 @@
1
+ %|chapter "Introduction"
2
+ %|project_summary
3
+ **<%= $project %>** is an assertion testing library for Ruby that emphasizes a simple assertion vocabulary, instant debuggability of failures, and flexibility in composing tests.
4
+
5
+ **<%= $project %>** is exciting because:
6
+ * It has only 5 methods to remember: D F E C T.
7
+ * It lets you debug assertion failures interactively.
8
+ * It keeps a detailed report of assertion failures.
9
+ * It lets you nest tests and execution hooks.
10
+ * It is implemented in a mere <%= `sloccount lib`[/^\d+/] %> lines of code.
11
+
12
+ These features distinguish **<%= $project %>** from the competition:
13
+ * [assert{ 2.0 }](http://assert2.rubyforge.org)
14
+ * [Verify](http://www.ruby-forum.com/topic/183354)
15
+ * [Testy](http://www.ruby-forum.com/topic/182798)
16
+
17
+ %|paragraph "Etymology"
18
+ **<%= $project %>** is named after the 5 methods it provides: D F E C T.
19
+
20
+ The name is also play on the word "defect", whereby the intentional misspelling of "defect" as "dfect" is a defect in itself! <tt>;-)</tt>
21
+
22
+ This wordplay is similar to [Mnesia](http://www.erlang.org/doc/apps/mnesia/index.html)'s play on the word "amnesia", whereby the intentional omission of the letter "A" indicates forgetfulness---the key characteristic of having amnesia. Clever!
23
+
24
+ %|section "Logistics"
25
+ * <%= xref "History", "Release notes" %> --- history of project releases.
26
+ * [Source code](http://github.com/sunaku/<%= $program %>) --- obtain via [Git](http://git.or.cz) or browse online.
27
+ * [API reference](api/index.html) --- documentation for source code.
28
+
29
+ To get help or provide feedback, simply
30
+ <%= xref "License", "contact the author(s)" %>.
31
+
32
+ %|paragraph "Version numbers"
33
+ **<%= $project %>** releases are numbered in *major.minor.patch*
34
+ form according to the [RubyGems rational versioning
35
+ policy](http://www.rubygems.org/read/chapter/7), which
36
+ can be summarized thus:
37
+
38
+ <table markdown="1">
39
+ <thead>
40
+ <tr>
41
+ <td rowspan="2">What increased in the version number?</td>
42
+ <td colspan="3">The increase indicates that the release:</td>
43
+ </tr>
44
+ <tr>
45
+ <th>Is backward compatible?</th>
46
+ <th>Has new features?</th>
47
+ <th>Has bug fixes?</th>
48
+ </tr>
49
+ </thead>
50
+ <tbody>
51
+ <tr>
52
+ <th>major</th>
53
+ <td style="background-color: #FFE4E1;">No</td>
54
+ <td>Yes</td>
55
+ <td>Yes</td>
56
+ </tr>
57
+ <tr>
58
+ <th>minor</th>
59
+ <td>Yes</td>
60
+ <td>Yes</td>
61
+ <td>Yes</td>
62
+ </tr>
63
+ <tr>
64
+ <th>patch</th>
65
+ <td>Yes</td>
66
+ <td style="background-color: #FFE4E1;">No</td>
67
+ <td>Yes</td>
68
+ </tr>
69
+ </tbody>
70
+ </table>
71
+
72
+ %|section "License"
73
+ %< "../LICENSE"
74
+
75
+ %|section "Credits"
76
+ **<%= $project %>** is made possible by
77
+ <%= xref "History", "contributions" %>
78
+ from users like you.
data/doc/setup.erb ADDED
@@ -0,0 +1,34 @@
1
+ %|chapter "Setup"
2
+ %|section "Requirements"
3
+ Your system needs the following software to run **<%= $project %>**.
4
+
5
+ | Software | Description | Notes |
6
+ | -------- | ----------- | ----- |
7
+ | [Ruby](http://ruby-lang.org) | Ruby language interpreter | Version 1.8.6, 1.8.7, and 1.9.1 have been tested successfully. |
8
+ | [RubyGems](http://rubygems.org) | Ruby packaging system | Version 1.3.1 is required. |
9
+ | [ruby-debug](http://www.datanoise.com/ruby-debug) | Interactive debugger | This is an _optional_ requirement; IRB will be used if this library is not available. |
10
+
11
+ %|section "Installation"
12
+ You can install **<%= $project %>** by running this command:
13
+
14
+ gem install <%= $program %>
15
+
16
+ %|section "Manifest"
17
+ You will see the following items inside **<%= $project %>**'s installation
18
+ directory:
19
+
20
+ * <tt>lib/</tt>
21
+
22
+ * <tt><%= $program %>.rb</tt> --- the main **<%= $project %>** library.
23
+
24
+ * <tt><%= $program %>/</tt>
25
+
26
+ * <tt>auto.rb</tt> --- automates test execution.
27
+
28
+ * <tt>doc/</tt>
29
+
30
+ * <tt>api/</tt> --- API reference documentation.
31
+
32
+ * <tt>index.erb</tt> --- source of this user manual.
33
+
34
+ * <tt>LICENSE</tt> --- copyright notice and legal conditions.
data/doc/usage.erb ADDED
@@ -0,0 +1,186 @@
1
+ % dfect_api = 'api/classes/Dfect.html'
2
+
3
+ %|chapter "Usage"
4
+ Begin by loading **<%= $project %>** into your program:
5
+
6
+ <code>
7
+ require 'rubygems'
8
+ require 'dfect'
9
+ </code>
10
+
11
+ Now you have access to the [`Dfect` module](<%= dfect_api %>), which provides mixin-able instance methods which are also directly-callable as module functions (class methods):
12
+
13
+ <code>
14
+ Dfect.D "hello" do
15
+ puts "world"
16
+ end
17
+
18
+ # the above is same as:
19
+
20
+ include Dfect
21
+
22
+ D "hello" do
23
+ puts "world"
24
+ end
25
+ </code>
26
+
27
+ The following sections explain these methods in detail.
28
+
29
+ %|section "Assertions"
30
+ The following methods take a block parameter and assert something about the result of executing that block. Follow the links into the API documentation for examples.
31
+
32
+ * [`T()`](<%= dfect_api %>) --- assert true (not nil and not false)
33
+ * [`F()`](<%= dfect_api %>) --- assert not true (nil or false)
34
+ * [`E()`](<%= dfect_api %>) --- assert that an execption is raised
35
+ * [`C()`](<%= dfect_api %>) --- assert that a symbol is caught
36
+
37
+ %|section "Failures"
38
+ When an assertion fails, the details about the failure will be shown like this:
39
+
40
+ <pre>
41
+ - a complex test:
42
+ - with more nested tests:
43
+ - fail: block must yield true (!nil && !false)
44
+ code: |-
45
+ [12..22] in test/simple.rb
46
+ 12
47
+ 13 D "with more nested tests" do
48
+ 14 x = 5
49
+ 15
50
+ 16 T { x > 2 } # passes
51
+ => 17 F { x > 2 } # fails
52
+ 18 E { x.hello } # fails
53
+ 19 end
54
+ 20 end
55
+ 21
56
+ 22 # equivalent of before(:each) or setup()
57
+ vars:
58
+ x: 5
59
+ y: 83
60
+ call:
61
+ - test/simple.rb:17
62
+ - test/simple.rb:3
63
+ </pre>
64
+
65
+ If the `:debug` option is enabled in [`Dfect.options`](<%= dfect_api %>), you will then be placed into a debugger to investigate the failure.
66
+
67
+ 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.
68
+
69
+ %|section "Tests"
70
+ The [`D()` method](<%= dfect_api %>) defines a new **test**, which is analagous to the `describe()` environment provided by BDD frameworks like RSpec.
71
+
72
+ A test may also contain nested tests.
73
+
74
+ <code>
75
+ D "outer test" do
76
+ # assertions and logic here
77
+
78
+ D "inner test" do
79
+ # more assertions and logic here
80
+ end
81
+ end
82
+ </code>
83
+
84
+ %|section "Hooks"
85
+ The [`D()` method](<%= dfect_api %>) provides several entry points (hooks) into the test execution process:
86
+
87
+ <code>
88
+ D "outer test" do
89
+ D .< { puts "before each nested test" }
90
+ D .> { puts "after each nested test" }
91
+ D .<< { puts "before all nested tests" }
92
+ D .>> { puts "after all nested tests" }
93
+
94
+ D "inner test" do
95
+ # assertions and logic here
96
+ end
97
+ end
98
+ </code>
99
+
100
+ A hook method may be called multiple times. Each call registers additional logic to execute during the hook:
101
+
102
+ <code>
103
+ D .< { puts "do something" }
104
+ D .< { puts "do something more!" }
105
+ </code>
106
+
107
+ %|section "Execution"
108
+ You can configure test execution using:
109
+
110
+ <code>
111
+ Dfect.options = your_options
112
+ </code>
113
+
114
+ You can execute all tests defined thus far using:
115
+
116
+ <code>
117
+ Dfect.run
118
+ </code>
119
+
120
+ You can stop this execution at any time using:
121
+
122
+ <code>
123
+ Dfect.stop
124
+ </code>
125
+
126
+ You can view the results of execution using:
127
+
128
+ <code>
129
+ puts Dfect.report.to_yaml
130
+ </code>
131
+
132
+ See the [API documentation](<%= dfect_api %>) for details and examples.
133
+
134
+ %|section "Automatic test execution"
135
+ <code>
136
+ require 'rubygems'
137
+ require 'dfect/auto' # <== notice the "auto"
138
+ </code>
139
+
140
+ The above code will mix-in the `Dfect` module into your program and will execute all tests defined by your program before it terminates.
141
+
142
+ %|example "A sample unit test"
143
+ <code>
144
+ require 'rubygems'
145
+ require 'dfect/auto'
146
+
147
+ D "a test" do
148
+ D "a nested test" do
149
+ end
150
+
151
+ D "another nested test" do
152
+ end
153
+
154
+ D "a complex test" do
155
+ y = 83
156
+
157
+ D "with more nested tests" do
158
+ x = 5
159
+
160
+ T { x > 2 } # passes
161
+ F { x > 2 } # fails
162
+ E { x.hello } # fails
163
+ end
164
+ end
165
+
166
+ # equivalent of before(:each) or setup()
167
+ D.< do
168
+ puts "this is executed before every test in this scope"
169
+ end
170
+
171
+ # equivalent of after(:each) or teardown()
172
+ D.> do
173
+ puts "this is executed after every test in this scope"
174
+ end
175
+
176
+ # equivalent of before(:all)
177
+ D.<< do
178
+ puts "this is executed once, before all tests in this scope"
179
+ end
180
+
181
+ # equivalent of after(:all)
182
+ D.>> do
183
+ puts "this is executed once, after all tests in this scope"
184
+ end
185
+ end
186
+ </code>
data/lib/dfect/auto.rb ADDED
@@ -0,0 +1,24 @@
1
+ #--
2
+ # Copyright 2009 Suraj N. Kurapati
3
+ # See the LICENSE file for details.
4
+ #++
5
+ # Provides painless, automatic configuration of Dfect.
6
+ #
7
+ # Simply require() this file and Dfect will be available for use anywhere
8
+ # in your program and will execute all tests before your program exits.
9
+
10
+ require 'dfect'
11
+
12
+ class Object
13
+ include Dfect
14
+ end
15
+
16
+ at_exit do
17
+ Dfect.run
18
+
19
+ # reflect number of failures in exit status
20
+ stats = Dfect.report[:statistics]
21
+ fails = stats[:failed_assertions] + stats[:uncaught_exceptions]
22
+
23
+ exit [fails, 255].min
24
+ end