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

Last change on this file since 20733 was 20733, checked in by felix winkelmann, 10 years ago

test doc update

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