source: project/wiki/eggref/4/test @ 22036

Last change on this file since 22036 was 22036, checked in by Jim Ursetto, 9 years ago

wiki/test: light up syntax and procedures

File size: 5.1 KB
Line 
1[[tags: egg]]
2
3== test
4
5Yet another testing utility.
6
7[[toc:]]
8
9=== Usage
10
11<enscript language=scheme>
12(require-extension test)
13(test 4 (+ 2 2))
14</enscript>
15
16=== Interface
17
18This is designed to be as simple and friendly as possible.
19
20<syntax>(test [<name>] <expected-value> <expression>)</syntax>
21
22The basic test interface; really all you need to use.  It will catch errors and
23print informative failure messages, including the name
24(which defaults to an abbreviated form of the test expression),
25the source, and the line number information of the failed
26expression.  Equality is checked with EQUAL?, unless the expected
27value is inexact, in which case it checks to be sure the
28percentage difference between the result and expected value
29fall within the TEST-EPSILON parameter of each other.  This is
30because it almost never makes sense to test inexact numbers
31with EQUAL? or =, and usually you'll want a single epsilon
32throughout a range of tests.
33
34<syntax>(test-assert [<name>] <expression>)</syntax>
35<syntax>(test-error [<name>] <expression>)</syntax>
36
37Convenience wrappers around {{test}}. {{test-assert}} asserts that the
38expression is non-false; {{test-error}} asserts that the expression
39results in an error.
40
41<syntax>(test-begin [<name>])</syntax>
42<syntax>(test-end [<name>])</syntax>
43
44Test group reporting, including elapsed time and pass percentages,
45can be achieved using
46
47<enscript language=scheme>
48 (test-begin [<name>])
49 (test ...)
50 ...
51 (test-end [<name>])
52</enscript>
53
54where the group name is optional in either case.
55
56<syntax>(test-group <name> ...)</syntax>
57
58You can group tests in a single lexical scope (and also establish
59nested groups) with the {{test-group}} macro:
60
61<enscript language=scheme>
62 (test-group <name>
63   (test ...)
64   ...
65 )
66</enscript>
67
68The name for {{test-group}} is not optional.
69
70<procedure>(test-exit [<failure-exit-code>])</procedure>
71
72As a convenience there is a {{test-exit}} procedure, which
73exits the process with a status of 0 if all tests in all
74groups have passed, and with an optional numeric
75status (defaulting to 1), if there have been any failures
76or errors.
77
78=== Parameters
79
80All other aspects of testing are controlled by parameters.
81
82<parameter>current-test-verbosity</parameter>
83
84Default to {{#t}}, prints full diagnostics for failures
85
86<parameter>current-test-epsilon</parameter>
87
88Percentage difference allowed for inexact comparisons
89
90<parameter>current-test-comparator</parameter>
91
92{{TEST-EQUAL?}}
93
94<parameter>current-test-filters</parameter>
95
96List of predicates to filter (not run) tests
97
98<parameter>current-test-group-filters</parameter>
99
100List of predicates to filter entire test groups
101
102<parameter>current-test-applier</parameter>
103<parameter>current-test-handler</parameter>
104<parameter>current-test-skipper</parameter>
105<parameter>current-test-group-reporter</parameter>
106
107These parameters can be used to override the reporting
108behavior, for example if you wanted a GUI interface instead of
109the default textual reporting.
110
111=== Environment
112
113Often you'll be working on a change or new feature, and while the
114code is changing the test suite remains relatively constant.  However,
115it's a pain to recompile the test suite every time, and to re-run
116the entire suite when just working on one area, or even when you just
117want to run a single test by name.
118
119The parameters allow filtering, but it can be a pain to setup an
120interface to this or to recompile with different settings.  So for
121easy use, by default the parameters can be initialized from environment
122variables.
123
124{{CURRENT-TEST-FILTERS}} can be set by the environment variables {{TEST_FILTER}},
125a regexp which test names must match to be run, and {{TEST_REMOVE}}, a regexp
126of tests not to run.  For example, if you have your test suite in the
127file {{test-foo.scm}}, compiled to test-foo, and you only want to run the test
128named "test-foo-with-bells-on," you could do so with
129
130  $ TEST_FILTER=bells-on ./test-foo
131
132The test name defaults to the source expression, which can also be
133handy for quick filtering.  For instance, if in the same test suite
134you knew that you had broken the "flurble" data structure, you could
135filter out all tests using it with
136
137  $ TEST_REMOVE=flurble- ./test-foo
138
139For more structured filtering you can also filter by group.  The
140{{CURRENT-TEST-GROUP-FILTERS}} parameter can be initialized with the
141{{TEST_GROUP_FILTER}} and {{TEST_GROUP_REMOVE}} environment variables in
142the same way as above.
143
144You can also default the {{CURRENT-TEST-VERBOSITY}} parameter to {{#f}}
145by setting the {{TEST_QUIET}} environment variable.
146
147test tries to automatically determine if your terminal supports
148ANSI colors and uses them (sparingly, mostly so that failures
149and errors stand out).  You can force this on or off by setting
150the environment variable TEST_USE_ANSI variable to 0 or 1.
151
152=== License
153
154BSD
155
156=== Author
157
158Alex Shinn
159
160=== History
161
162; 0.9.9 : added regex dependency
163; 0.8 : Port to hygienic chicken [Peter Bex]
164; 0.7 : fix for dynamic test names w/o syntax-rules [Peter Bex]
165; 0.6 : adding several TERM settings to those recognized as ANSI
166; 0.5 : fixing spurious warning in nested groups
167; 0.4 : time reporting was off
168; 0.3 : minor bugfixes
169; 0.2 : minor bugfixes
170; 0.1 : initial release
Note: See TracBrowser for help on using the repository browser.