\input texinfo
@c %**start of header
-@setfilename ../../info/ert
+@setfilename ../../info/ert.info
@settitle Emacs Lisp Regression Testing
+@documentencoding UTF-8
@c %**end of header
@dircategory Emacs misc features
@direntry
-* ERT: (ert). Emacs Lisp regression testing tool.
+* ERT: (ert). Emacs Lisp regression testing tool.
@end direntry
@copying
-Copyright @copyright{} 2008, 2010--2013 Free Software Foundation, Inc.
+Copyright @copyright{} 2008, 2010--2014 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
+Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below. A copy of the license
is included in the section entitled ``GNU Free Documentation License''.
@end quotation
@end copying
+@titlepage
+@title Emacs Lisp Regression Testing
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
@node Top
@top ERT: Emacs Lisp Regression Testing
+@insertcopying
+
ERT is a tool for automated testing in Emacs Lisp. Its main features
are facilities for defining tests, running them and reporting the
results, and for debugging test failures interactively.
@end detailmenu
@end menu
+@end ifnottex
@node Introduction
@chapter Introduction
If you know @code{defun}, the syntax of @code{ert-deftest} should look
familiar: This example defines a test named @code{pp-test-quote} that
-will pass if the three calls to @code{equal} all return true
-(non-nil).
+will pass if the three calls to @code{equal} all return non-@code{nil}.
@code{should} is a macro with the same meaning as @code{cl-assert} but
better error reporting. @xref{The @code{should} Macro}.
@example
Selector: t
-Passed: 31
-Failed: 2 (2 unexpected)
-Total: 33/33
+Passed: 31
+Skipped: 0
+Failed: 2 (2 unexpected)
+Total: 33/33
Started at: 2008-09-11 08:39:25-0700
Finished.
@item @code{(tag TAG)} selects all tests that have TAG on their tags list.
(Tags are optional labels you can apply to tests when you define them.)
@item @code{(satisfies PREDICATE)} selects all tests that satisfy PREDICATE,
-a function that takes a test as argument and returns non-nil if it is selected.
+a function that takes a test as argument and returns non-@code{nil} if
+it is selected.
@end itemize
Selectors that are frequently useful when selecting tests to run
@end example
In this example, @code{should} recorded the fact that (= (+ 1 2) 4)
-reduced to (= 3 4) before it reduced to nil. When debugging why the
+reduced to (= 3 4) before it reduced to @code{nil}. When debugging why the
test failed, it helps to know that the function @code{+} returned 3
here. ERT records the return value for any predicate called directly
within @code{should}.
In addition to @code{should}, ERT provides @code{should-not}, which
-checks that the predicate returns nil, and @code{should-error}, which
+checks that the predicate returns @code{nil}, and @code{should-error}, which
checks that the form called within it signals an error. An example
use of @code{should-error}:
@node Tests and Their Environment
@section Tests and Their Environment
+Sometimes, it doesn't make sense to run a test due to missing
+preconditions. A required Emacs feature might not be compiled in, the
+function to be tested could call an external binary which might not be
+available on the test machine, you name it. In this case, the macro
+@code{skip-unless} could be used to skip the test:
+
+@lisp
+(ert-deftest test-dbus ()
+ "A test that checks D-BUS functionality."
+ (skip-unless (featurep 'dbusbind))
+ ...)
+@end lisp
+
The outcome of running a test should not depend on the current state
of the environment, and each test should leave its environment in the
same state it found it in. In particular, a test should not depend on
An exception to this are messages that the code under test prints with
@code{message} and similar logging; tests should not bother restoring
-the @code{*Message*} buffer to its original state.
+the @file{*Message*} buffer to its original state.
The above guidelines imply that tests should avoid calling highly
customizable commands such as @code{find-file}, except, of course, if
predictable semantics like @code{with-temp-buffer}, @code{insert} or
@code{insert-file-contents-literally}, and to activate any desired mode
by calling the corresponding function directly, after binding the
-hook variables to nil. This avoids the above problems.
+hook variables to @code{nil}. This avoids the above problems.
@node Useful Techniques
that it returns. The explanation can be any object but should have a
comprehensible printed representation. If the return value of the
predicate needs no explanation for a given list of arguments, the
-explanation function should return nil.
+explanation function should return @code{nil}.
To associate an explanation function with a predicate, add the
property @code{ert-explainer} to the symbol that names the predicate.
HCoop / bpt / emacs.git / blobdiff