From 4dd3796ffadafb9a9a485b7db499149cc990cf63 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Thu, 15 Aug 2024 11:30:48 +0300 Subject: [PATCH] Improve documentation of ERT * 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. (cherry picked from commit 4f3e8c3b4ed7b4d12fca9370e84e91b4b3379c7c) --- doc/misc/ert.texi | 9 ++++++--- lisp/emacs-lisp/ert.el | 20 +++++++++++--------- 2 files changed, 17 insertions(+), 12 deletions(-) diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi index 109dbd0f0ce..1ac0378148b 100644 --- a/doc/misc/ert.texi +++ b/doc/misc/ert.texi @@ -203,9 +203,12 @@ different Emacs versions. @cindex interactive testing @findex ert +@findex ert-run-tests-interactively 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 -@code{t} argument, @pxref{Test Selectors}.) ERT will pop up a new +command @kbd{M-x ert @key{RET} t @key{RET}} (which is an alias of +@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. 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{: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 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 @code{(member @var{tests}...)} selects the elements of @var{tests}, a list of tests or symbols naming tests. diff --git a/lisp/emacs-lisp/ert.el b/lisp/emacs-lisp/ert.el index 2a28dd6f3d2..93dcfc39d1b 100644 --- a/lisp/emacs-lisp/ert.el +++ b/lisp/emacs-lisp/ert.el @@ -932,14 +932,14 @@ of tests, or t, which refers to all tests named by symbols in `obarray'. Valid SELECTORs: 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. :failed, :passed -- 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 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 - `ert-test-unbound' error if none. +a test -- (i.e., an object of the `ert-test' data-type) Selects that test. +a symbol -- Selects the test named by the symbol, signals an + `ert-test-unbound' error if no such test. \(member TESTS...) -- Selects the elements of TESTS, a list of tests or symbols naming tests. \(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) "Run the tests specified by SELECTOR, printing results to the terminal. -SELECTOR works as described in `ert-select-tests', except if -SELECTOR is nil, in which case all tests rather than none will be -run; this makes the command line \"emacs -batch -l my-tests.el -f -ert-run-tests-batch-and-exit\" useful. +SELECTOR selects which tests to run as described in `ert-select-tests' when +called with its second argument t, except if SELECTOR is nil, in which case +all tests rather than none will be run; this makes the command line + \"emacs -batch -l my-tests.el -f ert-run-tests-batch-and-exit\" useful. Returns the stats object." (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) "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 (list (let ((default (if ert--selector-history ;; Can't use `first' here as this form is -- 2.39.2