@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--2012 Free Software Foundation, Inc.
+Copyright @copyright{} 2008, 2010--2013 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@end quotation
@end copying
-@node Top, Introduction, (dir), (dir)
+@node Top
@top ERT: Emacs Lisp Regression Testing
ERT is a tool for automated testing in Emacs Lisp. Its main features
@end detailmenu
@end menu
-@node Introduction, How to Run Tests, Top, Top
+@node Introduction
@chapter Introduction
ERT allows you to define @emph{tests} in addition to functions,
Environment}.
-@node How to Run Tests, How to Write Tests, Introduction, Top
+@node How to Run Tests
@chapter How to Run Tests
You can run tests either in the Emacs you are working in, or on the
@end menu
-@node Running Tests Interactively, Running Tests in Batch Mode, How to Run Tests, How to Run Tests
+@node Running Tests Interactively
@section Running Tests Interactively
You can run the tests that are currently defined in your Emacs with
@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.
of the expression.
-@node Running Tests in Batch Mode, Test Selectors, Running Tests Interactively, How to Run Tests
+@node Running Tests in Batch Mode
@section Running Tests in Batch Mode
ERT supports automated invocations from the command line or from
files that it requires are on your @code{load-path}.
-@node Test Selectors, , Running Tests in Batch Mode, How to Run Tests
+@node Test Selectors
@section Test Selectors
Functions like @code{ert} accept a @emph{test selector}, a Lisp
@code{:causes-redisplay}.
-@node How to Write Tests, How to Debug Tests, How to Run Tests, Top
+@node How to Write Tests
@chapter How to Write Tests
ERT lets you define tests in the same way you define functions. You
* Useful Techniques:: Some examples.
@end menu
-@node The @code{should} Macro, Expected Failures, How to Write Tests, How to Write Tests
+@node The @code{should} Macro
@section The @code{should} Macro
Test bodies can include arbitrary code; but to be useful, they need to
@code{should} reports.
-@node Expected Failures, Tests and Their Environment, The @code{should} Macro, How to Write Tests
+@node Expected Failures
@section Expected Failures
Some bugs are complicated to fix, or not very important, and are left as
@end lisp
-@node Tests and Their Environment, Useful Techniques, Expected Failures, How to Write Tests
+@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
hook variables to nil. This avoids the above problems.
-@node Useful Techniques, , Tests and Their Environment, How to Write Tests
+@node Useful Techniques
@section Useful Techniques when Writing Tests
Testing simple functions that have no side effects and no dependencies
well.
-@node How to Debug Tests, Extending ERT, How to Write Tests, Top
+@node How to Debug Tests
@chapter How to Debug Tests
This section describes how to use ERT's features to understand why
@end menu
-@node Understanding Explanations, Interactive Debugging, How to Debug Tests, How to Debug Tests
+@node Understanding Explanations
@section Understanding Explanations
Failed @code{should} forms are reported like this:
function registered. @xref{Defining Explanation Functions}.
-@node Interactive Debugging, , Understanding Explanations, How to Debug Tests
+@node Interactive Debugging
@section Interactive Debugging
Debugging failed tests essentially works the same way as debugging any
@end itemize
-@node Extending ERT, Other Testing Concepts, How to Debug Tests, Top
+@node Extending ERT
@chapter Extending ERT
There are several ways to add functionality to ERT.
@end menu
-@node Defining Explanation Functions, Low-Level Functions for Working with Tests, Extending ERT, Extending ERT
+@node Defining Explanation Functions
@section Defining Explanation Functions
The explanation function for a predicate is a function that takes the
explanation function.
-@node Low-Level Functions for Working with Tests, , Defining Explanation Functions, Extending ERT
+@node Low-Level Functions for Working with Tests
@section Low-Level Functions for Working with Tests
Both @code{ert-run-tests-interactively} and @code{ert-run-tests-batch}
Contributions to ERT are welcome.
-@node Other Testing Concepts, GNU Free Documentation License , Extending ERT, Top
+@node Other Testing Concepts
@chapter Other Testing Concepts
For information on mocks, stubs, fixtures, or test suites, see below.
* Fixtures and Test Suites:: How ERT differs from tools for other languages.
@end menu
-@node Mocks and Stubs, Fixtures and Test Suites, Other Testing Concepts, Other Testing Concepts
+@node Mocks and Stubs
@section Other Tools for Emacs Lisp
Stubbing out functions or using so-called @emph{mocks} can make it
offers mocks for Emacs Lisp and can be used in conjunction with ERT.
-@node Fixtures and Test Suites, , Mocks and Stubs, Other Testing Concepts
+@node Fixtures and Test Suites
@section Fixtures and Test Suites
In many ways, ERT is similar to frameworks for other languages like
often. This can be achieved with the @code{:tag} argument to
@code{ert-deftest} and @code{tag} test selectors.
-@node GNU Free Documentation License, , Other Testing Concepts, Top
+@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi
HCoop / bpt / emacs.git / blobdiff