man/man1/detest.1 in detest-3.1.1 vs man/man1/detest.1 in detest-3.1.2
- old
+ new
@@ -1,15 +1,15 @@
'\" t
.\" 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
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
@@ -344,10 +344,256 @@
.if n \{\
.RE
.\}
.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
The D() method creates a new \fBtest\fR, which is analagous to the \fBdescribe\fR keyword in [RSpec] and also to the concept of a "test case" in [xUnit]\&.
.sp
@@ -368,13 +614,29 @@
.\}
.sp
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
When the following test is run:
.sp
@@ -421,29 +683,19 @@
\- a root\-level test:
\- an inner, non\-insulated test:
\- 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{
+The S() method is a mechanism for sharing code\&. It can be used in two ways:
.sp
-Mechanism for sharing code\&. It can be used in two ways:
-
-.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
@@ -461,27 +713,14 @@
.sp -1
.IP " 2." 4.2
.\}
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
When the following test is run:
.sp
@@ -537,36 +776,20 @@
\- Strength is power!
\- King:
\- 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{
+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
-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{
-.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
When the following test is run:
.sp
@@ -601,22 +824,22 @@
\-\-\-
\- Wizard:
\- Preparing spell to defeat mortal foes\&.\&.\&.
\- Magician:
\- Preparing rabbits to pull from hat\&.\&.\&.
- \- 6
+ \- 8
\- Calculator:
\- 3\&.141592653589793
\- \- 1
\- 2
\- 3
\- \- a
\- b
\- c
\- foo: bar!
\-\-\-
-time: 0\&.00284595
+time: 0\&.002930334
.fi
.if n \{\
.RE
.\}
.SS "Execution hooks"
@@ -631,32 +854,32 @@
T{
.sp
D\&.<()
T}:T{
.sp
-Calls the given block \fIbefore each\fR child test\&.
+calls the given block \fIbefore each\fR child test \(em API documentation
T}
T{
.sp
D\&.>()
T}:T{
.sp
-Calls the given block \fIafter each\fR child test\&.
+calls the given block \fIafter each\fR child test \(em API documentation
T}
T{
.sp
D\&.<<()
T}:T{
.sp
-Calls the given block \fIbefore all\fR child tests\&.
+calls the given block \fIbefore all\fR child tests \(em API documentation
T}
T{
.sp
D\&.>>()
T}:T{
.sp
-Calls the given block \fIafter all\fR child tests\&.
+calls the given block \fIafter all\fR child tests \(em API documentation
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:
@@ -737,269 +960,15 @@
\- goodbye world
\- (outer hook) after each
\- (outer hook) after each, again
\- (outer hook) after all
\-\-\-
-time: 0\&.007706195
+time: 0\&.009311863
.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
-.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"
-.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
-T}
-T{
-.sp
-F?()
-T}:T{
-.sp
-returns true if F() passes; false otherwise
-T}
-T{
-.sp
-N?()
-T}:T{
-.sp
-returns true if N() passes; false otherwise
-T}
-T{
-.sp
-E?()
-T}:T{
-.sp
-returns true if E() passes; false otherwise
-T}
-T{
-.sp
-C?()
-T}:T{
-.sp
-returns true if C() passes; false otherwise
-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 "EMULATION"
.sp
Detest can emulate several popular testing libraries:
.TS
tab(:);
@@ -1817,9 +1786,71 @@
Its exit status will indicate whether all tests have passed\&. It may also print additional pass/fail information depending on the testing library used in the test/helper\&.rb file\&.
.SS "Contributing"
.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\&.
.PP
\fBBug fixes\fR