etest-result-mode.el: Prettier alignment of metadata output.
[ETest.git] / etest.texinfo
blobd36bfc690db1921585a67e9ed1d10607fba7844e
1 \input texinfo   @c -*-texinfo-*-
3 @setfilename etest.info
4 @settitle Emacs Testing Framework
6 @dircategory Emacs
7 @direntry
8 * ETest: (etest).           The Emacs Testing Framework
9 @end direntry
11 @copying
12 Copyright @copyright{} 2008 Philip Jackson.
13 @quotation
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".
20 @end quotation
21 @end copying
23 @titlepage
24 @title ETest - The Emacs Testing Framework
26 @page
27 @vskip 0pt plus 1filll
28 @insertcopying
29 @end titlepage
31 @ifhtml
32 @contents
33 @end ifhtml
35 @ifnottex
36 @node Top, Introduction, (dir), (dir)
37 @top ETest Manual 0.1
39 @menu
40 * Introduction::                Introduction to ETest.
41 * Fetching ETest::              How to download ETest.
42 * 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.
46 @end menu
47 @end ifnottex
49 @node Introduction, Fetching ETest, Top, Top
50 @chapter Introduction
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 one's 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
60 comment toggling.
62 @node Fetching ETest, Installation, Introduction, Top
63 @chapter Fetching ETest
65 At the time of writing you must download ETest using git:
67 @code{git clone http://repo.or.cz/r/ETest.git etest}
69 Though it will always be bleeding edge @code{master} should always be
70 in a @emph{working} state.
72 @node Installation, Usage, Fetching ETest, Top
73 @chapter Installation
75 To install ETest use one of the following methods:
77 @section Compiling ETest
79 Once you've fetched ETest change into the new directory and run
80 @code{make} if all goes well run @code{make install} (you may need
81 escalated privileges for this step).
83 @section Manual Installation
85 If you don't want to byte-compile for some reason then you can just
86 copy the @code{.el} files into a directory in your @var{load-path}.
88 If you would rather add the unpacked library @emph{to} your load path
89 then the following will work assuming the etest directory is in your
90 home directory:
92 @lisp
93 (add-to-list 'load-path "~/etest")
94 @end lisp
96 If you want to run tests from a lisp buffer add the following to your
97 initialistation file:
99 @lisp
100 ;; The only keybinding we make... hopefully
101 (add-hook 'emacs-lisp-mode-hook
102           (lambda ()
103             (local-set-key (kbd "C-c t") 'etest-execute)))
104 @end lisp
106 And to have @code{.etest} files load @code{emacs-lisp-mode} put the
107 following into your initialistation file:
109 @lisp
110 ;; Load lisp mode when editing an etest file
111 (add-to-list 'auto-mode-alist '("\\.etest$" . emacs-lisp-mode))
112 @end lisp
114 @node Usage, The results buffer, Installation, Top
115 @chapter Usage
117 First you must evaluate @code{(require 'etest)} then you can start
118 using the @code{etest} macro.
120 Using ETest is very simple. Once you have installed the modules then
121 you can simply run your first test like this:
123 @lisp
124 (etest (ok 1))
125 @end lisp
126 @noindent
128 This should pop up a results buffer showing you the outcome of the
129 run. In this case all should be ok because, well, 1 is a pass
130 according to the @code{ok} test.
132 @menu
133 * Example working practice::    How one might use etest.
134 @end menu
136 @node Example working practice
137 @section Example working practice
139 Generally (at least the way I work) is to have a @code{.etest} file
140 which matches all but the extension of the filename of the file I am
141 to test. So if I were testing a file called @code{find-cmd.el} I would
142 write my tests in a file called @code{find-cmd.etest} (in the same
143 directory as @code{find-cmd.el}) and then when I hit @kbd{C-c t} (in
144 @code{emacs-lisp-mode}) the run would happen and the results pop up in
145 their normal fashion.
147 Thanks to @file{etest-execute.el} there are several options for the
148 location of an etest file (one at a time). In order of execution they
149 are:
151 1. The buffer local variable @code{etest-file} is set to the filename
152 of the etest file.
154 2. A matching etest file is in the directories listed in
155 @code{etest-load-path}.
157 3. A matching etest file is in the current working directory
158 (@code{default-directory}).
160 At the moment it's impossible to have two etest structures defined in
161 one file @emph{and} see the results in one results buffer (at least in
162 the result mode that is bundled with ETest) as an @code{erase-buffer}
163 is executed (effectively) for each invocation of the @code{etest}
164 macro.
166 @node The results buffer, The Tests, Usage, Top
167 @chapter The results buffer
169 The results buffer is where you can see (and manipulate) the results
170 of a test run in a human friendly format. It will always popup when
171 etest is run and let you know how things went.
173 @menu
174 * Example output::              What the output looks like.
175 * Bindings::                    What commands you have at your disposal.
176 @end menu
178 @node Example output, Bindings, The results buffer, The results buffer
179 @section Example output
181 Given the hypothetical tests:
183 @lisp
184 (etest
185  ("Numeric comparisons"
186   ("Integers"
187    (ok (> 1 0) "one is more than 0")
188    (ok (< 1 0) "one is less than 0"))
189   ("Floats"
190    (ok (> 10 9.99))
191    (ok (< 1 -5.2) "one is less than 5.2"))))
192 @end lisp
193 @noindent
195 Once run give us the following in the results buffer:
197 @example
198 * Numeric comparisons
199 ** Integers
200    ok ................ one is more than 0
201                        # got: 't'
202    not ok ............ one is less than 0
203                        # got: 'nil'
204 ** Floats
205    ok ................ (ok (> 10 9.99))
206                        # got: 't'
207    not ok ............ one is less than 5.2
208                        # got: 'nil'
209 @end example
210 @noindent
212 All headings are foldable as are comments.
214 @node Bindings,  , Example output, The results buffer
215 @section Bindings
217 @table @kbd
218 @item q
219 @findex bury-buffer
220 Bury this results buffer.
221 @item #
222 @findex etest-rm-etest-rm-cycle-comments
223 Shift the values in @code{etest-rm-comment-visibility-types} and use
224 the @code{car} of that list to determine the visibility of comments.
225 @item <tab>
226 @findex etest-rm-toggle-headline
227 Toggle the visibility of a heading or test comment.
228 @end table
230 @node The Tests,  , The results buffer, Top
231 @chapter The Tests
233 Tests are always run within the @code{etest} form and usually always
234 evaluate their arguments. Tests will always have a defined number of
235 required arguments (for example @code{ok} requires one argument. Each
236 test also allows for one optional argument which is a custom
237 documentation string. If this argument is omitted then ETest will
238 generate one in its place. So, for example, if you used
239 @code{(etest (ok 1))} the doc string would be @code{"(ok 1)"} if you used
240 @code{(etest (ok 1 "Foo"))} the doc string would be @code{"Foo"}.
242 @menu
243 * Test Structure::              Basic structure of tests.
244 * Builtin Simple Tests::        Boolean checks.
245 * Builtin Equality Tests::      Are two things similar?
246 * Builtin Error Tests::         Test exception handling.
247 * Builtin String Tests::        Check a string matches an RE.
248 * Defining your own tests::     Extend ETest.
249 @end menu
251 @node Test Structure, Builtin Simple Tests, The Tests, The Tests
252 @section Test Structure
254 Tests can be grouped within headings by simply using a string as the
255 first element of a form like this:
257 @lisp
258 (etest
259  ("Simple tests"
260   (ok 1)))
261 @end lisp
262 @noindent
264 You can nest headings to your hearts content.
266 This will produce a set of results that follow the same hierarchical
267 pattern as the tests themselves. For example the above produces the
268 following structure:
270 @lisp
271 (("Simple tests"
272   (:result t :comments "got: '1'" :doc "(ok 1)")))
273 @end lisp
274 @noindent
276 The output in the results buffer is:
278 @example
279 * Simple tests
280   ok ................. (ok 1)
281                        # got: '1'
282 @end example
284 @node Builtin Simple Tests, Builtin Equality Tests, Test Structure, The Tests
285 @section Builtin Simple Tests
287 These basic tests allow you, basically, to check if a value is either
288 non-nil or nil.
290 @subsection ok
292 @code{ok} will only pass if its argument produces a non-nil result.
294 @lisp
295 (etest (ok (+ 1 1)))
296 @end lisp
297 @noindent
299 @subsection null
301 @code{null} will only pass if its argument produces a nil result.
303 @lisp
304 (etest (null nil))
305 @end lisp
306 @noindent
308 @node Builtin Equality Tests, Builtin Error Tests, Builtin Simple Tests, The Tests
309 @section Builtin Equality Tests
311 The following functions map to their lisp counterparts and so don't
312 really require much explanation. Evaluate each of the examples to
313 watch them pass.
315 Each take two forms which, post evaluation, are the objects to
316 compare.
318 @subsection eq
320 @lisp
321 (etest (eq 1 1))
322 @end lisp
323 @noindent
325 @subsection eql
327 @lisp
328 (etest (eql 1.1 1.1))
329 @end lisp
330 @noindent
332 @subsection equal
334 @lisp
335 (etest (equal '(1 2) '(1 2)))
336 @end lisp
337 @noindent
339 @node Builtin Error Tests, Builtin String Tests, Builtin Equality Tests, The Tests
340 @section Builtin Error Tests
342 These two functions each take one form.
344 @subsection error
346 This test will pass if an exception is raised. For example, cause a
347 divide by zero error (@code{(arith-error)}):
349 @lisp
350 (etest (error (/ 1 0)))
351 @end lisp
352 @noindent
354 @subsection noerror
356 This test will pass if no exception is raised. For example, a valid
357 division will not raise an error:
359 @lisp
360 (etest (noerror (/ 0 1)))
361 @end lisp
362 @noindent
364 @node Builtin String Tests, Defining your own tests, Builtin Error Tests, The Tests
365 @section Builtin String Tests
367 @subsection like
369 @code{like} takes two arguments a string and a regexp to test it against:
371 @lisp
372 (etest (like "Hello" "^H\\(e\\)"))
373 @end lisp
374 @noindent
376 Produces this in the results buffer:
378 @example
379  ok .................. (like "Hello" "^H\\(e\\)")
380                        # searching: 'Hello'
381                        # match   1: 'e'
382 @end example
383 @noindent
385 The grouping within the regular expression only affects the comments.
387 @node Defining your own tests,  , Builtin String Tests, The Tests
388 @section Defining your own tests
390 Defining your own tests is fairly trivial and where ETest becomes
391 really useful.
393 Each test must return a plist that has @code{:result} and, optionally,
394 @code{:comments} in it.
396 @code{:result} represents whether the test passed or failed non-nil
397 for a pass and nil for a fail.
399 The optional @code{:comments} are newline separated strings that might
400 help the user in their diagnosis of a problem. Comments should follow
401 the conventions set by the 'builtin' tests using keywords such as
402 'got:'.
404 To have ETest recognise the test as valid the @code{deftest} function
405 should be used. For example if I wanted to create a function that
406 took two arguments and tested the first was numerically greater than
407 the other I might do this:
409 @lisp
410 (defun etest-greater-than (one two)
411   (let* ((res (> one two)))
412     (list :result res
413           :comments (unless res
414                       (format "one: '%d'\ntwo: '%d'" one two)))))
415 @end lisp
416 @noindent
418 We let emacs take care of type errors (and any other type of error)
419 which is what all of the builtins do. Also it's worth noting that if
420 you want your arguments evaling you have to do it yourself.
422 Now we let ETest know this new function exists:
424 @lisp
425 (deftest '(> 2) 'etest-greater-than)
426 @end lisp
427 @noindent
429 So, the new function will be called @code{>}, it will take two arguments
430 and it calls maps to @code{etest-greater-than}.
432 @lisp
433 (deftest '(> 2) 'etest-greater-than)
434 @end lisp
435 @noindent
437 Now you can mix @code{>} with other tests:
439 @lisp
440 (etest
441  (ok "something")
442  (> 1 2 "one is more than two"))
443 @end lisp
444 @noindent
446 Which in the results buffer produces:
448 @example
449  ok .................. (ok "something")
450                        # got: '"something"'
451  not ok .............. one is more than two
452                        # one: '1'
453                        # two: '2'
454 @end example
455 @noindent
457 @bye