etest.texinfo: Updated to include download info.
[ETest.git] / etest.texinfo
blobcdae4a2edf7b00d459508c6ff52042869ed363a4
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 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
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 @node Usage, The results buffer, Installation, Top
97 @chapter Usage
99 First you must evaluate @code{(require 'etest)} then you can start
100 using the @code{etest} macro.
102 Using ETest is very simple. Once you have installed the modules then
103 you can simply run your first test like this:
105 @lisp
106 (etest (ok 1))
107 @end lisp
108 @noindent
110 This should pop up a results buffer showing you the outcome of the
111 run. In this case all should be ok because, well, 1 is a pass
112 according to the @code{ok} test.
114 @node The results buffer, The Tests, Usage, Top
115 @chapter The results buffer
117 The results buffer is where you can see (and manipulate) the results
118 of a test run in a human friendly format. It will always popup when
119 etest is run and let you know how things went.
121 @menu
122 * Example output::              What the output looks like.
123 * Bindings::                    What commands you have at your disposal.
124 @end menu
126 @node Example output, Bindings, The results buffer, The results buffer
127 @section Example output
129 Given the hypothetical tests:
131 @lisp
132 (etest
133  ("Numeric comparisons"
134   ("Integers"
135    (ok (> 1 0) "one is more than 0")
136    (ok (< 1 0) "one is less than 0"))
137   ("Floats"
138    (ok (> 10 9.99))
139    (ok (< 1 -5.2) "one is less than 5.2"))))
140 @end lisp
141 @noindent
143 Once run give us the following in the results buffer:
145 @example
146 * Numeric comparisons
147 ** Integers
148    ok ................ one is more than 0
149                        # got: 't'
150    not ok ............ one is less than 0
151                        # got: 'nil'
152 ** Floats
153    ok ................ (ok (> 10 9.99))
154                        # got: 't'
155    not ok ............ one is less than 5.2
156                        # got: 'nil'
157 @end example
158 @noindent
160 All headings are foldable as are comments.
162 @node Bindings,  , Example output, The results buffer
163 @section Bindings
165 @table @kbd
166 @item q
167 @findex bury-buffer
168 Bury this results buffer.
169 @item #
170 @findex etest-rm-etest-rm-cycle-comments
171 Shift the values in @code{etest-rm-comment-visibility-types} and use
172 the @code{car} of that list to determine the visibility of comments.
173 @item <tab>
174 @findex etest-rm-toggle-headline
175 Toggle the visibility of a heading or test comment.
176 @end table
178 @node The Tests,  , The results buffer, Top
179 @chapter The Tests
181 Tests are always run within the @code{etest} form and usually always
182 evaluate their arguments. Tests will always have a defined number of
183 required arguments (for example @code{ok} requires one argument. Each
184 test also allows for one optional argument which is a custom
185 documentation string. If this argument is omitted then ETest will
186 generate one in its place. So, for example, if you used
187 @code{(etest (ok 1))} the doc string would be @code{"(ok 1)"} if you used
188 @code{(etest (ok 1 "Foo"))} the doc string would be @code{"Foo"}.
190 @menu
191 * Test Structure::              Basic structure of tests.
192 * Builtin Simple Tests::        Boolean checks.
193 * Builtin Equality Tests::      Are two things similar?
194 * Builtin Error Tests::         Test exception handling.
195 * Builtin String Tests::        
196 * Defining your own tests::     Extend ETest.
197 @end menu
199 @node Test Structure, Builtin Simple Tests, The Tests, The Tests
200 @section Test Structure
202 Tests can be grouped within headings by simply using a string as the
203 first element of a form like this:
205 @lisp
206 (etest
207  ("Simple tests"
208   (ok 1)))
209 @end lisp
210 @noindent
212 You can nest headings to your hearts content.
214 This will produce a set of results that follow the same hierarchical
215 pattern as the tests themselves. For example the above produces the
216 following structure:
218 @lisp
219 (("Simple tests"
220   (:result t :comments "got: '1'" :doc "(ok 1)")))
221 @end lisp
222 @noindent
224 The output in the results buffer is:
226 @example
227 * Simple tests
228   ok ................. (ok 1)
229                        # got: '1'
230 @end example
232 @node Builtin Simple Tests, Builtin Equality Tests, Test Structure, The Tests
233 @section Builtin Simple Tests
235 These basic tests allow you, basically, to check if a value is either
236 non-nil or nil.
238 @subsection ok
240 @code{ok} will only pass if its argument produces a non-nil result.
242 @lisp
243 (etest (ok (+ 1 1)))
244 @end lisp
245 @noindent
247 @subsection null
249 @code{null} will only pass if its argument produces a nil result.
251 @lisp
252 (etest (null nil))
253 @end lisp
254 @noindent
256 @node Builtin Equality Tests, Builtin Error Tests, Builtin Simple Tests, The Tests
257 @section Builtin Equality Tests
259 The following functions map to their lisp counterparts and so don't
260 really require much explanation. Evaluate each of the examples to
261 watch them pass.
263 Each take two forms which, post evaluation, are the objects to
264 compare.
266 @subsection eq
268 @lisp
269 (etest (eq 1 1))
270 @end lisp
271 @noindent
273 @subsection eql
275 @lisp
276 (etest (eql 1.1 1.1))
277 @end lisp
278 @noindent
280 @subsection equal
282 @lisp
283 (etest (equal '(1 2) '(1 2)))
284 @end lisp
285 @noindent
287 @node Builtin Error Tests, Builtin String Tests, Builtin Equality Tests, The Tests
288 @section Builtin Error Tests
290 These two functions each take one form.
292 @subsection error
294 This test will pass if an exception is raised. For example, cause a
295 divide by zero error (@code{(arith-error)}):
297 @lisp
298 (etest (error (/ 1 0)))
299 @end lisp
300 @noindent
302 @subsection noerror
304 This test will pass if no exception is raised. For example, a valid
305 division will not raise an error:
307 @lisp
308 (etest (noerror (/ 0 1)))
309 @end lisp
310 @noindent
312 @node Builtin String Tests, Defining your own tests, Builtin Error Tests, The Tests
313 @section Builtin String Tests
315 @subsection like
317 @code{like} takes two arguments a string and a regexp to test it against:
319 @lisp
320 (etest (like "Hello" "^H\\(e\\)"))
321 @end lisp
322 @noindent
324 Produces this in the results buffer:
326 @example
327  ok .................. (like "Hello" "^H\\(e\\)")
328                        # searching: 'Hello'
329                        # match   1: 'e'
330 @end example
331 @noindent
333 The grouping within the regular expression only affects the comments.
335 @node Defining your own tests,  , Builtin String Tests, The Tests
336 @section Defining your own tests
338 Defining your own tests is fairly trivial and where ETest becomes
339 really useful.
341 Each test must return a plist that has @code{:result} and, optionally,
342 @code{:comments} in it.
344 @code{:result} represents whether the test passed or failed non-nil
345 for a pass and nil for a fail.
347 The optional @code{:comments} are newline separated strings that might
348 help the user in their diagnosis of a problem. Comments should follow
349 the conventions set by the 'builtin' tests using keywords such as
350 'got:'.
352 To have ETest recognise the test as valid the @code{deftest} function
353 should be used. For example if I wanted to create a function that
354 took two arguments and tested the first was numerically greater than
355 the other I might do this:
357 @lisp
358 (defun etest-greater-than (one two)
359   (let* ((res (> one two)))
360     (list :result res
361           :comments (unless res
362                       (format "one: '%d'\ntwo: '%d'" one two)))))
363 @end lisp
364 @noindent
366 We let emacs take care of type errors (and any other type of error)
367 which is what all of the builtins do. Also it's worth noting that if
368 you want your arguments evaling you have to do it yourself.
370 Now we let ETest know this new function exists:
372 @lisp
373 (deftest '(> 2) 'etest-greater-than)
374 @end lisp
375 @noindent
377 So, the new function will be called @code{>}, it will take two arguments
378 and it calls maps to @code{etest-greater-than}.
380 @lisp
381 (deftest '(> 2) 'etest-greater-than)
382 @end lisp
383 @noindent
385 Now you can mix @code{>} with other tests:
387 @lisp
388 (etest
389  (ok "something")
390  (> 1 2 "one is more than two"))
391 @end lisp
392 @noindent
394 Which in the results buffer produces:
396 @example
397  ok .................. (ok "something")
398                        # got: '"something"'
399  not ok .............. one is more than two
400                        # one: '1'
401                        # two: '2'
402 @end example
403 @noindent
405 @bye