1 \input texinfo @c -*-texinfo-*-
3 @setfilename etest.info
4 @settitle Emacs Testing Framework
8 * ETest: (etest). The Emacs Testing Framework
12 Copyright @copyright{} 2008 Philip Jackson.
14 Permission is granted to copy, distribute and/or modify this document
15 under the terms of the GNU Free Documentation License, Version 1.1 or
16 any later version published by the Free Software Foundation; with no
17 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
18 copy of the license is included in the section entitled "GNU Free
19 Documentation License".
24 @title ETest - The Emacs Testing Framework
27 @vskip 0pt plus 1filll
36 @node Top, Introduction, (dir), (dir)
40 * Introduction:: Introduction to ETest.
41 * Installation:: How to get emacs to wear ETest.
43 * Usage:: How to use ETest.
44 * The results buffer:: Display of test results.
45 * The Tests:: Functions available for testing.
49 @node Introduction, Installation, Top, Top
52 ETest (or etest, if you like) is the Emacs Testing Framework. It is a
53 small modular system for writing unit tests in Emacs Lisp.
55 At time of writing ETest consists of two files. @file{etest.el}
56 provides the core test functionality. It defines the function
57 (actually, macro) @code{etest} which is usually ones entrance into a
58 test run. The file @file{etest-result-mode.el} adds functions that
59 allow the visualisation of a run with syntax highlighting, folding and
65 To install ETest use one of the following methods:
67 @section Compiling ETest
69 Once you've unpacked the tarball change into the new directory and run
70 @code{make} if all goes well run @code{make install} (you may need
71 escalated privileges for this step).
73 @section Manual Installation
75 If you don't want to byte-compile for some reason then you can just
76 copy the @code{.el} files into a directory in your @var{load-path}.
78 If you would rather add the unpacked library @emph{to} your load path
79 then the following will work assuming the etest directory is in your
83 (add-to-list 'load-path "~/etest")
89 First you must evaluate @code{(require 'etest)} then you can start
90 using the @code{etest} macro.
92 Using ETest is very simple. Once you have installed the modules then
93 you can simply run your first test like this:
100 This should pop up a results buffer showing you the outcome of the
101 run. In this case all should be ok because, well, 1 is a pass
102 according to the @code{ok} test.
104 @node The results buffer
105 @chapter The results buffer
107 The results buffer is where you can see (and manipulate) the results
108 of a test run in a human friendly format. It will always popup when
109 etest is run and let you know how things went.
112 * Example output:: What the output looks like.
113 * Bindings:: What commands you have at your disposal.
117 @section Example output
119 Given the hypothetical tests:
123 ("Numeric comparisons"
125 (ok (> 1 0) "one is more than 0")
126 (ok (< 1 0) "one is less than 0"))
129 (ok (< 1 -5.2) "one is less than 5.2"))))
133 Once run give us the following in the results buffer:
136 * Numeric comparisons
138 ok ................ one is more than 0
140 not ok ............ one is less than 0
143 ok ................ (ok (> 10 9.99))
145 not ok ............ one is less than 5.2
150 All headings are foldable as are comments.
158 Bury this results buffer.
160 @findex etest-rm-etest-rm-cycle-comments
161 Shift the values in @code{etest-rm-comment-visibility-types} and use
162 the @code{car} of that list to determine the visibility of comments.
164 @findex etest-rm-toggle-headline
165 Toggle the visibility of a heading or test comment.
171 Tests are always run within the @code{etest} form and usually always
172 evaluate their arguments. Tests will always have a defined number of
173 required arguments (for example @code{ok} requires one argument. Each
174 test also allows for one optional argument which is a custom
175 documentation string. If this argument is omitted then ETest will
176 generate one in its place. So, for example, if you used
177 @code{(etest (ok 1))} the doc string would be @code{"(ok 1)"} if you used
178 @code{(etest (ok 1 "Foo"))} the doc string would be @code{"Foo"}.
181 * Test Structure:: Basic structure of tests.
182 * Builtin Simple Tests:: Boolean checks.
183 * Builtin Equality Tests:: Are two things similar?
184 * Builtin Error Tests:: Test exception handling.
185 * Builtin String Tests::
186 * Defining your own tests:: Extend ETest.
190 @section Test Structure
192 Tests can be grouped within headings by simply using a string as the
193 first element of a form like this:
202 You can nest headings to your hearts content.
204 This will produce a set of results that follow the same hierarchical
205 pattern as the tests themselves. For example the above produces the
210 (:result t :comments "got: '1'" :doc "(ok 1)")))
214 The output in the results buffer is:
218 ok ................. (ok 1)
222 @node Builtin Simple Tests
223 @section Builtin Simple Tests
225 These basic tests allow you, basically, to check if a value is either
230 @code{ok} will only pass if its argument produces a non-nil result.
239 @code{null} will only pass if its argument produces a nil result.
246 @node Builtin Equality Tests
247 @section Builtin Equality Tests
249 The following functions map to their lisp counterparts and so don't
250 really require much explanation. Evaluate each of the examples to
253 Each take two forms which, post evaluation, are the objects to
266 (etest (eql 1.1 1.1))
273 (etest (equal '(1 2) '(1 2)))
277 @node Builtin Error Tests
278 @section Builtin Error Tests
280 These two functions each take one form.
284 This test will pass if an exception is raised. For example, cause a
285 divide by zero error (@code{(arith-error)}):
288 (etest (error (/ 1 0)))
294 This test will pass if no exception is raised. For example, a valid
295 division will not raise an error:
298 (etest (noerror (/ 0 1)))
302 @node Builtin String Tests
303 @section Builtin String Tests
307 @code{like} takes two arguments a string and a regexp to test it against:
310 (etest (like "Hello" "^H\\(e\\)"))
314 Produces this in the results buffer:
317 ok .................. (like "Hello" "^H\\(e\\)")
323 The grouping within the regular expression only affects the comments.
325 @node Defining your own tests
326 @section Defining your own tests
328 Defining your own tests is fairly trivial and where ETest becomes
331 Each test must return a plist that has @code{:result} and, optionally,
332 @code{:comments} in it.
334 @code{:result} represents whether the test passed or failed non-nil
335 for a pass and nil for a fail.
337 The optional @code{:comments} are newline separated strings that might
338 help the user in their diagnosis of a problem. Comments should follow
339 the conventions set by the 'builtin' tests using keywords such as
342 To have ETest recognise the test as valid the @code{deftest} function
343 should be used. For example if I wanted to create a function that
344 took two arguments and tested the first was numerically greater than
345 the other I might do this:
348 (defun etest-greater-than (one two)
349 (let* ((res (> one two)))
351 :comments (unless res
352 (format "one: '%d'\ntwo: '%d'" one two)))))
356 We let emacs take care of type errors (and any other type of error)
357 which is what all of the builtins do. Also it's worth noting that if
358 you want your arguments evaling you have to do it yourself.
360 Now we let ETest know this new function exists:
363 (deftest '(> 2) 'etest-greater-than)
367 So, the new function will be called @code{>}, it will take two arguments
368 and it calls maps to @code{etest-greater-than}.
371 (deftest '(> 2) 'etest-greater-than)
375 Now you can mix @code{>} with other tests:
380 (> 1 2 "one is more than two"))
384 Which in the results buffer produces:
387 ok .................. (ok "something")
389 not ok .............. one is more than two