procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation of ERT

Browse source 
* doc/misc/ert.texi (Running Tests Interactively)
(Test Selectors):
* lisp/emacs-lisp/ert.el (ert-select-tests)
(ert-run-tests-interactively, ert-run-tests-batch): Improve and
clarify the documentation of the main ERT functions.
This commit is contained in:
Eli Zaretskii 2024-08-15 11:30:48 +03:00
parent ed8904937e
commit 4f3e8c3b4e
2 changed files with 17 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

9
doc/misc/ert.texi
View file

@ -203,9 +203,12 @@ different Emacs versions.
@cindex interactive testing @cindex interactive testing
@findex ert @findex ert
@findex ert-run-tests-interactively
You can run the tests that are currently defined in your Emacs with the You can run the tests that are currently defined in your Emacs with the
command @kbd{M-x ert @key{RET} t @key{RET}}. (For an explanation of the command @kbd{M-x ert @key{RET} t @key{RET}} (which is an alias of
@code{t} argument, @pxref{Test Selectors}.) ERT will pop up a new @code{ert-run-tests-interactively}). The @code{t} argument means to run
all the defined tests, see @ref{Test Selectors}, which also explains how
to run only some specific part of the tests. ERT will pop up a new
buffer, the ERT results buffer, showing the results of the tests run. buffer, the ERT results buffer, showing the results of the tests run.
It looks like this: It looks like this:
@ -474,7 +477,7 @@ to Common Lisp's type specifier syntax:
@item @code{:failed} and @code{:passed} select tests according to their most recent result. @item @code{:failed} and @code{:passed} select tests according to their most recent result.
@item @code{:expected}, @code{:unexpected} select tests according to their most recent result. @item @code{:expected}, @code{:unexpected} select tests according to their most recent result.
@item A string is a regular expression that selects all tests with matching names. @item A string is a regular expression that selects all tests with matching names.
@item A test (i.e., an object of @code{ert-test} data type) selects that test. @item A test (i.e., an object of @code{ert-test} data type, see its doc string for details) selects that test.
@item A symbol selects the test that the symbol names. @item A symbol selects the test that the symbol names.
@item @code{(member @var{tests}...)} selects the elements of @item @code{(member @var{tests}...)} selects the elements of
@var{tests}, a list of tests or symbols naming tests. @var{tests}, a list of tests or symbols naming tests.

20
lisp/emacs-lisp/ert.el
View file

@ -932,14 +932,14 @@ of tests, or t, which refers to all tests named by symbols in `obarray'.
Valid SELECTORs: Valid SELECTORs:
nil -- Selects the empty set. nil -- Selects the empty set.
t -- Selects UNIVERSE. t -- Selects all of UNIVERSE. If UNIVERSE is t, selects all tests.
:new -- Selects all tests that have not been run yet. :new -- Selects all tests that have not been run yet.
:failed, :passed -- Select tests according to their most recent result. :failed, :passed -- Select tests according to their most recent result.
:expected, :unexpected -- Select tests according to their most recent result. :expected, :unexpected -- Select tests according to their most recent result.
a string -- A regular expression selecting all tests with matching names. a string -- A regular expression selecting all tests with matching names.
a test -- (i.e., an object of the ert-test data-type) Selects that test. a test -- (i.e., an object of the `ert-test' data-type) Selects that test.
a symbol -- Selects the test that the symbol names, signals an a symbol -- Selects the test named by the symbol, signals an
`ert-test-unbound' error if none. `ert-test-unbound' error if no such test.
\(member TESTS...) -- Selects the elements of TESTS, a list of tests \(member TESTS...) -- Selects the elements of TESTS, a list of tests
or symbols naming tests. or symbols naming tests.
\(eql TEST) -- Selects TEST, a test or a symbol naming a test. \(eql TEST) -- Selects TEST, a test or a symbol naming a test.
@ -1375,10 +1375,10 @@ RESULT must be an `ert-test-result-with-condition'."
(defun ert-run-tests-batch (&optional selector) (defun ert-run-tests-batch (&optional selector)
"Run the tests specified by SELECTOR, printing results to the terminal. "Run the tests specified by SELECTOR, printing results to the terminal.
SELECTOR works as described in `ert-select-tests', except if SELECTOR selects which tests to run as described in `ert-select-tests' when
SELECTOR is nil, in which case all tests rather than none will be called with its second argument t, except if SELECTOR is nil, in which case
run; this makes the command line \"emacs -batch -l my-tests.el -f all tests rather than none will be run; this makes the command line
ert-run-tests-batch-and-exit\" useful. \"emacs -batch -l my-tests.el -f ert-run-tests-batch-and-exit\" useful.
Returns the stats object." Returns the stats object."
(unless selector (setq selector 't)) (unless selector (setq selector 't))
@ -2240,7 +2240,9 @@ STATS is the stats object; LISTENER is the results listener."
(defun ert-run-tests-interactively (selector) (defun ert-run-tests-interactively (selector)
"Run the tests specified by SELECTOR and display the results in a buffer. "Run the tests specified by SELECTOR and display the results in a buffer.
SELECTOR works as described in `ert-select-tests'." SELECTOR selects which tests to run as described in `ert-select-tests'
when called with its second argument t. Interactively, prompt for
SELECTOR; the default t means run all the defined tests."
(interactive (interactive
(list (let ((default (if ert--selector-history (list (let ((default (if ert--selector-history
;; Can't use `first' here as this form is ;; Can't use `first' here as this form is