detest 3.1.1 → 3.1.2

data/lib/detest/inochi.rb

@@ -18,12 +18,12 @@ module Detest
   ##
   # Number of this release of this project.
   #
-  VERSION = '3.1.1'
+  VERSION = '3.1.2'
 
   ##
   # Date of this release of this project.
   #
-  RELDATE = '2010-08-08'
+  RELDATE = '2010-08-10'
 
   ##
   # Description of this release of this project.
@@ -74,7 +74,7 @@ module Detest
   #   }
   #
   DEVTIME = {
-    'inochi' => [ '>= 5.0.0', '< 6' ],
+    'inochi' => [ '>= 5.0.1', '< 6' ],
   }
 
   # establish gem version dependencies

data/man/man1/detest.1

@@ -2,12 +2,12 @@
 .\"     Title: detest
 .\"    Author: [see the "AUTHORS" section]
 .\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
-.\"      Date: 08/08/2010
+.\"      Date: 08/10/2010
 .\"    Manual: \ \&
-.\"    Source: \ \& 3.1.1
+.\"    Source: \ \& 3.1.2
 .\"  Language: English
 .\"
-.TH "DETEST" "1" "08/08/2010" "\ \& 3\&.1\&.1" "\ \&"
+.TH "DETEST" "1" "08/10/2010" "\ \& 3\&.1\&.2" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * set default formatting
 .\" -----------------------------------------------------------------
@@ -346,6 +346,252 @@ require \'detest/auto\'
 .\}
 .sp
 See the API documentation for more information and examples\&.
+.SH "ASSERTIONS"
+.SS "Writing assertions"
+.sp
+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 their failure reports if they fail\&.
+.TS
+tab(:);
+lt lt
+lt lt
+lt lt
+lt lt
+lt lt.
+T{
+.sp
+T()
+T}:T{
+.sp
+assert true (not nil and not false) \(em API documentation
+T}
+T{
+.sp
+F()
+T}:T{
+.sp
+assert not true (nil or false)  \(em API documentation
+T}
+T{
+.sp
+N()
+T}:T{
+.sp
+assert that the value is nil  \(em API documentation
+T}
+T{
+.sp
+E()
+T}:T{
+.sp
+assert that an execption is raised  \(em API documentation
+T}
+T{
+.sp
+C()
+T}:T{
+.sp
+assert that a symbol is thrown  \(em API documentation
+T}
+.TE
+.sp 1
+.sp
+For the T() and F() methods, you may alternatively pass the condition to be asserted as the first argument (instead of passing it as a block)\&. This might result in a more pleasing syntax, depending on your taste:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+my_ticket = rand()
+winning_ticket = rand()
+
+# passing the condition as a block:
+T("I won?!  Dream on\&.") { my_ticket != winning_ticket }
+F("I won?!  Dream on\&.") { my_ticket == winning_ticket }
+
+# passing the condition as an argument:
+T my_ticket != winning_ticket, "I won?!  Dream on\&."
+F my_ticket == winning_ticket, "I won?!  Dream on\&."
+.fi
+.if n \{\
+.RE
+.\}
+.SS "Negating assertions"
+.sp
+The following methods are the \fIopposite\fR of normal assertions\&.
+.TS
+tab(:);
+lt lt
+lt lt
+lt lt
+lt lt
+lt lt.
+T{
+.sp
+T!()
+T}:T{
+.sp
+same as F()  \(em API documentation
+T}
+T{
+.sp
+F!()
+T}:T{
+.sp
+same as T()  \(em API documentation
+T}
+T{
+.sp
+N!()
+T}:T{
+.sp
+assert that value is not nil  \(em API documentation
+T}
+T{
+.sp
+E!()
+T}:T{
+.sp
+assert that an exception is \fInot\fR raised  \(em API documentation
+T}
+T{
+.sp
+C!()
+T}:T{
+.sp
+assert that a symbol is \fInot\fR thrown  \(em API documentation
+T}
+.TE
+.sp 1
+.SS "Sampling assertions"
+.sp
+The following methods let you \fIcheck the outcome\fR of an assertion without recording a success or failure in the test execution report\&.
+.TS
+tab(:);
+lt lt
+lt lt
+lt lt
+lt lt
+lt lt.
+T{
+.sp
+T?()
+T}:T{
+.sp
+returns true if T() passes; false otherwise \(em API documentation
+T}
+T{
+.sp
+F?()
+T}:T{
+.sp
+returns true if F() passes; false otherwise \(em API documentation
+T}
+T{
+.sp
+N?()
+T}:T{
+.sp
+returns true if N() passes; false otherwise \(em API documentation
+T}
+T{
+.sp
+E?()
+T}:T{
+.sp
+returns true if E() passes; false otherwise \(em API documentation
+T}
+T{
+.sp
+C?()
+T}:T{
+.sp
+returns true if C() passes; false otherwise \(em API documentation
+T}
+.TE
+.sp 1
+.SS "Assertion failure reports"
+.sp
+Assertions failures are reported in the following manner:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+\- fail: block must yield true (!nil && !false)
+  call:
+  \- test/simple\&.rb:17
+  \- test/simple\&.rb:3
+  code: |\-
+    [12\&.\&.22] in test/simple\&.rb
+       12
+       13     D "with more nested tests" do
+       14       x = 5
+       15
+       16       T { x > 2 }   # passes
+    => 17       F { x > 2 }   # fails
+       18       E { x\&.hello } # passes
+       19     end
+       20   end
+       21
+       22   # equivalent of before(:each) or setup()
+  bind: test/simple\&.rb:17
+  vars:
+    x: (Fixnum) 5
+    y: (Fixnum) 83
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Failure reports are composed of the following sections:
+.TS
+tab(:);
+lt lt
+lt lt
+lt lt
+lt lt
+lt lt.
+T{
+.sp
+:fail
+T}:T{
+.sp
+Description of the assertion failure\&.
+T}
+T{
+.sp
+:call
+T}:T{
+.sp
+Stack trace leading to the point of failure\&.
+T}
+T{
+.sp
+:code
+T}:T{
+.sp
+Source code surrounding the point of failure\&.
+T}
+T{
+.sp
+:bind
+T}:T{
+.sp
+Source location of values in :vars section\&.
+T}
+T{
+.sp
+:vars
+T}:T{
+.sp
+Local variables visible at the point of failure\&.
+T}
+.TE
+.sp 1
+.sp
+After the failure is reported, you will be placed into a debugger to investigate the failure if the Detest\&.debug option is enabled\&.
+.sp
+Assertion failure reports can be accessed at any time within the test execution trace provided by the Detest\&.trace() method\&.
 .SH "TESTS"
 .SS "Defining tests"
 .sp
@@ -370,9 +616,25 @@ end
 A test may contain nested tests, as illustrated above\&.
 .SS "Insulating tests"
 .sp
-The D!() method defines a new test that is explicitly insulated from the tests that contain it and also from the top\-level Ruby environment\&. Root\-level calls to the D() method are insulated by default\&.
+The D!() method defines a new test that is explicitly insulated from the tests that contain it and also from the top\-level Ruby environment\&.
 .sp
 Inside an insulated test, you are free to mix\-in (using the \fBextend\fR keyword, not the \fBinclude\fR keyword) any modules your test logic needs\&. You can also define your own constants, methods, classes, and modules here\&.
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBNote\fR
+.ps -1
+.br
+.sp
+Root\-level calls to the D() method are insulated by default\&.
+.sp .5v
+.RE
 .PP
 \fBExample\ \&1.\ \&Insulated and uninsulated tests\fR
 .sp
@@ -423,24 +685,14 @@ Detest will output the following:
   \- an inner, insulated test:
 \-\-\-
 pass: 10
-time: 0\&.009435692
+time: 0\&.009158971
 .fi
 .if n \{\
 .RE
 .\}
 .SS "Sharing tests"
-.TS
-tab(:);
-lt lt
-lt lt
-lt lt.
-T{
-.sp
-S()
-T}:T{
 .sp
-Mechanism for sharing code\&. It can be used in two ways:
-
+The S() method is a mechanism for sharing code\&. It can be used in two ways:
 .sp
 .RS 4
 .ie n \{\
@@ -463,23 +715,10 @@ When called with a block, it shares the given block (under a given identifier) f
 .\}
 When called without a block, it injects a previously shared block (under a given identifier) into the environment where it is called\&.
 .RE
-T}
-T{
 .sp
-S!()
-T}:T{
+The S!() method is a combination of the two uses of the S() method: it lets you simultaneously share a block of code while injecting it into the environment where that method is called\&.
 .sp
-Combination of the two uses of the S() method: it lets you simultaneously share a block of code while injecting it into the environment where that method is called\&.
-T}
-T{
-.sp
-S?()
-T}:T{
-.sp
-Checks whether any code has been shared under a given identifier\&.
-T}
-.TE
-.sp 1
+The S?() method checks whether any code has been shared under a given identifier\&.
 .PP
 \fBExample\ \&2.\ \&Sharing code between tests\fR
 .sp
@@ -539,32 +778,16 @@ Detest will output the following:
   \- Power is power!
 \-\-\-
 pass: 3
-time: 0\&.007379665
+time: 0\&.007596486
 .fi
 .if n \{\
 .RE
 .\}
 .SS "Logging information"
-.TS
-tab(:);
-lt lt
-lt lt.
-T{
 .sp
-I()
-T}:T{
-.sp
-Mechanism for inserting arbitrary Ruby objects into the test execution report\&. You can think of this method as being a way \fIto inform\fR someone\&.
-T}
-T{
-.sp
-I!()
-T}:T{
+The I() method is a mechanism for inserting arbitrary Ruby objects into the test execution report\&. You can think of this method as being a way \fIto inform\fR someone\&.
 .sp
-Starts the interactive debugger at the location where it is called\&.
-T}
-.TE
-.sp 1
+The I!() method starts the interactive debugger at the location where it is called\&. You can think of this method as being a way \fIto investigate\fR the state of your program\&.
 .PP
 \fBExample\ \&3.\ \&Logging information in the execution report\fR
 .sp
@@ -603,7 +826,7 @@ Detest will output the following:
   \- Preparing spell to defeat mortal foes\&.\&.\&.
 \- Magician:
   \- Preparing rabbits to pull from hat\&.\&.\&.
-  \- 6
+  \- 8
 \- Calculator:
   \- 3\&.141592653589793
   \- \- 1
@@ -613,391 +836,137 @@ Detest will output the following:
       \- b
       \- c
   \- foo: bar!
-\-\-\-
-time: 0\&.00284595
-.fi
-.if n \{\
-.RE
-.\}
-.SS "Execution hooks"
-.sp
-A \fBhook\fR is a scheduled point of entry into the test execution process\&. The following \fBhook methods\fR allow you to register a block of code to execute when a hook occurs:
-.TS
-tab(:);
-lt lt
-lt lt
-lt lt
-lt lt.
-T{
-.sp
-D\&.<()
-T}:T{
-.sp
-Calls the given block \fIbefore each\fR child test\&.
-T}
-T{
-.sp
-D\&.>()
-T}:T{
-.sp
-Calls the given block \fIafter each\fR child test\&.
-T}
-T{
-.sp
-D\&.<<()
-T}:T{
-.sp
-Calls the given block \fIbefore all\fR child tests\&.
-T}
-T{
-.sp
-D\&.>>()
-T}:T{
-.sp
-Calls the given block \fIafter all\fR child tests\&.
-T}
-.TE
-.sp 1
-.sp
-A hook method can be called multiple times\&. Each additional call schedules more logic to be executed during the hook:
-.sp
-.if n \{\
-.RS 4
-.\}
-.nf
-D \&.< { puts "do something" }
-D \&.< { puts "do something more!" }
-.fi
-.if n \{\
-.RE
-.\}
-.PP
-\fBExample\ \&4.\ \&Using hooks to perform before and after actions\fR
-.sp
-When the following test is run:
-.sp
-.if n \{\
-.RS 4
-.\}
-.nf
-require \'detest/auto\'
-
-D "outer test" do
-  D \&.<  { I "(outer hook) before each" }
-  D \&.>  { I "(outer hook) after each" }
-  D \&.<< { I "(outer hook) before all" }
-  D \&.>> { I "(outer hook) after all" }
-
-  D "inner test 1" do
-    D \&.<  { I "(inner hook) before each" }
-    D \&.>  { I "(inner hook) after each" }
-    D \&.<< { I "(inner hook) before all" }
-    D \&.>> { I "(inner hook) after all" }
-
-    D "inner test 1\&.1" do
-      I "hello world"
-    end
-  end
-
-  D "inner test 2" do
-    I "goodbye world"
-  end
-
-  D \&.<  { I "(outer hook) before each, again" }
-  D \&.>  { I "(outer hook) after each, again" }
-end
-.fi
-.if n \{\
-.RE
-.\}
-.sp
-Detest will output the following:
-.sp
-.if n \{\
-.RS 4
-.\}
-.nf
-\-\-\-
-\- outer test:
-  \- (outer hook) before all
-  \- (outer hook) before each
-  \- (outer hook) before each, again
-  \- inner test 1:
-    \- (inner hook) before all
-    \- (inner hook) before each
-    \- inner test 1\&.1:
-      \- hello world
-    \- (inner hook) after each
-    \- (inner hook) after all
-  \- (outer hook) after each
-  \- (outer hook) after each, again
-  \- (outer hook) before each
-  \- (outer hook) before each, again
-  \- inner test 2:
-    \- goodbye world
-  \- (outer hook) after each
-  \- (outer hook) after each, again
-  \- (outer hook) after all
-\-\-\-
-time: 0\&.007706195
-.fi
-.if n \{\
-.RE
-.\}
-.SH "ASSERTIONS"
-.SS "Writing assertions"
-.sp
-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 their failure reports if they fail\&.
-.TS
-tab(:);
-lt lt
-lt lt
-lt lt
-lt lt
-lt lt.
-T{
-.sp
-T()
-T}:T{
-.sp
-assert true (not nil and not false)
-T}
-T{
-.sp
-F()
-T}:T{
-.sp
-assert not true (nil or false)
-T}
-T{
-.sp
-N()
-T}:T{
-.sp
-assert that the value is nil
-T}
-T{
-.sp
-E()
-T}:T{
-.sp
-assert that an execption is raised
-T}
-T{
-.sp
-C()
-T}:T{
-.sp
-assert that a symbol is thrown
-T}
-.TE
-.sp 1
-.sp
-For the T() and F() methods, you may alternatively pass the condition to be asserted as the first argument (instead of passing it as a block)\&. This might result in a more pleasing syntax, depending on your taste:
-.sp
-.if n \{\
-.RS 4
-.\}
-.nf
-D "Lottery" do
-  winning_ticket = rand()
-
-  D "My chances of winning" do
-    my_ticket = rand()
-
-    #
-    # Option 1: passing the condition as a block:
-    #
-    F("I won?!  Dream on\&.") { my_ticket == winning_ticket }
-
-    #
-    # Option 2: passing the condition as an argument:
-    #
-    F my_ticket == winning_ticket, "I won?!  Dream on\&."
-
-  end
-end
+\-\-\-
+time: 0\&.002930334
 .fi
 .if n \{\
 .RE
 .\}
-.SS "Negating assertions"
-.sp
-The following methods are the \fIopposite\fR of normal assertions\&.
-.TS
-tab(:);
-lt lt
-lt lt
-lt lt
-lt lt
-lt lt.
-T{
-.sp
-T!()
-T}:T{
-.sp
-same as F()
-T}
-T{
-.sp
-F!()
-T}:T{
-.sp
-same as T()
-T}
-T{
-.sp
-N!()
-T}:T{
-.sp
-assert that value is not nil
-T}
-T{
-.sp
-E!()
-T}:T{
-.sp
-assert that an exception is \fInot\fR raised
-T}
-T{
-.sp
-C!()
-T}:T{
-.sp
-assert that a symbol is \fInot\fR thrown
-T}
-.TE
-.sp 1
-.SS "Sampling assertions"
+.SS "Execution hooks"
 .sp
-The following methods let you \fIcheck the outcome\fR of an assertion without recording a success or failure in the test execution report\&.
+A \fBhook\fR is a scheduled point of entry into the test execution process\&. The following \fBhook methods\fR allow you to register a block of code to execute when a hook occurs:
 .TS
 tab(:);
 lt lt
 lt lt
 lt lt
-lt lt
 lt lt.
 T{
 .sp
-T?()
-T}:T{
-.sp
-returns true if T() passes; false otherwise
-T}
-T{
-.sp
-F?()
+D\&.<()
 T}:T{
 .sp
-returns true if F() passes; false otherwise
+calls the given block \fIbefore each\fR child test \(em API documentation
 T}
 T{
 .sp
-N?()
+D\&.>()
 T}:T{
 .sp
-returns true if N() passes; false otherwise
+calls the given block \fIafter each\fR child test  \(em API documentation
 T}
 T{
 .sp
-E?()
+D\&.<<()
 T}:T{
 .sp
-returns true if E() passes; false otherwise
+calls the given block \fIbefore all\fR child tests \(em API documentation
 T}
 T{
 .sp
-C?()
+D\&.>>()
 T}:T{
 .sp
-returns true if C() passes; false otherwise
+calls the given block \fIafter all\fR child tests  \(em API documentation
 T}
 .TE
 .sp 1
-.SS "Assertion failure reports"
 .sp
-Assertions failures are reported in the following manner:
+A hook method can be called multiple times\&. Each additional call schedules more logic to be executed during the hook:
 .sp
 .if n \{\
 .RS 4
 .\}
 .nf
-\- fail: block must yield true (!nil && !false)
-  call:
-  \- test/simple\&.rb:17
-  \- test/simple\&.rb:3
-  code: |\-
-    [12\&.\&.22] in test/simple\&.rb
-       12
-       13     D "with more nested tests" do
-       14       x = 5
-       15
-       16       T { x > 2 }   # passes
-    => 17       F { x > 2 }   # fails
-       18       E { x\&.hello } # passes
-       19     end
-       20   end
-       21
-       22   # equivalent of before(:each) or setup()
-  bind: test/simple\&.rb:17
-  vars:
-    x: (Fixnum) 5
-    y: (Fixnum) 83
+D \&.< { puts "do something" }
+D \&.< { puts "do something more!" }
 .fi
 .if n \{\
 .RE
 .\}
+.PP
+\fBExample\ \&4.\ \&Using hooks to perform before and after actions\fR
 .sp
-Failure reports are composed of the following sections:
-.TS
-tab(:);
-lt lt
-lt lt
-lt lt
-lt lt
-lt lt.
-T{
-.sp
-:fail
-T}:T{
-.sp
-Description of the assertion failure\&.
-T}
-T{
-.sp
-:call
-T}:T{
-.sp
-Stack trace leading to the point of failure\&.
-T}
-T{
-.sp
-:code
-T}:T{
-.sp
-Source code surrounding the point of failure\&.
-T}
-T{
-.sp
-:bind
-T}:T{
-.sp
-Source location of values in :vars section\&.
-T}
-T{
-.sp
-:vars
-T}:T{
+When the following test is run:
 .sp
-Local variables visible at the point of failure\&.
-T}
-.TE
-.sp 1
+.if n \{\
+.RS 4
+.\}
+.nf
+require \'detest/auto\'
+
+D "outer test" do
+  D \&.<  { I "(outer hook) before each" }
+  D \&.>  { I "(outer hook) after each" }
+  D \&.<< { I "(outer hook) before all" }
+  D \&.>> { I "(outer hook) after all" }
+
+  D "inner test 1" do
+    D \&.<  { I "(inner hook) before each" }
+    D \&.>  { I "(inner hook) after each" }
+    D \&.<< { I "(inner hook) before all" }
+    D \&.>> { I "(inner hook) after all" }
+
+    D "inner test 1\&.1" do
+      I "hello world"
+    end
+  end
+
+  D "inner test 2" do
+    I "goodbye world"
+  end
+
+  D \&.<  { I "(outer hook) before each, again" }
+  D \&.>  { I "(outer hook) after each, again" }
+end
+.fi
+.if n \{\
+.RE
+.\}
 .sp
-After the failure is reported, you will be placed into a debugger to investigate the failure if the Detest\&.debug option is enabled\&.
+Detest will output the following:
 .sp
-Assertion failure reports can be accessed at any time within the test execution trace provided by the Detest\&.trace() method\&.
+.if n \{\
+.RS 4
+.\}
+.nf
+\-\-\-
+\- outer test:
+  \- (outer hook) before all
+  \- (outer hook) before each
+  \- (outer hook) before each, again
+  \- inner test 1:
+    \- (inner hook) before all
+    \- (inner hook) before each
+    \- inner test 1\&.1:
+      \- hello world
+    \- (inner hook) after each
+    \- (inner hook) after all
+  \- (outer hook) after each
+  \- (outer hook) after each, again
+  \- (outer hook) before each
+  \- (outer hook) before each, again
+  \- inner test 2:
+    \- goodbye world
+  \- (outer hook) after each
+  \- (outer hook) after each, again
+  \- (outer hook) after all
+\-\-\-
+time: 0\&.009311863
+.fi
+.if n \{\
+.RE
+.\}
 .SH "EMULATION"
 .sp
 Detest can emulate several popular testing libraries:
@@ -1819,6 +1788,68 @@ Its exit status will indicate whether all tests have passed\&. It may also print
 .sp
 Fork this project on GitHub and send a pull request\&.
 .SH "HISTORY"
+.SS "Version 3\&.1\&.2 (2010\-08\-10)"
+.sp
+This release adds links to API documentation beside methods mentioned in the help manual and restores metadata that was missing in the gem release package\&.
+.PP
+\fBHousekeeping\fR
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Upgrade to Inochi 5\&.0\&.1 to fix metadata generation in gemspec\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Introduce assertions before tests in help manual\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Make use of AsciiDoc admonitions and icon images\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Add links into API documentation for core methods\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Add test case to ensure that
+E()
+returns the exception that was raised\&.
+.RE
 .SS "Version 3\&.1\&.1 (2010\-08\-08)"
 .sp
 This release adds forgotten nil assertions and updates the help manual\&.

metadata

@@ -5,16 +5,16 @@ version: !ruby/object:Gem::Version
   segments: 
   - 3
   - 1
-  - 1
-  version: 3.1.1
+  - 2
+  version: 3.1.2
 platform: ruby
-authors: []
-
+authors: 
+- Suraj N. Kurapati
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2010-08-08 00:00:00 -07:00
+date: 2010-08-10 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -28,8 +28,8 @@ dependencies:
         segments: 
         - 5
         - 0
-        - 0
-        version: 5.0.0
+        - 1
+        version: 5.0.1
     - - <
       - !ruby/object:Gem::Version 
         segments: 
@@ -37,7 +37,7 @@ dependencies:
         version: "6"
   type: :development
   version_requirements: *id001
-description: ""
+description: Detest is an assertion testing library for the Ruby programming language. It features a simple assertion vocabulary, instant debuggability
 of failures, and flexibility in composing tests.
 email: 
 executables: 
 - detest