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

Last change on this file since 31148 was 31148, checked in by svnwiki, 6 years ago

Anonymous wiki edit for IP [180.22.74.163]: clarifying test-epsilon behavior on zero

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