Commit | Line | Data |
---|---|---|
15c9d04e | 1 | ;;; ert.el --- Emacs Lisp Regression Testing -*- lexical-binding: t -*- |
d221e780 | 2 | |
ab422c4d | 3 | ;; Copyright (C) 2007-2008, 2010-2013 Free Software Foundation, Inc. |
d221e780 CO |
4 | |
5 | ;; Author: Christian Ohler <ohler@gnu.org> | |
6 | ;; Keywords: lisp, tools | |
7 | ||
8 | ;; This file is part of GNU Emacs. | |
9 | ||
74bfe42a GM |
10 | ;; GNU Emacs is free software: you can redistribute it and/or modify |
11 | ;; it under the terms of the GNU General Public License as published by | |
12 | ;; the Free Software Foundation, either version 3 of the License, or | |
13 | ;; (at your option) any later version. | |
14 | ||
15 | ;; GNU Emacs is distributed in the hope that it will be useful, | |
16 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
18 | ;; GNU General Public License for more details. | |
19 | ||
d221e780 | 20 | ;; You should have received a copy of the GNU General Public License |
74bfe42a | 21 | ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. |
d221e780 CO |
22 | |
23 | ;;; Commentary: | |
24 | ||
25 | ;; ERT is a tool for automated testing in Emacs Lisp. Its main | |
26 | ;; features are facilities for defining and running test cases and | |
27 | ;; reporting the results as well as for debugging test failures | |
28 | ;; interactively. | |
29 | ;; | |
30 | ;; The main entry points are `ert-deftest', which is similar to | |
31 | ;; `defun' but defines a test, and `ert-run-tests-interactively', | |
32 | ;; which runs tests and offers an interactive interface for inspecting | |
33 | ;; results and debugging. There is also | |
34 | ;; `ert-run-tests-batch-and-exit' for non-interactive use. | |
35 | ;; | |
36 | ;; The body of `ert-deftest' forms resembles a function body, but the | |
37 | ;; additional operators `should', `should-not' and `should-error' are | |
38 | ;; available. `should' is similar to cl's `assert', but signals a | |
39 | ;; different error when its condition is violated that is caught and | |
40 | ;; processed by ERT. In addition, it analyzes its argument form and | |
41 | ;; records information that helps debugging (`assert' tries to do | |
42 | ;; something similar when its second argument SHOW-ARGS is true, but | |
43 | ;; `should' is more sophisticated). For information on `should-not' | |
44 | ;; and `should-error', see their docstrings. | |
45 | ;; | |
46 | ;; See ERT's info manual as well as the docstrings for more details. | |
47 | ;; To compile the manual, run `makeinfo ert.texinfo' in the ERT | |
48 | ;; directory, then C-u M-x info ert.info in Emacs to view it. | |
49 | ;; | |
50 | ;; To see some examples of tests written in ERT, see its self-tests in | |
51 | ;; ert-tests.el. Some of these are tricky due to the bootstrapping | |
52 | ;; problem of writing tests for a testing tool, others test simple | |
53 | ;; functions and are straightforward. | |
54 | ||
55 | ;;; Code: | |
56 | ||
15c9d04e | 57 | (eval-when-compile (require 'cl-lib)) |
d221e780 CO |
58 | (require 'button) |
59 | (require 'debug) | |
60 | (require 'easymenu) | |
61 | (require 'ewoc) | |
62 | (require 'find-func) | |
63 | (require 'help) | |
64 | ||
65 | ||
66 | ;;; UI customization options. | |
67 | ||
68 | (defgroup ert () | |
69 | "ERT, the Emacs Lisp regression testing tool." | |
70 | :prefix "ert-" | |
71 | :group 'lisp) | |
72 | ||
73 | (defface ert-test-result-expected '((((class color) (background light)) | |
74 | :background "green1") | |
75 | (((class color) (background dark)) | |
76 | :background "green3")) | |
77 | "Face used for expected results in the ERT results buffer." | |
78 | :group 'ert) | |
79 | ||
80 | (defface ert-test-result-unexpected '((((class color) (background light)) | |
81 | :background "red1") | |
82 | (((class color) (background dark)) | |
83 | :background "red3")) | |
84 | "Face used for unexpected results in the ERT results buffer." | |
85 | :group 'ert) | |
86 | ||
87 | ||
88 | ;;; Copies/reimplementations of cl functions. | |
89 | ||
90 | (defun ert--cl-do-remf (plist tag) | |
91 | "Copy of `cl-do-remf'. Modify PLIST by removing TAG." | |
92 | (let ((p (cdr plist))) | |
93 | (while (and (cdr p) (not (eq (car (cdr p)) tag))) (setq p (cdr (cdr p)))) | |
94 | (and (cdr p) (progn (setcdr p (cdr (cdr (cdr p)))) t)))) | |
95 | ||
96 | (defun ert--remprop (sym tag) | |
97 | "Copy of `cl-remprop'. Modify SYM's plist by removing TAG." | |
98 | (let ((plist (symbol-plist sym))) | |
99 | (if (and plist (eq tag (car plist))) | |
100 | (progn (setplist sym (cdr (cdr plist))) t) | |
101 | (ert--cl-do-remf plist tag)))) | |
102 | ||
103 | (defun ert--remove-if-not (ert-pred ert-list) | |
104 | "A reimplementation of `remove-if-not'. | |
105 | ||
106 | ERT-PRED is a predicate, ERT-LIST is the input list." | |
15c9d04e SM |
107 | (cl-loop for ert-x in ert-list |
108 | if (funcall ert-pred ert-x) | |
109 | collect ert-x)) | |
d221e780 CO |
110 | |
111 | (defun ert--intersection (a b) | |
112 | "A reimplementation of `intersection'. Intersect the sets A and B. | |
113 | ||
114 | Elements are compared using `eql'." | |
15c9d04e SM |
115 | (cl-loop for x in a |
116 | if (memql x b) | |
117 | collect x)) | |
d221e780 CO |
118 | |
119 | (defun ert--set-difference (a b) | |
120 | "A reimplementation of `set-difference'. Subtract the set B from the set A. | |
121 | ||
122 | Elements are compared using `eql'." | |
15c9d04e SM |
123 | (cl-loop for x in a |
124 | unless (memql x b) | |
125 | collect x)) | |
d221e780 CO |
126 | |
127 | (defun ert--set-difference-eq (a b) | |
128 | "A reimplementation of `set-difference'. Subtract the set B from the set A. | |
129 | ||
130 | Elements are compared using `eq'." | |
15c9d04e SM |
131 | (cl-loop for x in a |
132 | unless (memq x b) | |
133 | collect x)) | |
d221e780 CO |
134 | |
135 | (defun ert--union (a b) | |
136 | "A reimplementation of `union'. Compute the union of the sets A and B. | |
137 | ||
138 | Elements are compared using `eql'." | |
139 | (append a (ert--set-difference b a))) | |
140 | ||
141 | (eval-and-compile | |
142 | (defvar ert--gensym-counter 0)) | |
143 | ||
144 | (eval-and-compile | |
145 | (defun ert--gensym (&optional prefix) | |
146 | "Only allows string PREFIX, not compatible with CL." | |
147 | (unless prefix (setq prefix "G")) | |
148 | (make-symbol (format "%s%s" | |
149 | prefix | |
150 | (prog1 ert--gensym-counter | |
15c9d04e | 151 | (cl-incf ert--gensym-counter)))))) |
d221e780 CO |
152 | |
153 | (defun ert--coerce-to-vector (x) | |
154 | "Coerce X to a vector." | |
155 | (when (char-table-p x) (error "Not supported")) | |
156 | (if (vectorp x) | |
157 | x | |
158 | (vconcat x))) | |
159 | ||
15c9d04e | 160 | (cl-defun ert--remove* (x list &key key test) |
d221e780 CO |
161 | "Does not support all the keywords of remove*." |
162 | (unless key (setq key #'identity)) | |
163 | (unless test (setq test #'eql)) | |
15c9d04e SM |
164 | (cl-loop for y in list |
165 | unless (funcall test x (funcall key y)) | |
166 | collect y)) | |
d221e780 CO |
167 | |
168 | (defun ert--string-position (c s) | |
169 | "Return the position of the first occurrence of C in S, or nil if none." | |
15c9d04e SM |
170 | (cl-loop for i from 0 |
171 | for x across s | |
172 | when (eql x c) return i)) | |
d221e780 CO |
173 | |
174 | (defun ert--mismatch (a b) | |
175 | "Return index of first element that differs between A and B. | |
176 | ||
177 | Like `mismatch'. Uses `equal' for comparison." | |
178 | (cond ((or (listp a) (listp b)) | |
179 | (ert--mismatch (ert--coerce-to-vector a) | |
180 | (ert--coerce-to-vector b))) | |
181 | ((> (length a) (length b)) | |
182 | (ert--mismatch b a)) | |
183 | (t | |
184 | (let ((la (length a)) | |
185 | (lb (length b))) | |
15c9d04e SM |
186 | (cl-assert (arrayp a) t) |
187 | (cl-assert (arrayp b) t) | |
188 | (cl-assert (<= la lb) t) | |
189 | (cl-loop for i below la | |
190 | when (not (equal (aref a i) (aref b i))) return i | |
191 | finally (cl-return (if (/= la lb) | |
192 | la | |
193 | (cl-assert (equal a b) t) | |
194 | nil))))))) | |
d221e780 CO |
195 | |
196 | (defun ert--subseq (seq start &optional end) | |
197 | "Return a subsequence of SEQ from START to END." | |
198 | (when (char-table-p seq) (error "Not supported")) | |
199 | (let ((vector (substring (ert--coerce-to-vector seq) start end))) | |
15c9d04e | 200 | (cl-etypecase seq |
d221e780 CO |
201 | (vector vector) |
202 | (string (concat vector)) | |
203 | (list (append vector nil)) | |
15c9d04e SM |
204 | (bool-vector (cl-loop with result |
205 | = (make-bool-vector (length vector) nil) | |
206 | for i below (length vector) do | |
207 | (setf (aref result i) (aref vector i)) | |
208 | finally (cl-return result))) | |
209 | (char-table (cl-assert nil))))) | |
d221e780 CO |
210 | |
211 | (defun ert-equal-including-properties (a b) | |
212 | "Return t if A and B have similar structure and contents. | |
213 | ||
214 | This is like `equal-including-properties' except that it compares | |
215 | the property values of text properties structurally (by | |
216 | recursing) rather than with `eq'. Perhaps this is what | |
217 | `equal-including-properties' should do in the first place; see | |
218 | Emacs bug 6581 at URL `http://debbugs.gnu.org/cgi/bugreport.cgi?bug=6581'." | |
219 | ;; This implementation is inefficient. Rather than making it | |
220 | ;; efficient, let's hope bug 6581 gets fixed so that we can delete | |
221 | ;; it altogether. | |
de69c0a8 | 222 | (not (ert--explain-equal-including-properties a b))) |
d221e780 CO |
223 | |
224 | ||
225 | ;;; Defining and locating tests. | |
226 | ||
227 | ;; The data structure that represents a test case. | |
15c9d04e | 228 | (cl-defstruct ert-test |
d221e780 CO |
229 | (name nil) |
230 | (documentation nil) | |
15c9d04e | 231 | (body (cl-assert nil)) |
d221e780 CO |
232 | (most-recent-result nil) |
233 | (expected-result-type ':passed) | |
234 | (tags '())) | |
235 | ||
236 | (defun ert-test-boundp (symbol) | |
237 | "Return non-nil if SYMBOL names a test." | |
238 | (and (get symbol 'ert--test) t)) | |
239 | ||
240 | (defun ert-get-test (symbol) | |
241 | "If SYMBOL names a test, return that. Signal an error otherwise." | |
242 | (unless (ert-test-boundp symbol) (error "No test named `%S'" symbol)) | |
243 | (get symbol 'ert--test)) | |
244 | ||
245 | (defun ert-set-test (symbol definition) | |
246 | "Make SYMBOL name the test DEFINITION, and return DEFINITION." | |
247 | (when (eq symbol 'nil) | |
248 | ;; We disallow nil since `ert-test-at-point' and related functions | |
249 | ;; want to return a test name, but also need an out-of-band value | |
250 | ;; on failure. Nil is the most natural out-of-band value; using 0 | |
8350f087 | 251 | ;; or "" or signaling an error would be too awkward. |
d221e780 CO |
252 | ;; |
253 | ;; Note that nil is still a valid value for the `name' slot in | |
254 | ;; ert-test objects. It designates an anonymous test. | |
255 | (error "Attempt to define a test named nil")) | |
256 | (put symbol 'ert--test definition) | |
257 | definition) | |
258 | ||
259 | (defun ert-make-test-unbound (symbol) | |
260 | "Make SYMBOL name no test. Return SYMBOL." | |
261 | (ert--remprop symbol 'ert--test) | |
262 | symbol) | |
263 | ||
264 | (defun ert--parse-keys-and-body (keys-and-body) | |
265 | "Split KEYS-AND-BODY into keyword-and-value pairs and the remaining body. | |
266 | ||
267 | KEYS-AND-BODY should have the form of a property list, with the | |
268 | exception that only keywords are permitted as keys and that the | |
269 | tail -- the body -- is a list of forms that does not start with a | |
270 | keyword. | |
271 | ||
272 | Returns a two-element list containing the keys-and-values plist | |
273 | and the body." | |
274 | (let ((extracted-key-accu '()) | |
275 | (remaining keys-and-body)) | |
15c9d04e | 276 | (while (keywordp (car-safe remaining)) |
d221e780 CO |
277 | (let ((keyword (pop remaining))) |
278 | (unless (consp remaining) | |
279 | (error "Value expected after keyword %S in %S" | |
280 | keyword keys-and-body)) | |
281 | (when (assoc keyword extracted-key-accu) | |
282 | (warn "Keyword %S appears more than once in %S" keyword | |
283 | keys-and-body)) | |
284 | (push (cons keyword (pop remaining)) extracted-key-accu))) | |
285 | (setq extracted-key-accu (nreverse extracted-key-accu)) | |
15c9d04e SM |
286 | (list (cl-loop for (key . value) in extracted-key-accu |
287 | collect key | |
288 | collect value) | |
d221e780 CO |
289 | remaining))) |
290 | ||
291 | ;;;###autoload | |
15c9d04e | 292 | (cl-defmacro ert-deftest (name () &body docstring-keys-and-body) |
d221e780 CO |
293 | "Define NAME (a symbol) as a test. |
294 | ||
295 | BODY is evaluated as a `progn' when the test is run. It should | |
296 | signal a condition on failure or just return if the test passes. | |
297 | ||
298 | `should', `should-not' and `should-error' are useful for | |
299 | assertions in BODY. | |
300 | ||
301 | Use `ert' to run tests interactively. | |
302 | ||
303 | Tests that are expected to fail can be marked as such | |
304 | using :expected-result. See `ert-test-result-type-p' for a | |
305 | description of valid values for RESULT-TYPE. | |
306 | ||
307 | \(fn NAME () [DOCSTRING] [:expected-result RESULT-TYPE] \ | |
308 | \[:tags '(TAG...)] BODY...)" | |
309 | (declare (debug (&define :name test | |
310 | name sexp [&optional stringp] | |
311 | [&rest keywordp sexp] def-body)) | |
312 | (doc-string 3) | |
313 | (indent 2)) | |
314 | (let ((documentation nil) | |
315 | (documentation-supplied-p nil)) | |
15c9d04e | 316 | (when (stringp (car docstring-keys-and-body)) |
d221e780 CO |
317 | (setq documentation (pop docstring-keys-and-body) |
318 | documentation-supplied-p t)) | |
15c9d04e SM |
319 | (cl-destructuring-bind |
320 | ((&key (expected-result nil expected-result-supplied-p) | |
321 | (tags nil tags-supplied-p)) | |
322 | body) | |
d221e780 CO |
323 | (ert--parse-keys-and-body docstring-keys-and-body) |
324 | `(progn | |
325 | (ert-set-test ',name | |
326 | (make-ert-test | |
327 | :name ',name | |
328 | ,@(when documentation-supplied-p | |
329 | `(:documentation ,documentation)) | |
330 | ,@(when expected-result-supplied-p | |
331 | `(:expected-result-type ,expected-result)) | |
332 | ,@(when tags-supplied-p | |
333 | `(:tags ,tags)) | |
334 | :body (lambda () ,@body))) | |
335 | ;; This hack allows `symbol-file' to associate `ert-deftest' | |
336 | ;; forms with files, and therefore enables `find-function' to | |
337 | ;; work with tests. However, it leads to warnings in | |
338 | ;; `unload-feature', which doesn't know how to undefine tests | |
339 | ;; and has no mechanism for extension. | |
340 | (push '(ert-deftest . ,name) current-load-list) | |
341 | ',name)))) | |
342 | ||
343 | ;; We use these `put' forms in addition to the (declare (indent)) in | |
344 | ;; the defmacro form since the `declare' alone does not lead to | |
345 | ;; correct indentation before the .el/.elc file is loaded. | |
346 | ;; Autoloading these `put' forms solves this. | |
347 | ;;;###autoload | |
348 | (progn | |
349 | ;; TODO(ohler): Figure out what these mean and make sure they are correct. | |
350 | (put 'ert-deftest 'lisp-indent-function 2) | |
351 | (put 'ert-info 'lisp-indent-function 1)) | |
352 | ||
353 | (defvar ert--find-test-regexp | |
354 | (concat "^\\s-*(ert-deftest" | |
355 | find-function-space-re | |
356 | "%s\\(\\s-\\|$\\)") | |
357 | "The regexp the `find-function' mechanisms use for finding test definitions.") | |
358 | ||
359 | ||
360 | (put 'ert-test-failed 'error-conditions '(error ert-test-failed)) | |
361 | (put 'ert-test-failed 'error-message "Test failed") | |
362 | ||
363 | (defun ert-pass () | |
364 | "Terminate the current test and mark it passed. Does not return." | |
365 | (throw 'ert--pass nil)) | |
366 | ||
367 | (defun ert-fail (data) | |
368 | "Terminate the current test and mark it failed. Does not return. | |
369 | DATA is displayed to the user and should state the reason of the failure." | |
370 | (signal 'ert-test-failed (list data))) | |
371 | ||
372 | ||
373 | ;;; The `should' macros. | |
374 | ||
375 | (defvar ert--should-execution-observer nil) | |
376 | ||
377 | (defun ert--signal-should-execution (form-description) | |
378 | "Tell the current `should' form observer (if any) about FORM-DESCRIPTION." | |
379 | (when ert--should-execution-observer | |
380 | (funcall ert--should-execution-observer form-description))) | |
381 | ||
382 | (defun ert--special-operator-p (thing) | |
383 | "Return non-nil if THING is a symbol naming a special operator." | |
384 | (and (symbolp thing) | |
385 | (let ((definition (indirect-function thing t))) | |
386 | (and (subrp definition) | |
387 | (eql (cdr (subr-arity definition)) 'unevalled))))) | |
388 | ||
389 | (defun ert--expand-should-1 (whole form inner-expander) | |
390 | "Helper function for the `should' macro and its variants." | |
391 | (let ((form | |
bc715d67 SM |
392 | (macroexpand form (cond |
393 | ((boundp 'macroexpand-all-environment) | |
394 | macroexpand-all-environment) | |
395 | ((boundp 'cl-macro-environment) | |
396 | cl-macro-environment))))) | |
d221e780 CO |
397 | (cond |
398 | ((or (atom form) (ert--special-operator-p (car form))) | |
399 | (let ((value (ert--gensym "value-"))) | |
400 | `(let ((,value (ert--gensym "ert-form-evaluation-aborted-"))) | |
401 | ,(funcall inner-expander | |
402 | `(setq ,value ,form) | |
403 | `(list ',whole :form ',form :value ,value) | |
404 | value) | |
405 | ,value))) | |
406 | (t | |
407 | (let ((fn-name (car form)) | |
408 | (arg-forms (cdr form))) | |
15c9d04e SM |
409 | (cl-assert (or (symbolp fn-name) |
410 | (and (consp fn-name) | |
411 | (eql (car fn-name) 'lambda) | |
412 | (listp (cdr fn-name))))) | |
d221e780 CO |
413 | (let ((fn (ert--gensym "fn-")) |
414 | (args (ert--gensym "args-")) | |
415 | (value (ert--gensym "value-")) | |
416 | (default-value (ert--gensym "ert-form-evaluation-aborted-"))) | |
417 | `(let ((,fn (function ,fn-name)) | |
418 | (,args (list ,@arg-forms))) | |
419 | (let ((,value ',default-value)) | |
420 | ,(funcall inner-expander | |
421 | `(setq ,value (apply ,fn ,args)) | |
422 | `(nconc (list ',whole) | |
423 | (list :form `(,,fn ,@,args)) | |
424 | (unless (eql ,value ',default-value) | |
425 | (list :value ,value)) | |
426 | (let ((-explainer- | |
427 | (and (symbolp ',fn-name) | |
428 | (get ',fn-name 'ert-explainer)))) | |
429 | (when -explainer- | |
430 | (list :explanation | |
431 | (apply -explainer- ,args))))) | |
432 | value) | |
433 | ,value)))))))) | |
434 | ||
435 | (defun ert--expand-should (whole form inner-expander) | |
436 | "Helper function for the `should' macro and its variants. | |
437 | ||
438 | Analyzes FORM and returns an expression that has the same | |
439 | semantics under evaluation but records additional debugging | |
440 | information. | |
441 | ||
442 | INNER-EXPANDER should be a function and is called with two | |
443 | arguments: INNER-FORM and FORM-DESCRIPTION-FORM, where INNER-FORM | |
444 | is an expression equivalent to FORM, and FORM-DESCRIPTION-FORM is | |
445 | an expression that returns a description of FORM. INNER-EXPANDER | |
446 | should return code that calls INNER-FORM and performs the checks | |
8350f087 | 447 | and error signaling specific to the particular variant of |
d221e780 CO |
448 | `should'. The code that INNER-EXPANDER returns must not call |
449 | FORM-DESCRIPTION-FORM before it has called INNER-FORM." | |
15c9d04e SM |
450 | (ert--expand-should-1 |
451 | whole form | |
452 | (lambda (inner-form form-description-form value-var) | |
453 | (let ((form-description (ert--gensym "form-description-"))) | |
454 | `(let (,form-description) | |
455 | ,(funcall inner-expander | |
456 | `(unwind-protect | |
457 | ,inner-form | |
458 | (setq ,form-description ,form-description-form) | |
459 | (ert--signal-should-execution ,form-description)) | |
460 | `,form-description | |
461 | value-var)))))) | |
462 | ||
463 | (cl-defmacro should (form) | |
d221e780 CO |
464 | "Evaluate FORM. If it returns nil, abort the current test as failed. |
465 | ||
466 | Returns the value of FORM." | |
285c8184 | 467 | (declare (debug t)) |
d221e780 | 468 | (ert--expand-should `(should ,form) form |
15c9d04e | 469 | (lambda (inner-form form-description-form _value-var) |
d221e780 CO |
470 | `(unless ,inner-form |
471 | (ert-fail ,form-description-form))))) | |
472 | ||
15c9d04e | 473 | (cl-defmacro should-not (form) |
d221e780 CO |
474 | "Evaluate FORM. If it returns non-nil, abort the current test as failed. |
475 | ||
476 | Returns nil." | |
285c8184 | 477 | (declare (debug t)) |
d221e780 | 478 | (ert--expand-should `(should-not ,form) form |
15c9d04e | 479 | (lambda (inner-form form-description-form _value-var) |
d221e780 CO |
480 | `(unless (not ,inner-form) |
481 | (ert-fail ,form-description-form))))) | |
482 | ||
483 | (defun ert--should-error-handle-error (form-description-fn | |
484 | condition type exclude-subtypes) | |
485 | "Helper function for `should-error'. | |
486 | ||
487 | Determines whether CONDITION matches TYPE and EXCLUDE-SUBTYPES, | |
488 | and aborts the current test as failed if it doesn't." | |
8350f087 | 489 | (let ((signaled-conditions (get (car condition) 'error-conditions)) |
15c9d04e | 490 | (handled-conditions (cl-etypecase type |
d221e780 CO |
491 | (list type) |
492 | (symbol (list type))))) | |
15c9d04e | 493 | (cl-assert signaled-conditions) |
8350f087 | 494 | (unless (ert--intersection signaled-conditions handled-conditions) |
d221e780 CO |
495 | (ert-fail (append |
496 | (funcall form-description-fn) | |
497 | (list | |
498 | :condition condition | |
8350f087 | 499 | :fail-reason (concat "the error signaled did not" |
d221e780 CO |
500 | " have the expected type"))))) |
501 | (when exclude-subtypes | |
502 | (unless (member (car condition) handled-conditions) | |
503 | (ert-fail (append | |
504 | (funcall form-description-fn) | |
505 | (list | |
506 | :condition condition | |
8350f087 | 507 | :fail-reason (concat "the error signaled was a subtype" |
d221e780 CO |
508 | " of the expected type")))))))) |
509 | ||
510 | ;; FIXME: The expansion will evaluate the keyword args (if any) in | |
511 | ;; nonstandard order. | |
15c9d04e | 512 | (cl-defmacro should-error (form &rest keys &key type exclude-subtypes) |
d221e780 CO |
513 | "Evaluate FORM and check that it signals an error. |
514 | ||
8350f087 | 515 | The error signaled needs to match TYPE. TYPE should be a list |
d221e780 CO |
516 | of condition names. (It can also be a non-nil symbol, which is |
517 | equivalent to a singleton list containing that symbol.) If | |
518 | EXCLUDE-SUBTYPES is nil, the error matches TYPE if one of its | |
519 | condition names is an element of TYPE. If EXCLUDE-SUBTYPES is | |
520 | non-nil, the error matches TYPE if it is an element of TYPE. | |
521 | ||
522 | If the error matches, returns (ERROR-SYMBOL . DATA) from the | |
8350f087 | 523 | error. If not, or if no error was signaled, abort the test as |
d221e780 | 524 | failed." |
e3e7b504 | 525 | (declare (debug t)) |
d221e780 CO |
526 | (unless type (setq type ''error)) |
527 | (ert--expand-should | |
528 | `(should-error ,form ,@keys) | |
529 | form | |
530 | (lambda (inner-form form-description-form value-var) | |
531 | (let ((errorp (ert--gensym "errorp")) | |
532 | (form-description-fn (ert--gensym "form-description-fn-"))) | |
533 | `(let ((,errorp nil) | |
534 | (,form-description-fn (lambda () ,form-description-form))) | |
535 | (condition-case -condition- | |
536 | ,inner-form | |
537 | ;; We can't use ,type here because we want to evaluate it. | |
538 | (error | |
539 | (setq ,errorp t) | |
540 | (ert--should-error-handle-error ,form-description-fn | |
541 | -condition- | |
542 | ,type ,exclude-subtypes) | |
543 | (setq ,value-var -condition-))) | |
544 | (unless ,errorp | |
545 | (ert-fail (append | |
546 | (funcall ,form-description-fn) | |
547 | (list | |
548 | :fail-reason "did not signal an error"))))))))) | |
549 | ||
550 | ||
551 | ;;; Explanation of `should' failures. | |
552 | ||
553 | ;; TODO(ohler): Rework explanations so that they are displayed in a | |
554 | ;; similar way to `ert-info' messages; in particular, allow text | |
555 | ;; buttons in explanations that give more detail or open an ediff | |
556 | ;; buffer. Perhaps explanations should be reported through `ert-info' | |
557 | ;; rather than as part of the condition. | |
558 | ||
559 | (defun ert--proper-list-p (x) | |
560 | "Return non-nil if X is a proper list, nil otherwise." | |
15c9d04e | 561 | (cl-loop |
d221e780 CO |
562 | for firstp = t then nil |
563 | for fast = x then (cddr fast) | |
564 | for slow = x then (cdr slow) do | |
15c9d04e SM |
565 | (when (null fast) (cl-return t)) |
566 | (when (not (consp fast)) (cl-return nil)) | |
567 | (when (null (cdr fast)) (cl-return t)) | |
568 | (when (not (consp (cdr fast))) (cl-return nil)) | |
569 | (when (and (not firstp) (eq fast slow)) (cl-return nil)))) | |
d221e780 CO |
570 | |
571 | (defun ert--explain-format-atom (x) | |
de69c0a8 | 572 | "Format the atom X for `ert--explain-equal'." |
15c9d04e | 573 | (cl-typecase x |
84a06b50 GM |
574 | (character (list x (format "#x%x" x) (format "?%c" x))) |
575 | (fixnum (list x (format "#x%x" x))) | |
d221e780 CO |
576 | (t x))) |
577 | ||
de69c0a8 | 578 | (defun ert--explain-equal-rec (a b) |
c235b555 | 579 | "Return a programmer-readable explanation of why A and B are not `equal'. |
de69c0a8 | 580 | Returns nil if they are." |
d221e780 CO |
581 | (if (not (equal (type-of a) (type-of b))) |
582 | `(different-types ,a ,b) | |
15c9d04e | 583 | (cl-etypecase a |
d221e780 CO |
584 | (cons |
585 | (let ((a-proper-p (ert--proper-list-p a)) | |
586 | (b-proper-p (ert--proper-list-p b))) | |
587 | (if (not (eql (not a-proper-p) (not b-proper-p))) | |
588 | `(one-list-proper-one-improper ,a ,b) | |
589 | (if a-proper-p | |
590 | (if (not (equal (length a) (length b))) | |
591 | `(proper-lists-of-different-length ,(length a) ,(length b) | |
592 | ,a ,b | |
593 | first-mismatch-at | |
594 | ,(ert--mismatch a b)) | |
15c9d04e SM |
595 | (cl-loop for i from 0 |
596 | for ai in a | |
597 | for bi in b | |
598 | for xi = (ert--explain-equal-rec ai bi) | |
599 | do (when xi (cl-return `(list-elt ,i ,xi))) | |
600 | finally (cl-assert (equal a b) t))) | |
de69c0a8 | 601 | (let ((car-x (ert--explain-equal-rec (car a) (car b)))) |
d221e780 CO |
602 | (if car-x |
603 | `(car ,car-x) | |
de69c0a8 | 604 | (let ((cdr-x (ert--explain-equal-rec (cdr a) (cdr b)))) |
d221e780 CO |
605 | (if cdr-x |
606 | `(cdr ,cdr-x) | |
15c9d04e | 607 | (cl-assert (equal a b) t) |
d221e780 CO |
608 | nil)))))))) |
609 | (array (if (not (equal (length a) (length b))) | |
610 | `(arrays-of-different-length ,(length a) ,(length b) | |
611 | ,a ,b | |
612 | ,@(unless (char-table-p a) | |
613 | `(first-mismatch-at | |
614 | ,(ert--mismatch a b)))) | |
15c9d04e SM |
615 | (cl-loop for i from 0 |
616 | for ai across a | |
617 | for bi across b | |
618 | for xi = (ert--explain-equal-rec ai bi) | |
619 | do (when xi (cl-return `(array-elt ,i ,xi))) | |
620 | finally (cl-assert (equal a b) t)))) | |
d221e780 CO |
621 | (atom (if (not (equal a b)) |
622 | (if (and (symbolp a) (symbolp b) (string= a b)) | |
623 | `(different-symbols-with-the-same-name ,a ,b) | |
624 | `(different-atoms ,(ert--explain-format-atom a) | |
625 | ,(ert--explain-format-atom b))) | |
626 | nil))))) | |
de69c0a8 CO |
627 | |
628 | (defun ert--explain-equal (a b) | |
629 | "Explainer function for `equal'." | |
630 | ;; Do a quick comparison in C to avoid running our expensive | |
631 | ;; comparison when possible. | |
632 | (if (equal a b) | |
633 | nil | |
634 | (ert--explain-equal-rec a b))) | |
635 | (put 'equal 'ert-explainer 'ert--explain-equal) | |
d221e780 CO |
636 | |
637 | (defun ert--significant-plist-keys (plist) | |
638 | "Return the keys of PLIST that have non-null values, in order." | |
15c9d04e SM |
639 | (cl-assert (zerop (mod (length plist) 2)) t) |
640 | (cl-loop for (key value . rest) on plist by #'cddr | |
641 | unless (or (null value) (memq key accu)) collect key into accu | |
642 | finally (cl-return accu))) | |
d221e780 CO |
643 | |
644 | (defun ert--plist-difference-explanation (a b) | |
645 | "Return a programmer-readable explanation of why A and B are different plists. | |
646 | ||
647 | Returns nil if they are equivalent, i.e., have the same value for | |
648 | each key, where absent values are treated as nil. The order of | |
649 | key/value pairs in each list does not matter." | |
15c9d04e SM |
650 | (cl-assert (zerop (mod (length a) 2)) t) |
651 | (cl-assert (zerop (mod (length b) 2)) t) | |
d221e780 CO |
652 | ;; Normalizing the plists would be another way to do this but it |
653 | ;; requires a total ordering on all lisp objects (since any object | |
654 | ;; is valid as a text property key). Perhaps defining such an | |
655 | ;; ordering is useful in other contexts, too, but it's a lot of | |
656 | ;; work, so let's punt on it for now. | |
657 | (let* ((keys-a (ert--significant-plist-keys a)) | |
658 | (keys-b (ert--significant-plist-keys b)) | |
659 | (keys-in-a-not-in-b (ert--set-difference-eq keys-a keys-b)) | |
660 | (keys-in-b-not-in-a (ert--set-difference-eq keys-b keys-a))) | |
15c9d04e SM |
661 | (cl-flet ((explain-with-key (key) |
662 | (let ((value-a (plist-get a key)) | |
663 | (value-b (plist-get b key))) | |
664 | (cl-assert (not (equal value-a value-b)) t) | |
665 | `(different-properties-for-key | |
666 | ,key ,(ert--explain-equal-including-properties value-a | |
667 | value-b))))) | |
d221e780 | 668 | (cond (keys-in-a-not-in-b |
15c9d04e | 669 | (explain-with-key (car keys-in-a-not-in-b))) |
d221e780 | 670 | (keys-in-b-not-in-a |
15c9d04e | 671 | (explain-with-key (car keys-in-b-not-in-a))) |
d221e780 | 672 | (t |
15c9d04e SM |
673 | (cl-loop for key in keys-a |
674 | when (not (equal (plist-get a key) (plist-get b key))) | |
675 | return (explain-with-key key))))))) | |
d221e780 CO |
676 | |
677 | (defun ert--abbreviate-string (s len suffixp) | |
678 | "Shorten string S to at most LEN chars. | |
679 | ||
680 | If SUFFIXP is non-nil, returns a suffix of S, otherwise a prefix." | |
681 | (let ((n (length s))) | |
682 | (cond ((< n len) | |
683 | s) | |
684 | (suffixp | |
685 | (substring s (- n len))) | |
686 | (t | |
687 | (substring s 0 len))))) | |
688 | ||
de69c0a8 CO |
689 | ;; TODO(ohler): Once bug 6581 is fixed, rename this to |
690 | ;; `ert--explain-equal-including-properties-rec' and add a fast-path | |
691 | ;; wrapper like `ert--explain-equal'. | |
692 | (defun ert--explain-equal-including-properties (a b) | |
d221e780 CO |
693 | "Explainer function for `ert-equal-including-properties'. |
694 | ||
695 | Returns a programmer-readable explanation of why A and B are not | |
696 | `ert-equal-including-properties', or nil if they are." | |
697 | (if (not (equal a b)) | |
de69c0a8 | 698 | (ert--explain-equal a b) |
15c9d04e SM |
699 | (cl-assert (stringp a) t) |
700 | (cl-assert (stringp b) t) | |
701 | (cl-assert (eql (length a) (length b)) t) | |
702 | (cl-loop for i from 0 to (length a) | |
703 | for props-a = (text-properties-at i a) | |
704 | for props-b = (text-properties-at i b) | |
705 | for difference = (ert--plist-difference-explanation | |
706 | props-a props-b) | |
707 | do (when difference | |
708 | (cl-return `(char ,i ,(substring-no-properties a i (1+ i)) | |
709 | ,difference | |
710 | context-before | |
711 | ,(ert--abbreviate-string | |
712 | (substring-no-properties a 0 i) | |
713 | 10 t) | |
714 | context-after | |
715 | ,(ert--abbreviate-string | |
716 | (substring-no-properties a (1+ i)) | |
717 | 10 nil)))) | |
718 | ;; TODO(ohler): Get `equal-including-properties' fixed in | |
719 | ;; Emacs, delete `ert-equal-including-properties', and | |
720 | ;; re-enable this assertion. | |
721 | ;;finally (cl-assert (equal-including-properties a b) t) | |
722 | ))) | |
d221e780 CO |
723 | (put 'ert-equal-including-properties |
724 | 'ert-explainer | |
de69c0a8 | 725 | 'ert--explain-equal-including-properties) |
d221e780 CO |
726 | |
727 | ||
728 | ;;; Implementation of `ert-info'. | |
729 | ||
730 | ;; TODO(ohler): The name `info' clashes with | |
731 | ;; `ert--test-execution-info'. One or both should be renamed. | |
732 | (defvar ert--infos '() | |
733 | "The stack of `ert-info' infos that currently apply. | |
734 | ||
735 | Bound dynamically. This is a list of (PREFIX . MESSAGE) pairs.") | |
736 | ||
15c9d04e SM |
737 | (cl-defmacro ert-info ((message-form &key ((:prefix prefix-form) "Info: ")) |
738 | &body body) | |
d221e780 CO |
739 | "Evaluate MESSAGE-FORM and BODY, and report the message if BODY fails. |
740 | ||
741 | To be used within ERT tests. MESSAGE-FORM should evaluate to a | |
742 | string that will be displayed together with the test result if | |
743 | the test fails. PREFIX-FORM should evaluate to a string as well | |
744 | and is displayed in front of the value of MESSAGE-FORM." | |
745 | (declare (debug ((form &rest [sexp form]) body)) | |
746 | (indent 1)) | |
747 | `(let ((ert--infos (cons (cons ,prefix-form ,message-form) ert--infos))) | |
748 | ,@body)) | |
749 | ||
750 | ||
751 | ||
752 | ;;; Facilities for running a single test. | |
753 | ||
754 | (defvar ert-debug-on-error nil | |
755 | "Non-nil means enter debugger when a test fails or terminates with an error.") | |
756 | ||
757 | ;; The data structures that represent the result of running a test. | |
15c9d04e | 758 | (cl-defstruct ert-test-result |
d221e780 CO |
759 | (messages nil) |
760 | (should-forms nil) | |
761 | ) | |
15c9d04e SM |
762 | (cl-defstruct (ert-test-passed (:include ert-test-result))) |
763 | (cl-defstruct (ert-test-result-with-condition (:include ert-test-result)) | |
764 | (condition (cl-assert nil)) | |
765 | (backtrace (cl-assert nil)) | |
766 | (infos (cl-assert nil))) | |
767 | (cl-defstruct (ert-test-quit (:include ert-test-result-with-condition))) | |
768 | (cl-defstruct (ert-test-failed (:include ert-test-result-with-condition))) | |
769 | (cl-defstruct (ert-test-aborted-with-non-local-exit | |
770 | (:include ert-test-result))) | |
d221e780 CO |
771 | |
772 | ||
773 | (defun ert--record-backtrace () | |
774 | "Record the current backtrace (as a list) and return it." | |
775 | ;; Since the backtrace is stored in the result object, result | |
776 | ;; objects must only be printed with appropriate limits | |
777 | ;; (`print-level' and `print-length') in place. For interactive | |
778 | ;; use, the cost of ensuring this possibly outweighs the advantage | |
779 | ;; of storing the backtrace for | |
780 | ;; `ert-results-pop-to-backtrace-for-test-at-point' given that we | |
781 | ;; already have `ert-results-rerun-test-debugging-errors-at-point'. | |
782 | ;; For batch use, however, printing the backtrace may be useful. | |
15c9d04e | 783 | (cl-loop |
d221e780 CO |
784 | ;; 6 is the number of frames our own debugger adds (when |
785 | ;; compiled; more when interpreted). FIXME: Need to describe a | |
786 | ;; procedure for determining this constant. | |
787 | for i from 6 | |
788 | for frame = (backtrace-frame i) | |
789 | while frame | |
790 | collect frame)) | |
791 | ||
792 | (defun ert--print-backtrace (backtrace) | |
793 | "Format the backtrace BACKTRACE to the current buffer." | |
794 | ;; This is essentially a reimplementation of Fbacktrace | |
795 | ;; (src/eval.c), but for a saved backtrace, not the current one. | |
796 | (let ((print-escape-newlines t) | |
797 | (print-level 8) | |
798 | (print-length 50)) | |
799 | (dolist (frame backtrace) | |
15c9d04e | 800 | (cl-ecase (car frame) |
d221e780 CO |
801 | ((nil) |
802 | ;; Special operator. | |
15c9d04e | 803 | (cl-destructuring-bind (special-operator &rest arg-forms) |
d221e780 CO |
804 | (cdr frame) |
805 | (insert | |
15c9d04e | 806 | (format " %S\n" (cons special-operator arg-forms))))) |
d221e780 CO |
807 | ((t) |
808 | ;; Function call. | |
15c9d04e | 809 | (cl-destructuring-bind (fn &rest args) (cdr frame) |
d221e780 | 810 | (insert (format " %S(" fn)) |
15c9d04e SM |
811 | (cl-loop for firstp = t then nil |
812 | for arg in args do | |
813 | (unless firstp | |
814 | (insert " ")) | |
815 | (insert (format "%S" arg))) | |
d221e780 CO |
816 | (insert ")\n"))))))) |
817 | ||
818 | ;; A container for the state of the execution of a single test and | |
819 | ;; environment data needed during its execution. | |
15c9d04e SM |
820 | (cl-defstruct ert--test-execution-info |
821 | (test (cl-assert nil)) | |
822 | (result (cl-assert nil)) | |
d221e780 CO |
823 | ;; A thunk that may be called when RESULT has been set to its final |
824 | ;; value and test execution should be terminated. Should not | |
825 | ;; return. | |
15c9d04e | 826 | (exit-continuation (cl-assert nil)) |
d221e780 CO |
827 | ;; The binding of `debugger' outside of the execution of the test. |
828 | next-debugger | |
829 | ;; The binding of `ert-debug-on-error' that is in effect for the | |
830 | ;; execution of the current test. We store it to avoid being | |
831 | ;; affected by any new bindings the test itself may establish. (I | |
832 | ;; don't remember whether this feature is important.) | |
833 | ert-debug-on-error) | |
834 | ||
15c9d04e | 835 | (defun ert--run-test-debugger (info args) |
d221e780 CO |
836 | "During a test run, `debugger' is bound to a closure that calls this function. |
837 | ||
838 | This function records failures and errors and either terminates | |
839 | the test silently or calls the interactive debugger, as | |
840 | appropriate. | |
841 | ||
842 | INFO is the ert--test-execution-info corresponding to this test | |
15c9d04e SM |
843 | run. ARGS are the arguments to `debugger'." |
844 | (cl-destructuring-bind (first-debugger-arg &rest more-debugger-args) | |
845 | args | |
846 | (cl-ecase first-debugger-arg | |
d221e780 | 847 | ((lambda debug t exit nil) |
15c9d04e | 848 | (apply (ert--test-execution-info-next-debugger info) args)) |
d221e780 | 849 | (error |
15c9d04e SM |
850 | (let* ((condition (car more-debugger-args)) |
851 | (type (cl-case (car condition) | |
d221e780 CO |
852 | ((quit) 'quit) |
853 | (otherwise 'failed))) | |
854 | (backtrace (ert--record-backtrace)) | |
855 | (infos (reverse ert--infos))) | |
856 | (setf (ert--test-execution-info-result info) | |
15c9d04e | 857 | (cl-ecase type |
d221e780 CO |
858 | (quit |
859 | (make-ert-test-quit :condition condition | |
860 | :backtrace backtrace | |
861 | :infos infos)) | |
862 | (failed | |
863 | (make-ert-test-failed :condition condition | |
864 | :backtrace backtrace | |
865 | :infos infos)))) | |
44e97401 | 866 | ;; Work around Emacs's heuristic (in eval.c) for detecting |
d221e780 | 867 | ;; errors in the debugger. |
15c9d04e | 868 | (cl-incf num-nonmacro-input-events) |
d221e780 CO |
869 | ;; FIXME: We should probably implement more fine-grained |
870 | ;; control a la non-t `debug-on-error' here. | |
871 | (cond | |
872 | ((ert--test-execution-info-ert-debug-on-error info) | |
15c9d04e | 873 | (apply (ert--test-execution-info-next-debugger info) args)) |
d221e780 CO |
874 | (t)) |
875 | (funcall (ert--test-execution-info-exit-continuation info))))))) | |
876 | ||
15c9d04e SM |
877 | (defun ert--run-test-internal (test-execution-info) |
878 | "Low-level function to run a test according to TEST-EXECUTION-INFO. | |
d221e780 CO |
879 | |
880 | This mainly sets up debugger-related bindings." | |
15c9d04e SM |
881 | (setf (ert--test-execution-info-next-debugger test-execution-info) debugger |
882 | (ert--test-execution-info-ert-debug-on-error test-execution-info) | |
883 | ert-debug-on-error) | |
884 | (catch 'ert--pass | |
885 | ;; For now, each test gets its own temp buffer and its own | |
886 | ;; window excursion, just to be safe. If this turns out to be | |
887 | ;; too expensive, we can remove it. | |
888 | (with-temp-buffer | |
889 | (save-window-excursion | |
890 | (let ((debugger (lambda (&rest args) | |
891 | (ert--run-test-debugger test-execution-info | |
892 | args))) | |
893 | (debug-on-error t) | |
894 | (debug-on-quit t) | |
895 | ;; FIXME: Do we need to store the old binding of this | |
896 | ;; and consider it in `ert--run-test-debugger'? | |
897 | (debug-ignored-errors nil) | |
898 | (ert--infos '())) | |
899 | (funcall (ert-test-body (ert--test-execution-info-test | |
900 | test-execution-info)))))) | |
901 | (ert-pass)) | |
902 | (setf (ert--test-execution-info-result test-execution-info) | |
903 | (make-ert-test-passed)) | |
d221e780 CO |
904 | nil) |
905 | ||
906 | (defun ert--force-message-log-buffer-truncation () | |
907 | "Immediately truncate *Messages* buffer according to `message-log-max'. | |
908 | ||
909 | This can be useful after reducing the value of `message-log-max'." | |
910 | (with-current-buffer (get-buffer-create "*Messages*") | |
911 | ;; This is a reimplementation of this part of message_dolog() in xdisp.c: | |
912 | ;; if (NATNUMP (Vmessage_log_max)) | |
913 | ;; { | |
914 | ;; scan_newline (Z, Z_BYTE, BEG, BEG_BYTE, | |
915 | ;; -XFASTINT (Vmessage_log_max) - 1, 0); | |
916 | ;; del_range_both (BEG, BEG_BYTE, PT, PT_BYTE, 0); | |
917 | ;; } | |
918 | (when (and (integerp message-log-max) (>= message-log-max 0)) | |
919 | (let ((begin (point-min)) | |
920 | (end (save-excursion | |
921 | (goto-char (point-max)) | |
922 | (forward-line (- message-log-max)) | |
923 | (point)))) | |
924 | (delete-region begin end))))) | |
925 | ||
926 | (defvar ert--running-tests nil | |
927 | "List of tests that are currently in execution. | |
928 | ||
929 | This list is empty while no test is running, has one element | |
930 | while a test is running, two elements while a test run from | |
931 | inside a test is running, etc. The list is in order of nesting, | |
932 | innermost test first. | |
933 | ||
934 | The elements are of type `ert-test'.") | |
935 | ||
936 | (defun ert-run-test (ert-test) | |
937 | "Run ERT-TEST. | |
938 | ||
939 | Returns the result and stores it in ERT-TEST's `most-recent-result' slot." | |
940 | (setf (ert-test-most-recent-result ert-test) nil) | |
15c9d04e SM |
941 | (cl-block error |
942 | (let ((begin-marker | |
943 | (with-current-buffer (get-buffer-create "*Messages*") | |
30818a23 | 944 | (point-max-marker)))) |
d221e780 | 945 | (unwind-protect |
15c9d04e SM |
946 | (let ((info (make-ert--test-execution-info |
947 | :test ert-test | |
948 | :result | |
949 | (make-ert-test-aborted-with-non-local-exit) | |
950 | :exit-continuation (lambda () | |
951 | (cl-return-from error nil)))) | |
952 | (should-form-accu (list))) | |
d221e780 CO |
953 | (unwind-protect |
954 | (let ((ert--should-execution-observer | |
955 | (lambda (form-description) | |
956 | (push form-description should-form-accu))) | |
957 | (message-log-max t) | |
958 | (ert--running-tests (cons ert-test ert--running-tests))) | |
959 | (ert--run-test-internal info)) | |
960 | (let ((result (ert--test-execution-info-result info))) | |
961 | (setf (ert-test-result-messages result) | |
962 | (with-current-buffer (get-buffer-create "*Messages*") | |
963 | (buffer-substring begin-marker (point-max)))) | |
964 | (ert--force-message-log-buffer-truncation) | |
965 | (setq should-form-accu (nreverse should-form-accu)) | |
966 | (setf (ert-test-result-should-forms result) | |
967 | should-form-accu) | |
968 | (setf (ert-test-most-recent-result ert-test) result)))) | |
969 | (set-marker begin-marker nil)))) | |
970 | (ert-test-most-recent-result ert-test)) | |
971 | ||
972 | (defun ert-running-test () | |
973 | "Return the top-level test currently executing." | |
974 | (car (last ert--running-tests))) | |
975 | ||
976 | ||
977 | ;;; Test selectors. | |
978 | ||
979 | (defun ert-test-result-type-p (result result-type) | |
980 | "Return non-nil if RESULT matches type RESULT-TYPE. | |
981 | ||
982 | Valid result types: | |
983 | ||
984 | nil -- Never matches. | |
985 | t -- Always matches. | |
986 | :failed, :passed -- Matches corresponding results. | |
987 | \(and TYPES...\) -- Matches if all TYPES match. | |
988 | \(or TYPES...\) -- Matches if some TYPES match. | |
989 | \(not TYPE\) -- Matches if TYPE does not match. | |
990 | \(satisfies PREDICATE\) -- Matches if PREDICATE returns true when called with | |
991 | RESULT." | |
992 | ;; It would be easy to add `member' and `eql' types etc., but I | |
993 | ;; haven't bothered yet. | |
15c9d04e | 994 | (cl-etypecase result-type |
d221e780 CO |
995 | ((member nil) nil) |
996 | ((member t) t) | |
997 | ((member :failed) (ert-test-failed-p result)) | |
998 | ((member :passed) (ert-test-passed-p result)) | |
999 | (cons | |
15c9d04e SM |
1000 | (cl-destructuring-bind (operator &rest operands) result-type |
1001 | (cl-ecase operator | |
d221e780 | 1002 | (and |
15c9d04e | 1003 | (cl-case (length operands) |
d221e780 CO |
1004 | (0 t) |
1005 | (t | |
15c9d04e SM |
1006 | (and (ert-test-result-type-p result (car operands)) |
1007 | (ert-test-result-type-p result `(and ,@(cdr operands))))))) | |
d221e780 | 1008 | (or |
15c9d04e | 1009 | (cl-case (length operands) |
d221e780 CO |
1010 | (0 nil) |
1011 | (t | |
15c9d04e SM |
1012 | (or (ert-test-result-type-p result (car operands)) |
1013 | (ert-test-result-type-p result `(or ,@(cdr operands))))))) | |
d221e780 | 1014 | (not |
15c9d04e SM |
1015 | (cl-assert (eql (length operands) 1)) |
1016 | (not (ert-test-result-type-p result (car operands)))) | |
d221e780 | 1017 | (satisfies |
15c9d04e SM |
1018 | (cl-assert (eql (length operands) 1)) |
1019 | (funcall (car operands) result))))))) | |
d221e780 CO |
1020 | |
1021 | (defun ert-test-result-expected-p (test result) | |
1022 | "Return non-nil if TEST's expected result type matches RESULT." | |
1023 | (ert-test-result-type-p result (ert-test-expected-result-type test))) | |
1024 | ||
1025 | (defun ert-select-tests (selector universe) | |
c235b555 | 1026 | "Return a list of tests that match SELECTOR. |
d221e780 | 1027 | |
c235b555 GM |
1028 | UNIVERSE specifies the set of tests to select from; it should be a list |
1029 | of tests, or t, which refers to all tests named by symbols in `obarray'. | |
d221e780 | 1030 | |
c235b555 | 1031 | Valid SELECTORs: |
d221e780 | 1032 | |
c235b555 GM |
1033 | nil -- Selects the empty set. |
1034 | t -- Selects UNIVERSE. | |
d221e780 | 1035 | :new -- Selects all tests that have not been run yet. |
c235b555 | 1036 | :failed, :passed -- Select tests according to their most recent result. |
d221e780 | 1037 | :expected, :unexpected -- Select tests according to their most recent result. |
c235b555 GM |
1038 | a string -- A regular expression selecting all tests with matching names. |
1039 | a test -- (i.e., an object of the ert-test data-type) Selects that test. | |
d221e780 | 1040 | a symbol -- Selects the test that the symbol names, errors if none. |
c235b555 GM |
1041 | \(member TESTS...) -- Selects the elements of TESTS, a list of tests |
1042 | or symbols naming tests. | |
d221e780 | 1043 | \(eql TEST\) -- Selects TEST, a test or a symbol naming a test. |
c235b555 GM |
1044 | \(and SELECTORS...) -- Selects the tests that match all SELECTORS. |
1045 | \(or SELECTORS...) -- Selects the tests that match any of the SELECTORS. | |
1046 | \(not SELECTOR) -- Selects all tests that do not match SELECTOR. | |
d221e780 | 1047 | \(tag TAG) -- Selects all tests that have TAG on their tags list. |
c235b555 GM |
1048 | A tag is an arbitrary label you can apply when you define a test. |
1049 | \(satisfies PREDICATE) -- Selects all tests that satisfy PREDICATE. | |
1050 | PREDICATE is a function that takes an ert-test object as argument, | |
1051 | and returns non-nil if it is selected. | |
d221e780 CO |
1052 | |
1053 | Only selectors that require a superset of tests, such | |
1054 | as (satisfies ...), strings, :new, etc. make use of UNIVERSE. | |
c235b555 | 1055 | Selectors that do not, such as (member ...), just return the |
d221e780 CO |
1056 | set implied by them without checking whether it is really |
1057 | contained in UNIVERSE." | |
1058 | ;; This code needs to match the etypecase in | |
1059 | ;; `ert-insert-human-readable-selector'. | |
15c9d04e | 1060 | (cl-etypecase selector |
d221e780 | 1061 | ((member nil) nil) |
15c9d04e | 1062 | ((member t) (cl-etypecase universe |
d221e780 CO |
1063 | (list universe) |
1064 | ((member t) (ert-select-tests "" universe)))) | |
1065 | ((member :new) (ert-select-tests | |
1066 | `(satisfies ,(lambda (test) | |
1067 | (null (ert-test-most-recent-result test)))) | |
1068 | universe)) | |
1069 | ((member :failed) (ert-select-tests | |
1070 | `(satisfies ,(lambda (test) | |
1071 | (ert-test-result-type-p | |
1072 | (ert-test-most-recent-result test) | |
1073 | ':failed))) | |
1074 | universe)) | |
1075 | ((member :passed) (ert-select-tests | |
1076 | `(satisfies ,(lambda (test) | |
1077 | (ert-test-result-type-p | |
1078 | (ert-test-most-recent-result test) | |
1079 | ':passed))) | |
1080 | universe)) | |
1081 | ((member :expected) (ert-select-tests | |
1082 | `(satisfies | |
1083 | ,(lambda (test) | |
1084 | (ert-test-result-expected-p | |
1085 | test | |
1086 | (ert-test-most-recent-result test)))) | |
1087 | universe)) | |
1088 | ((member :unexpected) (ert-select-tests `(not :expected) universe)) | |
1089 | (string | |
15c9d04e | 1090 | (cl-etypecase universe |
d221e780 CO |
1091 | ((member t) (mapcar #'ert-get-test |
1092 | (apropos-internal selector #'ert-test-boundp))) | |
1093 | (list (ert--remove-if-not (lambda (test) | |
1094 | (and (ert-test-name test) | |
1095 | (string-match selector | |
1096 | (ert-test-name test)))) | |
1097 | universe)))) | |
1098 | (ert-test (list selector)) | |
1099 | (symbol | |
15c9d04e | 1100 | (cl-assert (ert-test-boundp selector)) |
d221e780 CO |
1101 | (list (ert-get-test selector))) |
1102 | (cons | |
15c9d04e SM |
1103 | (cl-destructuring-bind (operator &rest operands) selector |
1104 | (cl-ecase operator | |
d221e780 CO |
1105 | (member |
1106 | (mapcar (lambda (purported-test) | |
15c9d04e SM |
1107 | (cl-etypecase purported-test |
1108 | (symbol (cl-assert (ert-test-boundp purported-test)) | |
d221e780 CO |
1109 | (ert-get-test purported-test)) |
1110 | (ert-test purported-test))) | |
1111 | operands)) | |
1112 | (eql | |
15c9d04e | 1113 | (cl-assert (eql (length operands) 1)) |
d221e780 CO |
1114 | (ert-select-tests `(member ,@operands) universe)) |
1115 | (and | |
1116 | ;; Do these definitions of AND, NOT and OR satisfy de | |
1117 | ;; Morgan's laws? Should they? | |
15c9d04e | 1118 | (cl-case (length operands) |
d221e780 | 1119 | (0 (ert-select-tests 't universe)) |
15c9d04e SM |
1120 | (t (ert-select-tests `(and ,@(cdr operands)) |
1121 | (ert-select-tests (car operands) | |
d221e780 CO |
1122 | universe))))) |
1123 | (not | |
15c9d04e | 1124 | (cl-assert (eql (length operands) 1)) |
d221e780 CO |
1125 | (let ((all-tests (ert-select-tests 't universe))) |
1126 | (ert--set-difference all-tests | |
15c9d04e | 1127 | (ert-select-tests (car operands) |
d221e780 CO |
1128 | all-tests)))) |
1129 | (or | |
15c9d04e | 1130 | (cl-case (length operands) |
d221e780 | 1131 | (0 (ert-select-tests 'nil universe)) |
15c9d04e SM |
1132 | (t (ert--union (ert-select-tests (car operands) universe) |
1133 | (ert-select-tests `(or ,@(cdr operands)) | |
d221e780 CO |
1134 | universe))))) |
1135 | (tag | |
15c9d04e SM |
1136 | (cl-assert (eql (length operands) 1)) |
1137 | (let ((tag (car operands))) | |
d221e780 CO |
1138 | (ert-select-tests `(satisfies |
1139 | ,(lambda (test) | |
1140 | (member tag (ert-test-tags test)))) | |
1141 | universe))) | |
1142 | (satisfies | |
15c9d04e SM |
1143 | (cl-assert (eql (length operands) 1)) |
1144 | (ert--remove-if-not (car operands) | |
d221e780 CO |
1145 | (ert-select-tests 't universe)))))))) |
1146 | ||
1147 | (defun ert--insert-human-readable-selector (selector) | |
1148 | "Insert a human-readable presentation of SELECTOR into the current buffer." | |
1149 | ;; This is needed to avoid printing the (huge) contents of the | |
1150 | ;; `backtrace' slot of the result objects in the | |
1151 | ;; `most-recent-result' slots of test case objects in (eql ...) or | |
1152 | ;; (member ...) selectors. | |
15c9d04e SM |
1153 | (cl-labels ((rec (selector) |
1154 | ;; This code needs to match the etypecase in | |
1155 | ;; `ert-select-tests'. | |
1156 | (cl-etypecase selector | |
1157 | ((or (member nil t | |
1158 | :new :failed :passed | |
1159 | :expected :unexpected) | |
1160 | string | |
1161 | symbol) | |
1162 | selector) | |
1163 | (ert-test | |
1164 | (if (ert-test-name selector) | |
1165 | (make-symbol (format "<%S>" (ert-test-name selector))) | |
1166 | (make-symbol "<unnamed test>"))) | |
1167 | (cons | |
1168 | (cl-destructuring-bind (operator &rest operands) selector | |
1169 | (cl-ecase operator | |
1170 | ((member eql and not or) | |
1171 | `(,operator ,@(mapcar #'rec operands))) | |
1172 | ((member tag satisfies) | |
1173 | selector))))))) | |
d221e780 CO |
1174 | (insert (format "%S" (rec selector))))) |
1175 | ||
1176 | ||
1177 | ;;; Facilities for running a whole set of tests. | |
1178 | ||
1179 | ;; The data structure that contains the set of tests being executed | |
1180 | ;; during one particular test run, their results, the state of the | |
1181 | ;; execution, and some statistics. | |
1182 | ;; | |
1183 | ;; The data about results and expected results of tests may seem | |
1184 | ;; redundant here, since the test objects also carry such information. | |
1185 | ;; However, the information in the test objects may be more recent, it | |
1186 | ;; may correspond to a different test run. We need the information | |
1187 | ;; that corresponds to this run in order to be able to update the | |
1188 | ;; statistics correctly when a test is re-run interactively and has a | |
1189 | ;; different result than before. | |
15c9d04e SM |
1190 | (cl-defstruct ert--stats |
1191 | (selector (cl-assert nil)) | |
d221e780 | 1192 | ;; The tests, in order. |
15c9d04e | 1193 | (tests (cl-assert nil) :type vector) |
d221e780 CO |
1194 | ;; A map of test names (or the test objects themselves for unnamed |
1195 | ;; tests) to indices into the `tests' vector. | |
15c9d04e | 1196 | (test-map (cl-assert nil) :type hash-table) |
d221e780 | 1197 | ;; The results of the tests during this run, in order. |
15c9d04e | 1198 | (test-results (cl-assert nil) :type vector) |
d221e780 CO |
1199 | ;; The start times of the tests, in order, as reported by |
1200 | ;; `current-time'. | |
15c9d04e | 1201 | (test-start-times (cl-assert nil) :type vector) |
d221e780 CO |
1202 | ;; The end times of the tests, in order, as reported by |
1203 | ;; `current-time'. | |
15c9d04e | 1204 | (test-end-times (cl-assert nil) :type vector) |
d221e780 CO |
1205 | (passed-expected 0) |
1206 | (passed-unexpected 0) | |
1207 | (failed-expected 0) | |
1208 | (failed-unexpected 0) | |
1209 | (start-time nil) | |
1210 | (end-time nil) | |
1211 | (aborted-p nil) | |
1212 | (current-test nil) | |
1213 | ;; The time at or after which the next redisplay should occur, as a | |
1214 | ;; float. | |
1215 | (next-redisplay 0.0)) | |
1216 | ||
1217 | (defun ert-stats-completed-expected (stats) | |
1218 | "Return the number of tests in STATS that had expected results." | |
1219 | (+ (ert--stats-passed-expected stats) | |
1220 | (ert--stats-failed-expected stats))) | |
1221 | ||
1222 | (defun ert-stats-completed-unexpected (stats) | |
1223 | "Return the number of tests in STATS that had unexpected results." | |
1224 | (+ (ert--stats-passed-unexpected stats) | |
1225 | (ert--stats-failed-unexpected stats))) | |
1226 | ||
1227 | (defun ert-stats-completed (stats) | |
1228 | "Number of tests in STATS that have run so far." | |
1229 | (+ (ert-stats-completed-expected stats) | |
1230 | (ert-stats-completed-unexpected stats))) | |
1231 | ||
1232 | (defun ert-stats-total (stats) | |
1233 | "Number of tests in STATS, regardless of whether they have run yet." | |
1234 | (length (ert--stats-tests stats))) | |
1235 | ||
1236 | ;; The stats object of the current run, dynamically bound. This is | |
1237 | ;; used for the mode line progress indicator. | |
1238 | (defvar ert--current-run-stats nil) | |
1239 | ||
1240 | (defun ert--stats-test-key (test) | |
1241 | "Return the key used for TEST in the test map of ert--stats objects. | |
1242 | ||
1243 | Returns the name of TEST if it has one, or TEST itself otherwise." | |
1244 | (or (ert-test-name test) test)) | |
1245 | ||
1246 | (defun ert--stats-set-test-and-result (stats pos test result) | |
1247 | "Change STATS by replacing the test at position POS with TEST and RESULT. | |
1248 | ||
1249 | Also changes the counters in STATS to match." | |
1250 | (let* ((tests (ert--stats-tests stats)) | |
1251 | (results (ert--stats-test-results stats)) | |
1252 | (old-test (aref tests pos)) | |
1253 | (map (ert--stats-test-map stats))) | |
15c9d04e SM |
1254 | (cl-flet ((update (d) |
1255 | (if (ert-test-result-expected-p (aref tests pos) | |
1256 | (aref results pos)) | |
1257 | (cl-etypecase (aref results pos) | |
1258 | (ert-test-passed | |
1259 | (cl-incf (ert--stats-passed-expected stats) d)) | |
1260 | (ert-test-failed | |
1261 | (cl-incf (ert--stats-failed-expected stats) d)) | |
1262 | (null) | |
1263 | (ert-test-aborted-with-non-local-exit) | |
1264 | (ert-test-quit)) | |
1265 | (cl-etypecase (aref results pos) | |
1266 | (ert-test-passed | |
1267 | (cl-incf (ert--stats-passed-unexpected stats) d)) | |
1268 | (ert-test-failed | |
1269 | (cl-incf (ert--stats-failed-unexpected stats) d)) | |
1270 | (null) | |
1271 | (ert-test-aborted-with-non-local-exit) | |
1272 | (ert-test-quit))))) | |
d221e780 CO |
1273 | ;; Adjust counters to remove the result that is currently in stats. |
1274 | (update -1) | |
1275 | ;; Put new test and result into stats. | |
1276 | (setf (aref tests pos) test | |
1277 | (aref results pos) result) | |
1278 | (remhash (ert--stats-test-key old-test) map) | |
1279 | (setf (gethash (ert--stats-test-key test) map) pos) | |
1280 | ;; Adjust counters to match new result. | |
1281 | (update +1) | |
1282 | nil))) | |
1283 | ||
1284 | (defun ert--make-stats (tests selector) | |
1285 | "Create a new `ert--stats' object for running TESTS. | |
1286 | ||
1287 | SELECTOR is the selector that was used to select TESTS." | |
1288 | (setq tests (ert--coerce-to-vector tests)) | |
1289 | (let ((map (make-hash-table :size (length tests)))) | |
15c9d04e SM |
1290 | (cl-loop for i from 0 |
1291 | for test across tests | |
1292 | for key = (ert--stats-test-key test) do | |
1293 | (cl-assert (not (gethash key map))) | |
1294 | (setf (gethash key map) i)) | |
d221e780 CO |
1295 | (make-ert--stats :selector selector |
1296 | :tests tests | |
1297 | :test-map map | |
1298 | :test-results (make-vector (length tests) nil) | |
1299 | :test-start-times (make-vector (length tests) nil) | |
1300 | :test-end-times (make-vector (length tests) nil)))) | |
1301 | ||
1302 | (defun ert-run-or-rerun-test (stats test listener) | |
1303 | ;; checkdoc-order: nil | |
1304 | "Run the single test TEST and record the result using STATS and LISTENER." | |
1305 | (let ((ert--current-run-stats stats) | |
1306 | (pos (ert--stats-test-pos stats test))) | |
1307 | (ert--stats-set-test-and-result stats pos test nil) | |
1308 | ;; Call listener after setting/before resetting | |
1309 | ;; (ert--stats-current-test stats); the listener might refresh the | |
1310 | ;; mode line display, and if the value is not set yet/any more | |
1311 | ;; during this refresh, the mode line will flicker unnecessarily. | |
1312 | (setf (ert--stats-current-test stats) test) | |
1313 | (funcall listener 'test-started stats test) | |
1314 | (setf (ert-test-most-recent-result test) nil) | |
1315 | (setf (aref (ert--stats-test-start-times stats) pos) (current-time)) | |
1316 | (unwind-protect | |
1317 | (ert-run-test test) | |
1318 | (setf (aref (ert--stats-test-end-times stats) pos) (current-time)) | |
1319 | (let ((result (ert-test-most-recent-result test))) | |
1320 | (ert--stats-set-test-and-result stats pos test result) | |
1321 | (funcall listener 'test-ended stats test result)) | |
1322 | (setf (ert--stats-current-test stats) nil)))) | |
1323 | ||
1324 | (defun ert-run-tests (selector listener) | |
1325 | "Run the tests specified by SELECTOR, sending progress updates to LISTENER." | |
1326 | (let* ((tests (ert-select-tests selector t)) | |
1327 | (stats (ert--make-stats tests selector))) | |
1328 | (setf (ert--stats-start-time stats) (current-time)) | |
1329 | (funcall listener 'run-started stats) | |
1330 | (let ((abortedp t)) | |
1331 | (unwind-protect | |
1332 | (let ((ert--current-run-stats stats)) | |
1333 | (force-mode-line-update) | |
1334 | (unwind-protect | |
1335 | (progn | |
15c9d04e SM |
1336 | (cl-loop for test in tests do |
1337 | (ert-run-or-rerun-test stats test listener)) | |
d221e780 CO |
1338 | (setq abortedp nil)) |
1339 | (setf (ert--stats-aborted-p stats) abortedp) | |
1340 | (setf (ert--stats-end-time stats) (current-time)) | |
1341 | (funcall listener 'run-ended stats abortedp))) | |
1342 | (force-mode-line-update)) | |
1343 | stats))) | |
1344 | ||
1345 | (defun ert--stats-test-pos (stats test) | |
1346 | ;; checkdoc-order: nil | |
1347 | "Return the position (index) of TEST in the run represented by STATS." | |
1348 | (gethash (ert--stats-test-key test) (ert--stats-test-map stats))) | |
1349 | ||
1350 | ||
1351 | ;;; Formatting functions shared across UIs. | |
1352 | ||
1353 | (defun ert--format-time-iso8601 (time) | |
1354 | "Format TIME in the variant of ISO 8601 used for timestamps in ERT." | |
1355 | (format-time-string "%Y-%m-%d %T%z" time)) | |
1356 | ||
1357 | (defun ert-char-for-test-result (result expectedp) | |
1358 | "Return a character that represents the test result RESULT. | |
1359 | ||
1360 | EXPECTEDP specifies whether the result was expected." | |
15c9d04e | 1361 | (let ((s (cl-etypecase result |
d221e780 CO |
1362 | (ert-test-passed ".P") |
1363 | (ert-test-failed "fF") | |
1364 | (null "--") | |
7c0d1441 CO |
1365 | (ert-test-aborted-with-non-local-exit "aA") |
1366 | (ert-test-quit "qQ")))) | |
d221e780 CO |
1367 | (elt s (if expectedp 0 1)))) |
1368 | ||
1369 | (defun ert-string-for-test-result (result expectedp) | |
1370 | "Return a string that represents the test result RESULT. | |
1371 | ||
1372 | EXPECTEDP specifies whether the result was expected." | |
15c9d04e | 1373 | (let ((s (cl-etypecase result |
d221e780 CO |
1374 | (ert-test-passed '("passed" "PASSED")) |
1375 | (ert-test-failed '("failed" "FAILED")) | |
1376 | (null '("unknown" "UNKNOWN")) | |
7c0d1441 CO |
1377 | (ert-test-aborted-with-non-local-exit '("aborted" "ABORTED")) |
1378 | (ert-test-quit '("quit" "QUIT"))))) | |
d221e780 CO |
1379 | (elt s (if expectedp 0 1)))) |
1380 | ||
1381 | (defun ert--pp-with-indentation-and-newline (object) | |
1382 | "Pretty-print OBJECT, indenting it to the current column of point. | |
1383 | Ensures a final newline is inserted." | |
1384 | (let ((begin (point))) | |
1385 | (pp object (current-buffer)) | |
1386 | (unless (bolp) (insert "\n")) | |
1387 | (save-excursion | |
1388 | (goto-char begin) | |
1389 | (indent-sexp)))) | |
1390 | ||
1391 | (defun ert--insert-infos (result) | |
1392 | "Insert `ert-info' infos from RESULT into current buffer. | |
1393 | ||
1394 | RESULT must be an `ert-test-result-with-condition'." | |
15c9d04e | 1395 | (cl-check-type result ert-test-result-with-condition) |
d221e780 | 1396 | (dolist (info (ert-test-result-with-condition-infos result)) |
15c9d04e | 1397 | (cl-destructuring-bind (prefix . message) info |
d221e780 CO |
1398 | (let ((begin (point)) |
1399 | (indentation (make-string (+ (length prefix) 4) ?\s)) | |
1400 | (end nil)) | |
1401 | (unwind-protect | |
1402 | (progn | |
1403 | (insert message "\n") | |
1404 | (setq end (copy-marker (point))) | |
1405 | (goto-char begin) | |
1406 | (insert " " prefix) | |
1407 | (forward-line 1) | |
1408 | (while (< (point) end) | |
1409 | (insert indentation) | |
1410 | (forward-line 1))) | |
1411 | (when end (set-marker end nil))))))) | |
1412 | ||
1413 | ||
1414 | ;;; Running tests in batch mode. | |
1415 | ||
1416 | (defvar ert-batch-backtrace-right-margin 70 | |
fb7ada5f | 1417 | "The maximum line length for printing backtraces in `ert-run-tests-batch'.") |
d221e780 CO |
1418 | |
1419 | ;;;###autoload | |
1420 | (defun ert-run-tests-batch (&optional selector) | |
1421 | "Run the tests specified by SELECTOR, printing results to the terminal. | |
1422 | ||
1423 | SELECTOR works as described in `ert-select-tests', except if | |
1424 | SELECTOR is nil, in which case all tests rather than none will be | |
1425 | run; this makes the command line \"emacs -batch -l my-tests.el -f | |
1426 | ert-run-tests-batch-and-exit\" useful. | |
1427 | ||
1428 | Returns the stats object." | |
1429 | (unless selector (setq selector 't)) | |
1430 | (ert-run-tests | |
1431 | selector | |
1432 | (lambda (event-type &rest event-args) | |
15c9d04e | 1433 | (cl-ecase event-type |
d221e780 | 1434 | (run-started |
15c9d04e | 1435 | (cl-destructuring-bind (stats) event-args |
d221e780 CO |
1436 | (message "Running %s tests (%s)" |
1437 | (length (ert--stats-tests stats)) | |
1438 | (ert--format-time-iso8601 (ert--stats-start-time stats))))) | |
1439 | (run-ended | |
15c9d04e | 1440 | (cl-destructuring-bind (stats abortedp) event-args |
d221e780 CO |
1441 | (let ((unexpected (ert-stats-completed-unexpected stats)) |
1442 | (expected-failures (ert--stats-failed-expected stats))) | |
1443 | (message "\n%sRan %s tests, %s results as expected%s (%s)%s\n" | |
1444 | (if (not abortedp) | |
1445 | "" | |
1446 | "Aborted: ") | |
1447 | (ert-stats-total stats) | |
1448 | (ert-stats-completed-expected stats) | |
1449 | (if (zerop unexpected) | |
1450 | "" | |
1451 | (format ", %s unexpected" unexpected)) | |
1452 | (ert--format-time-iso8601 (ert--stats-end-time stats)) | |
1453 | (if (zerop expected-failures) | |
1454 | "" | |
1455 | (format "\n%s expected failures" expected-failures))) | |
1456 | (unless (zerop unexpected) | |
1457 | (message "%s unexpected results:" unexpected) | |
15c9d04e SM |
1458 | (cl-loop for test across (ert--stats-tests stats) |
1459 | for result = (ert-test-most-recent-result test) do | |
1460 | (when (not (ert-test-result-expected-p test result)) | |
1461 | (message "%9s %S" | |
1462 | (ert-string-for-test-result result nil) | |
1463 | (ert-test-name test)))) | |
d221e780 CO |
1464 | (message "%s" ""))))) |
1465 | (test-started | |
1466 | ) | |
1467 | (test-ended | |
15c9d04e | 1468 | (cl-destructuring-bind (stats test result) event-args |
d221e780 | 1469 | (unless (ert-test-result-expected-p test result) |
15c9d04e | 1470 | (cl-etypecase result |
d221e780 CO |
1471 | (ert-test-passed |
1472 | (message "Test %S passed unexpectedly" (ert-test-name test))) | |
1473 | (ert-test-result-with-condition | |
1474 | (message "Test %S backtrace:" (ert-test-name test)) | |
1475 | (with-temp-buffer | |
1476 | (ert--print-backtrace (ert-test-result-with-condition-backtrace | |
1477 | result)) | |
1478 | (goto-char (point-min)) | |
1479 | (while (not (eobp)) | |
1480 | (let ((start (point)) | |
1481 | (end (progn (end-of-line) (point)))) | |
1482 | (setq end (min end | |
1483 | (+ start ert-batch-backtrace-right-margin))) | |
1484 | (message "%s" (buffer-substring-no-properties | |
1485 | start end))) | |
1486 | (forward-line 1))) | |
1487 | (with-temp-buffer | |
1488 | (ert--insert-infos result) | |
1489 | (insert " ") | |
1490 | (let ((print-escape-newlines t) | |
1491 | (print-level 5) | |
1492 | (print-length 10)) | |
7d476bde CO |
1493 | (ert--pp-with-indentation-and-newline |
1494 | (ert-test-result-with-condition-condition result))) | |
d221e780 | 1495 | (goto-char (1- (point-max))) |
15c9d04e | 1496 | (cl-assert (looking-at "\n")) |
d221e780 CO |
1497 | (delete-char 1) |
1498 | (message "Test %S condition:" (ert-test-name test)) | |
1499 | (message "%s" (buffer-string)))) | |
1500 | (ert-test-aborted-with-non-local-exit | |
1501 | (message "Test %S aborted with non-local exit" | |
7c0d1441 CO |
1502 | (ert-test-name test))) |
1503 | (ert-test-quit | |
1504 | (message "Quit during %S" (ert-test-name test))))) | |
d221e780 CO |
1505 | (let* ((max (prin1-to-string (length (ert--stats-tests stats)))) |
1506 | (format-string (concat "%9s %" | |
1507 | (prin1-to-string (length max)) | |
1508 | "s/" max " %S"))) | |
1509 | (message format-string | |
1510 | (ert-string-for-test-result result | |
1511 | (ert-test-result-expected-p | |
1512 | test result)) | |
1513 | (1+ (ert--stats-test-pos stats test)) | |
1514 | (ert-test-name test))))))))) | |
1515 | ||
1516 | ;;;###autoload | |
1517 | (defun ert-run-tests-batch-and-exit (&optional selector) | |
1518 | "Like `ert-run-tests-batch', but exits Emacs when done. | |
1519 | ||
1520 | The exit status will be 0 if all test results were as expected, 1 | |
1521 | on unexpected results, or 2 if the tool detected an error outside | |
1522 | of the tests (e.g. invalid SELECTOR or bug in the code that runs | |
1523 | the tests)." | |
1524 | (unwind-protect | |
1525 | (let ((stats (ert-run-tests-batch selector))) | |
1526 | (kill-emacs (if (zerop (ert-stats-completed-unexpected stats)) 0 1))) | |
1527 | (unwind-protect | |
1528 | (progn | |
1529 | (message "Error running tests") | |
1530 | (backtrace)) | |
1531 | (kill-emacs 2)))) | |
1532 | ||
1533 | ||
1534 | ;;; Utility functions for load/unload actions. | |
1535 | ||
1536 | (defun ert--activate-font-lock-keywords () | |
1537 | "Activate font-lock keywords for some of ERT's symbols." | |
1538 | (font-lock-add-keywords | |
1539 | nil | |
1540 | '(("(\\(\\<ert-deftest\\)\\>\\s *\\(\\sw+\\)?" | |
1541 | (1 font-lock-keyword-face nil t) | |
1542 | (2 font-lock-function-name-face nil t))))) | |
1543 | ||
15c9d04e | 1544 | (cl-defun ert--remove-from-list (list-var element &key key test) |
d221e780 CO |
1545 | "Remove ELEMENT from the value of LIST-VAR if present. |
1546 | ||
1547 | This can be used as an inverse of `add-to-list'." | |
1548 | (unless key (setq key #'identity)) | |
1549 | (unless test (setq test #'equal)) | |
1550 | (setf (symbol-value list-var) | |
1551 | (ert--remove* element | |
1552 | (symbol-value list-var) | |
1553 | :key key | |
1554 | :test test))) | |
1555 | ||
1556 | ||
1557 | ;;; Some basic interactive functions. | |
1558 | ||
1559 | (defun ert-read-test-name (prompt &optional default history | |
1560 | add-default-to-prompt) | |
1561 | "Read the name of a test and return it as a symbol. | |
1562 | ||
1563 | Prompt with PROMPT. If DEFAULT is a valid test name, use it as a | |
1564 | default. HISTORY is the history to use; see `completing-read'. | |
1565 | If ADD-DEFAULT-TO-PROMPT is non-nil, PROMPT will be modified to | |
1566 | include the default, if any. | |
1567 | ||
1568 | Signals an error if no test name was read." | |
15c9d04e | 1569 | (cl-etypecase default |
d221e780 CO |
1570 | (string (let ((symbol (intern-soft default))) |
1571 | (unless (and symbol (ert-test-boundp symbol)) | |
1572 | (setq default nil)))) | |
1573 | (symbol (setq default | |
1574 | (if (ert-test-boundp default) | |
1575 | (symbol-name default) | |
1576 | nil))) | |
1577 | (ert-test (setq default (ert-test-name default)))) | |
1578 | (when add-default-to-prompt | |
1579 | (setq prompt (if (null default) | |
1580 | (format "%s: " prompt) | |
1581 | (format "%s (default %s): " prompt default)))) | |
1582 | (let ((input (completing-read prompt obarray #'ert-test-boundp | |
1583 | t nil history default nil))) | |
1584 | ;; completing-read returns an empty string if default was nil and | |
1585 | ;; the user just hit enter. | |
1586 | (let ((sym (intern-soft input))) | |
1587 | (if (ert-test-boundp sym) | |
1588 | sym | |
1589 | (error "Input does not name a test"))))) | |
1590 | ||
1591 | (defun ert-read-test-name-at-point (prompt) | |
1592 | "Read the name of a test and return it as a symbol. | |
1593 | As a default, use the symbol at point, or the test at point if in | |
1594 | the ERT results buffer. Prompt with PROMPT, augmented with the | |
1595 | default (if any)." | |
1596 | (ert-read-test-name prompt (ert-test-at-point) nil t)) | |
1597 | ||
1598 | (defun ert-find-test-other-window (test-name) | |
1599 | "Find, in another window, the definition of TEST-NAME." | |
1600 | (interactive (list (ert-read-test-name-at-point "Find test definition: "))) | |
1601 | (find-function-do-it test-name 'ert-deftest 'switch-to-buffer-other-window)) | |
1602 | ||
1603 | (defun ert-delete-test (test-name) | |
1604 | "Make the test TEST-NAME unbound. | |
1605 | ||
1606 | Nothing more than an interactive interface to `ert-make-test-unbound'." | |
1607 | (interactive (list (ert-read-test-name-at-point "Delete test"))) | |
1608 | (ert-make-test-unbound test-name)) | |
1609 | ||
1610 | (defun ert-delete-all-tests () | |
1611 | "Make all symbols in `obarray' name no test." | |
1612 | (interactive) | |
7d476bde | 1613 | (when (called-interactively-p 'any) |
d221e780 CO |
1614 | (unless (y-or-n-p "Delete all tests? ") |
1615 | (error "Aborted"))) | |
1616 | ;; We can't use `ert-select-tests' here since that gives us only | |
1617 | ;; test objects, and going from them back to the test name symbols | |
1618 | ;; can fail if the `ert-test' defstruct has been redefined. | |
1619 | (mapc #'ert-make-test-unbound (apropos-internal "" #'ert-test-boundp)) | |
1620 | t) | |
1621 | ||
1622 | ||
1623 | ;;; Display of test progress and results. | |
1624 | ||
1625 | ;; An entry in the results buffer ewoc. There is one entry per test. | |
15c9d04e SM |
1626 | (cl-defstruct ert--ewoc-entry |
1627 | (test (cl-assert nil)) | |
d221e780 CO |
1628 | ;; If the result of this test was expected, its ewoc entry is hidden |
1629 | ;; initially. | |
15c9d04e | 1630 | (hidden-p (cl-assert nil)) |
d221e780 CO |
1631 | ;; An ewoc entry may be collapsed to hide details such as the error |
1632 | ;; condition. | |
1633 | ;; | |
1634 | ;; I'm not sure the ability to expand and collapse entries is still | |
1635 | ;; a useful feature. | |
1636 | (expanded-p t) | |
1637 | ;; By default, the ewoc entry presents the error condition with | |
1638 | ;; certain limits on how much to print (`print-level', | |
1639 | ;; `print-length'). The user can interactively switch to a set of | |
1640 | ;; higher limits. | |
1641 | (extended-printer-limits-p nil)) | |
1642 | ||
1643 | ;; Variables local to the results buffer. | |
1644 | ||
1645 | ;; The ewoc. | |
1646 | (defvar ert--results-ewoc) | |
1647 | ;; The stats object. | |
1648 | (defvar ert--results-stats) | |
1649 | ;; A string with one character per test. Each character represents | |
1650 | ;; the result of the corresponding test. The string is displayed near | |
1651 | ;; the top of the buffer and serves as a progress bar. | |
1652 | (defvar ert--results-progress-bar-string) | |
1653 | ;; The position where the progress bar button begins. | |
1654 | (defvar ert--results-progress-bar-button-begin) | |
1655 | ;; The test result listener that updates the buffer when tests are run. | |
1656 | (defvar ert--results-listener) | |
1657 | ||
1658 | (defun ert-insert-test-name-button (test-name) | |
1659 | "Insert a button that links to TEST-NAME." | |
1660 | (insert-text-button (format "%S" test-name) | |
1661 | :type 'ert--test-name-button | |
1662 | 'ert-test-name test-name)) | |
1663 | ||
1664 | (defun ert--results-format-expected-unexpected (expected unexpected) | |
1665 | "Return a string indicating EXPECTED expected results, UNEXPECTED unexpected." | |
1666 | (if (zerop unexpected) | |
1667 | (format "%s" expected) | |
1668 | (format "%s (%s unexpected)" (+ expected unexpected) unexpected))) | |
1669 | ||
1670 | (defun ert--results-update-ewoc-hf (ewoc stats) | |
1671 | "Update the header and footer of EWOC to show certain information from STATS. | |
1672 | ||
1673 | Also sets `ert--results-progress-bar-button-begin'." | |
1674 | (let ((run-count (ert-stats-completed stats)) | |
1675 | (results-buffer (current-buffer)) | |
1676 | ;; Need to save buffer-local value. | |
1677 | (font-lock font-lock-mode)) | |
1678 | (ewoc-set-hf | |
1679 | ewoc | |
1680 | ;; header | |
1681 | (with-temp-buffer | |
1682 | (insert "Selector: ") | |
1683 | (ert--insert-human-readable-selector (ert--stats-selector stats)) | |
1684 | (insert "\n") | |
1685 | (insert | |
1686 | (format (concat "Passed: %s\n" | |
1687 | "Failed: %s\n" | |
1688 | "Total: %s/%s\n\n") | |
1689 | (ert--results-format-expected-unexpected | |
1690 | (ert--stats-passed-expected stats) | |
1691 | (ert--stats-passed-unexpected stats)) | |
1692 | (ert--results-format-expected-unexpected | |
1693 | (ert--stats-failed-expected stats) | |
1694 | (ert--stats-failed-unexpected stats)) | |
1695 | run-count | |
1696 | (ert-stats-total stats))) | |
1697 | (insert | |
1698 | (format "Started at: %s\n" | |
1699 | (ert--format-time-iso8601 (ert--stats-start-time stats)))) | |
1700 | ;; FIXME: This is ugly. Need to properly define invariants of | |
1701 | ;; the `stats' data structure. | |
1702 | (let ((state (cond ((ert--stats-aborted-p stats) 'aborted) | |
1703 | ((ert--stats-current-test stats) 'running) | |
1704 | ((ert--stats-end-time stats) 'finished) | |
1705 | (t 'preparing)))) | |
15c9d04e | 1706 | (cl-ecase state |
d221e780 CO |
1707 | (preparing |
1708 | (insert "")) | |
1709 | (aborted | |
1710 | (cond ((ert--stats-current-test stats) | |
1711 | (insert "Aborted during test: ") | |
1712 | (ert-insert-test-name-button | |
1713 | (ert-test-name (ert--stats-current-test stats)))) | |
1714 | (t | |
1715 | (insert "Aborted.")))) | |
1716 | (running | |
15c9d04e | 1717 | (cl-assert (ert--stats-current-test stats)) |
d221e780 CO |
1718 | (insert "Running test: ") |
1719 | (ert-insert-test-name-button (ert-test-name | |
1720 | (ert--stats-current-test stats)))) | |
1721 | (finished | |
15c9d04e | 1722 | (cl-assert (not (ert--stats-current-test stats))) |
d221e780 CO |
1723 | (insert "Finished."))) |
1724 | (insert "\n") | |
1725 | (if (ert--stats-end-time stats) | |
1726 | (insert | |
1727 | (format "%s%s\n" | |
1728 | (if (ert--stats-aborted-p stats) | |
1729 | "Aborted at: " | |
1730 | "Finished at: ") | |
1731 | (ert--format-time-iso8601 (ert--stats-end-time stats)))) | |
1732 | (insert "\n")) | |
1733 | (insert "\n")) | |
1734 | (let ((progress-bar-string (with-current-buffer results-buffer | |
1735 | ert--results-progress-bar-string))) | |
1736 | (let ((progress-bar-button-begin | |
1737 | (insert-text-button progress-bar-string | |
1738 | :type 'ert--results-progress-bar-button | |
1739 | 'face (or (and font-lock | |
1740 | (ert-face-for-stats stats)) | |
1741 | 'button)))) | |
1742 | ;; The header gets copied verbatim to the results buffer, | |
1743 | ;; and all positions remain the same, so | |
1744 | ;; `progress-bar-button-begin' will be the right position | |
1745 | ;; even in the results buffer. | |
1746 | (with-current-buffer results-buffer | |
1747 | (set (make-local-variable 'ert--results-progress-bar-button-begin) | |
1748 | progress-bar-button-begin)))) | |
1749 | (insert "\n\n") | |
1750 | (buffer-string)) | |
1751 | ;; footer | |
1752 | ;; | |
1753 | ;; We actually want an empty footer, but that would trigger a bug | |
1754 | ;; in ewoc, sometimes clearing the entire buffer. (It's possible | |
1755 | ;; that this bug has been fixed since this has been tested; we | |
1756 | ;; should test it again.) | |
1757 | "\n"))) | |
1758 | ||
1759 | ||
1760 | (defvar ert-test-run-redisplay-interval-secs .1 | |
1761 | "How many seconds ERT should wait between redisplays while running tests. | |
1762 | ||
1763 | While running tests, ERT shows the current progress, and this variable | |
1764 | determines how frequently the progress display is updated.") | |
1765 | ||
1766 | (defun ert--results-update-stats-display (ewoc stats) | |
1767 | "Update EWOC and the mode line to show data from STATS." | |
1768 | ;; TODO(ohler): investigate using `make-progress-reporter'. | |
1769 | (ert--results-update-ewoc-hf ewoc stats) | |
1770 | (force-mode-line-update) | |
1771 | (redisplay t) | |
1772 | (setf (ert--stats-next-redisplay stats) | |
1773 | (+ (float-time) ert-test-run-redisplay-interval-secs))) | |
1774 | ||
1775 | (defun ert--results-update-stats-display-maybe (ewoc stats) | |
1776 | "Call `ert--results-update-stats-display' if not called recently. | |
1777 | ||
1778 | EWOC and STATS are arguments for `ert--results-update-stats-display'." | |
1779 | (when (>= (float-time) (ert--stats-next-redisplay stats)) | |
1780 | (ert--results-update-stats-display ewoc stats))) | |
1781 | ||
1782 | (defun ert--tests-running-mode-line-indicator () | |
1783 | "Return a string for the mode line that shows the test run progress." | |
1784 | (let* ((stats ert--current-run-stats) | |
1785 | (tests-total (ert-stats-total stats)) | |
1786 | (tests-completed (ert-stats-completed stats))) | |
1787 | (if (>= tests-completed tests-total) | |
1788 | (format " ERT(%s/%s,finished)" tests-completed tests-total) | |
1789 | (format " ERT(%s/%s):%s" | |
1790 | (1+ tests-completed) | |
1791 | tests-total | |
1792 | (if (null (ert--stats-current-test stats)) | |
1793 | "?" | |
1794 | (format "%S" | |
1795 | (ert-test-name (ert--stats-current-test stats)))))))) | |
1796 | ||
1797 | (defun ert--make-xrefs-region (begin end) | |
1798 | "Attach cross-references to function names between BEGIN and END. | |
1799 | ||
1800 | BEGIN and END specify a region in the current buffer." | |
1801 | (save-excursion | |
1802 | (save-restriction | |
7d476bde | 1803 | (narrow-to-region begin end) |
d221e780 CO |
1804 | ;; Inhibit optimization in `debugger-make-xrefs' that would |
1805 | ;; sometimes insert unrelated backtrace info into our buffer. | |
1806 | (let ((debugger-previous-backtrace nil)) | |
1807 | (debugger-make-xrefs))))) | |
1808 | ||
1809 | (defun ert--string-first-line (s) | |
1810 | "Return the first line of S, or S if it contains no newlines. | |
1811 | ||
1812 | The return value does not include the line terminator." | |
1813 | (substring s 0 (ert--string-position ?\n s))) | |
1814 | ||
1815 | (defun ert-face-for-test-result (expectedp) | |
1816 | "Return a face that shows whether a test result was expected or unexpected. | |
1817 | ||
1818 | If EXPECTEDP is nil, returns the face for unexpected results; if | |
1819 | non-nil, returns the face for expected results.." | |
1820 | (if expectedp 'ert-test-result-expected 'ert-test-result-unexpected)) | |
1821 | ||
1822 | (defun ert-face-for-stats (stats) | |
1823 | "Return a face that represents STATS." | |
1824 | (cond ((ert--stats-aborted-p stats) 'nil) | |
15c9d04e | 1825 | ((cl-plusp (ert-stats-completed-unexpected stats)) |
d221e780 CO |
1826 | (ert-face-for-test-result nil)) |
1827 | ((eql (ert-stats-completed-expected stats) (ert-stats-total stats)) | |
1828 | (ert-face-for-test-result t)) | |
1829 | (t 'nil))) | |
1830 | ||
1831 | (defun ert--print-test-for-ewoc (entry) | |
1832 | "The ewoc print function for ewoc test entries. ENTRY is the entry to print." | |
1833 | (let* ((test (ert--ewoc-entry-test entry)) | |
1834 | (stats ert--results-stats) | |
1835 | (result (let ((pos (ert--stats-test-pos stats test))) | |
15c9d04e | 1836 | (cl-assert pos) |
d221e780 CO |
1837 | (aref (ert--stats-test-results stats) pos))) |
1838 | (hiddenp (ert--ewoc-entry-hidden-p entry)) | |
1839 | (expandedp (ert--ewoc-entry-expanded-p entry)) | |
1840 | (extended-printer-limits-p (ert--ewoc-entry-extended-printer-limits-p | |
1841 | entry))) | |
1842 | (cond (hiddenp) | |
1843 | (t | |
1844 | (let ((expectedp (ert-test-result-expected-p test result))) | |
1845 | (insert-text-button (format "%c" (ert-char-for-test-result | |
1846 | result expectedp)) | |
1847 | :type 'ert--results-expand-collapse-button | |
1848 | 'face (or (and font-lock-mode | |
1849 | (ert-face-for-test-result | |
1850 | expectedp)) | |
1851 | 'button))) | |
1852 | (insert " ") | |
1853 | (ert-insert-test-name-button (ert-test-name test)) | |
1854 | (insert "\n") | |
1855 | (when (and expandedp (not (eql result 'nil))) | |
1856 | (when (ert-test-documentation test) | |
1857 | (insert " " | |
1858 | (propertize | |
1859 | (ert--string-first-line (ert-test-documentation test)) | |
1860 | 'font-lock-face 'font-lock-doc-face) | |
1861 | "\n")) | |
15c9d04e | 1862 | (cl-etypecase result |
d221e780 CO |
1863 | (ert-test-passed |
1864 | (if (ert-test-result-expected-p test result) | |
1865 | (insert " passed\n") | |
1866 | (insert " passed unexpectedly\n")) | |
1867 | (insert "")) | |
1868 | (ert-test-result-with-condition | |
1869 | (ert--insert-infos result) | |
1870 | (let ((print-escape-newlines t) | |
1871 | (print-level (if extended-printer-limits-p 12 6)) | |
1872 | (print-length (if extended-printer-limits-p 100 10))) | |
1873 | (insert " ") | |
1874 | (let ((begin (point))) | |
1875 | (ert--pp-with-indentation-and-newline | |
1876 | (ert-test-result-with-condition-condition result)) | |
1877 | (ert--make-xrefs-region begin (point))))) | |
1878 | (ert-test-aborted-with-non-local-exit | |
7c0d1441 CO |
1879 | (insert " aborted\n")) |
1880 | (ert-test-quit | |
1881 | (insert " quit\n"))) | |
d221e780 CO |
1882 | (insert "\n"))))) |
1883 | nil) | |
1884 | ||
1885 | (defun ert--results-font-lock-function (enabledp) | |
1886 | "Redraw the ERT results buffer after font-lock-mode was switched on or off. | |
1887 | ||
1888 | ENABLEDP is true if font-lock-mode is switched on, false | |
1889 | otherwise." | |
1890 | (ert--results-update-ewoc-hf ert--results-ewoc ert--results-stats) | |
1891 | (ewoc-refresh ert--results-ewoc) | |
1892 | (font-lock-default-function enabledp)) | |
1893 | ||
1894 | (defun ert--setup-results-buffer (stats listener buffer-name) | |
1895 | "Set up a test results buffer. | |
1896 | ||
1897 | STATS is the stats object; LISTENER is the results listener; | |
1898 | BUFFER-NAME, if non-nil, is the buffer name to use." | |
1899 | (unless buffer-name (setq buffer-name "*ert*")) | |
1900 | (let ((buffer (get-buffer-create buffer-name))) | |
1901 | (with-current-buffer buffer | |
d221e780 CO |
1902 | (let ((inhibit-read-only t)) |
1903 | (buffer-disable-undo) | |
1904 | (erase-buffer) | |
5da16a86 | 1905 | (ert-results-mode) |
d221e780 CO |
1906 | ;; Erase buffer again in case switching out of the previous |
1907 | ;; mode inserted anything. (This happens e.g. when switching | |
1908 | ;; from ert-results-mode to ert-results-mode when | |
1909 | ;; font-lock-mode turns itself off in change-major-mode-hook.) | |
1910 | (erase-buffer) | |
1911 | (set (make-local-variable 'font-lock-function) | |
1912 | 'ert--results-font-lock-function) | |
1913 | (let ((ewoc (ewoc-create 'ert--print-test-for-ewoc nil nil t))) | |
1914 | (set (make-local-variable 'ert--results-ewoc) ewoc) | |
1915 | (set (make-local-variable 'ert--results-stats) stats) | |
1916 | (set (make-local-variable 'ert--results-progress-bar-string) | |
1917 | (make-string (ert-stats-total stats) | |
1918 | (ert-char-for-test-result nil t))) | |
1919 | (set (make-local-variable 'ert--results-listener) listener) | |
15c9d04e SM |
1920 | (cl-loop for test across (ert--stats-tests stats) do |
1921 | (ewoc-enter-last ewoc | |
1922 | (make-ert--ewoc-entry :test test | |
1923 | :hidden-p t))) | |
d221e780 | 1924 | (ert--results-update-ewoc-hf ert--results-ewoc ert--results-stats) |
5da16a86 CO |
1925 | (goto-char (1- (point-max))) |
1926 | buffer))))) | |
d221e780 CO |
1927 | |
1928 | ||
1929 | (defvar ert--selector-history nil | |
1930 | "List of recent test selectors read from terminal.") | |
1931 | ||
1932 | ;; Should OUTPUT-BUFFER-NAME and MESSAGE-FN really be arguments here? | |
1933 | ;; They are needed only for our automated self-tests at the moment. | |
1934 | ;; Or should there be some other mechanism? | |
1935 | ;;;###autoload | |
1936 | (defun ert-run-tests-interactively (selector | |
1937 | &optional output-buffer-name message-fn) | |
1938 | "Run the tests specified by SELECTOR and display the results in a buffer. | |
1939 | ||
1940 | SELECTOR works as described in `ert-select-tests'. | |
1941 | OUTPUT-BUFFER-NAME and MESSAGE-FN should normally be nil; they | |
1942 | are used for automated self-tests and specify which buffer to use | |
1943 | and how to display message." | |
1944 | (interactive | |
1945 | (list (let ((default (if ert--selector-history | |
1946 | ;; Can't use `first' here as this form is | |
1947 | ;; not compiled, and `first' is not | |
1948 | ;; defined without cl. | |
1949 | (car ert--selector-history) | |
1950 | "t"))) | |
1951 | (read-from-minibuffer (if (null default) | |
1952 | "Run tests: " | |
1953 | (format "Run tests (default %s): " default)) | |
1954 | nil nil t 'ert--selector-history | |
1955 | default nil)) | |
1956 | nil)) | |
1957 | (unless message-fn (setq message-fn 'message)) | |
15c9d04e SM |
1958 | (let ((output-buffer-name output-buffer-name) |
1959 | buffer | |
1960 | listener | |
1961 | (message-fn message-fn)) | |
d221e780 CO |
1962 | (setq listener |
1963 | (lambda (event-type &rest event-args) | |
15c9d04e | 1964 | (cl-ecase event-type |
d221e780 | 1965 | (run-started |
15c9d04e | 1966 | (cl-destructuring-bind (stats) event-args |
d221e780 CO |
1967 | (setq buffer (ert--setup-results-buffer stats |
1968 | listener | |
1969 | output-buffer-name)) | |
1970 | (pop-to-buffer buffer))) | |
1971 | (run-ended | |
15c9d04e | 1972 | (cl-destructuring-bind (stats abortedp) event-args |
d221e780 CO |
1973 | (funcall message-fn |
1974 | "%sRan %s tests, %s results were as expected%s" | |
1975 | (if (not abortedp) | |
1976 | "" | |
1977 | "Aborted: ") | |
1978 | (ert-stats-total stats) | |
1979 | (ert-stats-completed-expected stats) | |
1980 | (let ((unexpected | |
1981 | (ert-stats-completed-unexpected stats))) | |
1982 | (if (zerop unexpected) | |
1983 | "" | |
1984 | (format ", %s unexpected" unexpected)))) | |
1985 | (ert--results-update-stats-display (with-current-buffer buffer | |
1986 | ert--results-ewoc) | |
1987 | stats))) | |
1988 | (test-started | |
15c9d04e | 1989 | (cl-destructuring-bind (stats test) event-args |
d221e780 CO |
1990 | (with-current-buffer buffer |
1991 | (let* ((ewoc ert--results-ewoc) | |
1992 | (pos (ert--stats-test-pos stats test)) | |
1993 | (node (ewoc-nth ewoc pos))) | |
15c9d04e | 1994 | (cl-assert node) |
d221e780 CO |
1995 | (setf (ert--ewoc-entry-test (ewoc-data node)) test) |
1996 | (aset ert--results-progress-bar-string pos | |
1997 | (ert-char-for-test-result nil t)) | |
1998 | (ert--results-update-stats-display-maybe ewoc stats) | |
1999 | (ewoc-invalidate ewoc node))))) | |
2000 | (test-ended | |
15c9d04e | 2001 | (cl-destructuring-bind (stats test result) event-args |
d221e780 CO |
2002 | (with-current-buffer buffer |
2003 | (let* ((ewoc ert--results-ewoc) | |
2004 | (pos (ert--stats-test-pos stats test)) | |
2005 | (node (ewoc-nth ewoc pos))) | |
2006 | (when (ert--ewoc-entry-hidden-p (ewoc-data node)) | |
2007 | (setf (ert--ewoc-entry-hidden-p (ewoc-data node)) | |
2008 | (ert-test-result-expected-p test result))) | |
2009 | (aset ert--results-progress-bar-string pos | |
2010 | (ert-char-for-test-result result | |
2011 | (ert-test-result-expected-p | |
2012 | test result))) | |
2013 | (ert--results-update-stats-display-maybe ewoc stats) | |
2014 | (ewoc-invalidate ewoc node)))))))) | |
2015 | (ert-run-tests | |
2016 | selector | |
2017 | listener))) | |
2018 | ;;;###autoload | |
2019 | (defalias 'ert 'ert-run-tests-interactively) | |
2020 | ||
2021 | ||
2022 | ;;; Simple view mode for auxiliary information like stack traces or | |
2023 | ;;; messages. Mainly binds "q" for quit. | |
2024 | ||
abef340a | 2025 | (define-derived-mode ert-simple-view-mode special-mode "ERT-View" |
d221e780 CO |
2026 | "Major mode for viewing auxiliary information in ERT.") |
2027 | ||
d221e780 CO |
2028 | ;;; Commands and button actions for the results buffer. |
2029 | ||
abef340a | 2030 | (define-derived-mode ert-results-mode special-mode "ERT-Results" |
d221e780 CO |
2031 | "Major mode for viewing results of ERT test runs.") |
2032 | ||
15c9d04e SM |
2033 | (cl-loop for (key binding) in |
2034 | '( ;; Stuff that's not in the menu. | |
2035 | ("\t" forward-button) | |
2036 | ([backtab] backward-button) | |
2037 | ("j" ert-results-jump-between-summary-and-result) | |
2038 | ("L" ert-results-toggle-printer-limits-for-test-at-point) | |
2039 | ("n" ert-results-next-test) | |
2040 | ("p" ert-results-previous-test) | |
2041 | ;; Stuff that is in the menu. | |
2042 | ("R" ert-results-rerun-all-tests) | |
2043 | ("r" ert-results-rerun-test-at-point) | |
2044 | ("d" ert-results-rerun-test-at-point-debugging-errors) | |
2045 | ("." ert-results-find-test-at-point-other-window) | |
2046 | ("b" ert-results-pop-to-backtrace-for-test-at-point) | |
2047 | ("m" ert-results-pop-to-messages-for-test-at-point) | |
2048 | ("l" ert-results-pop-to-should-forms-for-test-at-point) | |
2049 | ("h" ert-results-describe-test-at-point) | |
2050 | ("D" ert-delete-test) | |
2051 | ("T" ert-results-pop-to-timings) | |
2052 | ) | |
2053 | do | |
2054 | (define-key ert-results-mode-map key binding)) | |
d221e780 CO |
2055 | |
2056 | (easy-menu-define ert-results-mode-menu ert-results-mode-map | |
2057 | "Menu for `ert-results-mode'." | |
2058 | '("ERT Results" | |
2059 | ["Re-run all tests" ert-results-rerun-all-tests] | |
2060 | "--" | |
2061 | ["Re-run test" ert-results-rerun-test-at-point] | |
2062 | ["Debug test" ert-results-rerun-test-at-point-debugging-errors] | |
2063 | ["Show test definition" ert-results-find-test-at-point-other-window] | |
2064 | "--" | |
2065 | ["Show backtrace" ert-results-pop-to-backtrace-for-test-at-point] | |
2066 | ["Show messages" ert-results-pop-to-messages-for-test-at-point] | |
2067 | ["Show `should' forms" ert-results-pop-to-should-forms-for-test-at-point] | |
2068 | ["Describe test" ert-results-describe-test-at-point] | |
2069 | "--" | |
2070 | ["Delete test" ert-delete-test] | |
2071 | "--" | |
2072 | ["Show execution time of each test" ert-results-pop-to-timings] | |
2073 | )) | |
2074 | ||
2075 | (define-button-type 'ert--results-progress-bar-button | |
2076 | 'action #'ert--results-progress-bar-button-action | |
2077 | 'help-echo "mouse-2, RET: Reveal test result") | |
2078 | ||
2079 | (define-button-type 'ert--test-name-button | |
2080 | 'action #'ert--test-name-button-action | |
2081 | 'help-echo "mouse-2, RET: Find test definition") | |
2082 | ||
2083 | (define-button-type 'ert--results-expand-collapse-button | |
2084 | 'action #'ert--results-expand-collapse-button-action | |
2085 | 'help-echo "mouse-2, RET: Expand/collapse test result") | |
2086 | ||
2087 | (defun ert--results-test-node-or-null-at-point () | |
2088 | "If point is on a valid ewoc node, return it; return nil otherwise. | |
2089 | ||
2090 | To be used in the ERT results buffer." | |
2091 | (let* ((ewoc ert--results-ewoc) | |
2092 | (node (ewoc-locate ewoc))) | |
2093 | ;; `ewoc-locate' will return an arbitrary node when point is on | |
2094 | ;; header or footer, or when all nodes are invisible. So we need | |
2095 | ;; to validate its return value here. | |
2096 | ;; | |
2097 | ;; Update: I'm seeing nil being returned in some cases now, | |
2098 | ;; perhaps this has been changed? | |
2099 | (if (and node | |
2100 | (>= (point) (ewoc-location node)) | |
2101 | (not (ert--ewoc-entry-hidden-p (ewoc-data node)))) | |
2102 | node | |
2103 | nil))) | |
2104 | ||
2105 | (defun ert--results-test-node-at-point () | |
2106 | "If point is on a valid ewoc node, return it; signal an error otherwise. | |
2107 | ||
2108 | To be used in the ERT results buffer." | |
2109 | (or (ert--results-test-node-or-null-at-point) | |
2110 | (error "No test at point"))) | |
2111 | ||
2112 | (defun ert-results-next-test () | |
2113 | "Move point to the next test. | |
2114 | ||
2115 | To be used in the ERT results buffer." | |
2116 | (interactive) | |
2117 | (ert--results-move (ewoc-locate ert--results-ewoc) 'ewoc-next | |
2118 | "No tests below")) | |
2119 | ||
2120 | (defun ert-results-previous-test () | |
2121 | "Move point to the previous test. | |
2122 | ||
2123 | To be used in the ERT results buffer." | |
2124 | (interactive) | |
2125 | (ert--results-move (ewoc-locate ert--results-ewoc) 'ewoc-prev | |
2126 | "No tests above")) | |
2127 | ||
2128 | (defun ert--results-move (node ewoc-fn error-message) | |
2129 | "Move point from NODE to the previous or next node. | |
2130 | ||
2131 | EWOC-FN specifies the direction and should be either `ewoc-prev' | |
2132 | or `ewoc-next'. If there are no more nodes in that direction, an | |
8350f087 | 2133 | error is signaled with the message ERROR-MESSAGE." |
15c9d04e | 2134 | (cl-loop |
d221e780 CO |
2135 | (setq node (funcall ewoc-fn ert--results-ewoc node)) |
2136 | (when (null node) | |
2137 | (error "%s" error-message)) | |
2138 | (unless (ert--ewoc-entry-hidden-p (ewoc-data node)) | |
2139 | (goto-char (ewoc-location node)) | |
15c9d04e | 2140 | (cl-return)))) |
d221e780 | 2141 | |
15c9d04e | 2142 | (defun ert--results-expand-collapse-button-action (_button) |
d221e780 CO |
2143 | "Expand or collapse the test node BUTTON belongs to." |
2144 | (let* ((ewoc ert--results-ewoc) | |
2145 | (node (save-excursion | |
2146 | (goto-char (ert--button-action-position)) | |
2147 | (ert--results-test-node-at-point))) | |
2148 | (entry (ewoc-data node))) | |
2149 | (setf (ert--ewoc-entry-expanded-p entry) | |
2150 | (not (ert--ewoc-entry-expanded-p entry))) | |
2151 | (ewoc-invalidate ewoc node))) | |
2152 | ||
2153 | (defun ert-results-find-test-at-point-other-window () | |
2154 | "Find the definition of the test at point in another window. | |
2155 | ||
2156 | To be used in the ERT results buffer." | |
2157 | (interactive) | |
2158 | (let ((name (ert-test-at-point))) | |
2159 | (unless name | |
2160 | (error "No test at point")) | |
2161 | (ert-find-test-other-window name))) | |
2162 | ||
2163 | (defun ert--test-name-button-action (button) | |
2164 | "Find the definition of the test BUTTON belongs to, in another window." | |
2165 | (let ((name (button-get button 'ert-test-name))) | |
2166 | (ert-find-test-other-window name))) | |
2167 | ||
2168 | (defun ert--ewoc-position (ewoc node) | |
2169 | ;; checkdoc-order: nil | |
2170 | "Return the position of NODE in EWOC, or nil if NODE is not in EWOC." | |
15c9d04e SM |
2171 | (cl-loop for i from 0 |
2172 | for node-here = (ewoc-nth ewoc 0) then (ewoc-next ewoc node-here) | |
2173 | do (when (eql node node-here) | |
2174 | (cl-return i)) | |
2175 | finally (cl-return nil))) | |
d221e780 CO |
2176 | |
2177 | (defun ert-results-jump-between-summary-and-result () | |
2178 | "Jump back and forth between the test run summary and individual test results. | |
2179 | ||
2180 | From an ewoc node, jumps to the character that represents the | |
2181 | same test in the progress bar, and vice versa. | |
2182 | ||
2183 | To be used in the ERT results buffer." | |
2184 | ;; Maybe this command isn't actually needed much, but if it is, it | |
2185 | ;; seems like an indication that the UI design is not optimal. If | |
2186 | ;; jumping back and forth between a summary at the top of the buffer | |
2187 | ;; and the error log in the remainder of the buffer is useful, then | |
2188 | ;; the summary apparently needs to be easily accessible from the | |
2189 | ;; error log, and perhaps it would be better to have it in a | |
2190 | ;; separate buffer to keep it visible. | |
2191 | (interactive) | |
2192 | (let ((ewoc ert--results-ewoc) | |
2193 | (progress-bar-begin ert--results-progress-bar-button-begin)) | |
2194 | (cond ((ert--results-test-node-or-null-at-point) | |
2195 | (let* ((node (ert--results-test-node-at-point)) | |
2196 | (pos (ert--ewoc-position ewoc node))) | |
2197 | (goto-char (+ progress-bar-begin pos)))) | |
2198 | ((and (<= progress-bar-begin (point)) | |
2199 | (< (point) (button-end (button-at progress-bar-begin)))) | |
2200 | (let* ((node (ewoc-nth ewoc (- (point) progress-bar-begin))) | |
2201 | (entry (ewoc-data node))) | |
2202 | (when (ert--ewoc-entry-hidden-p entry) | |
2203 | (setf (ert--ewoc-entry-hidden-p entry) nil) | |
2204 | (ewoc-invalidate ewoc node)) | |
2205 | (ewoc-goto-node ewoc node))) | |
2206 | (t | |
2207 | (goto-char progress-bar-begin))))) | |
2208 | ||
2209 | (defun ert-test-at-point () | |
2210 | "Return the name of the test at point as a symbol, or nil if none." | |
2211 | (or (and (eql major-mode 'ert-results-mode) | |
2212 | (let ((test (ert--results-test-at-point-no-redefinition))) | |
2213 | (and test (ert-test-name test)))) | |
2214 | (let* ((thing (thing-at-point 'symbol)) | |
2215 | (sym (intern-soft thing))) | |
2216 | (and (ert-test-boundp sym) | |
2217 | sym)))) | |
2218 | ||
2219 | (defun ert--results-test-at-point-no-redefinition () | |
2220 | "Return the test at point, or nil. | |
2221 | ||
2222 | To be used in the ERT results buffer." | |
15c9d04e | 2223 | (cl-assert (eql major-mode 'ert-results-mode)) |
d221e780 CO |
2224 | (if (ert--results-test-node-or-null-at-point) |
2225 | (let* ((node (ert--results-test-node-at-point)) | |
2226 | (test (ert--ewoc-entry-test (ewoc-data node)))) | |
2227 | test) | |
2228 | (let ((progress-bar-begin ert--results-progress-bar-button-begin)) | |
2229 | (when (and (<= progress-bar-begin (point)) | |
2230 | (< (point) (button-end (button-at progress-bar-begin)))) | |
2231 | (let* ((test-index (- (point) progress-bar-begin)) | |
2232 | (test (aref (ert--stats-tests ert--results-stats) | |
2233 | test-index))) | |
2234 | test))))) | |
2235 | ||
2236 | (defun ert--results-test-at-point-allow-redefinition () | |
2237 | "Look up the test at point, and check whether it has been redefined. | |
2238 | ||
2239 | To be used in the ERT results buffer. | |
2240 | ||
2241 | Returns a list of two elements: the test (or nil) and a symbol | |
2242 | specifying whether the test has been redefined. | |
2243 | ||
2244 | If a new test has been defined with the same name as the test at | |
2245 | point, replaces the test at point with the new test, and returns | |
2246 | the new test and the symbol `redefined'. | |
2247 | ||
2248 | If the test has been deleted, returns the old test and the symbol | |
2249 | `deleted'. | |
2250 | ||
2251 | If the test is still current, returns the test and the symbol nil. | |
2252 | ||
2253 | If there is no test at point, returns a list with two nils." | |
2254 | (let ((test (ert--results-test-at-point-no-redefinition))) | |
2255 | (cond ((null test) | |
2256 | `(nil nil)) | |
2257 | ((null (ert-test-name test)) | |
2258 | `(,test nil)) | |
2259 | (t | |
2260 | (let* ((name (ert-test-name test)) | |
2261 | (new-test (and (ert-test-boundp name) | |
2262 | (ert-get-test name)))) | |
2263 | (cond ((eql test new-test) | |
2264 | `(,test nil)) | |
2265 | ((null new-test) | |
2266 | `(,test deleted)) | |
2267 | (t | |
2268 | (ert--results-update-after-test-redefinition | |
2269 | (ert--stats-test-pos ert--results-stats test) | |
2270 | new-test) | |
2271 | `(,new-test redefined)))))))) | |
2272 | ||
2273 | (defun ert--results-update-after-test-redefinition (pos new-test) | |
2274 | "Update results buffer after the test at pos POS has been redefined. | |
2275 | ||
2276 | Also updates the stats object. NEW-TEST is the new test | |
2277 | definition." | |
2278 | (let* ((stats ert--results-stats) | |
2279 | (ewoc ert--results-ewoc) | |
2280 | (node (ewoc-nth ewoc pos)) | |
2281 | (entry (ewoc-data node))) | |
2282 | (ert--stats-set-test-and-result stats pos new-test nil) | |
2283 | (setf (ert--ewoc-entry-test entry) new-test | |
2284 | (aref ert--results-progress-bar-string pos) (ert-char-for-test-result | |
2285 | nil t)) | |
2286 | (ewoc-invalidate ewoc node)) | |
2287 | nil) | |
2288 | ||
2289 | (defun ert--button-action-position () | |
2290 | "The buffer position where the last button action was triggered." | |
2291 | (cond ((integerp last-command-event) | |
2292 | (point)) | |
2293 | ((eventp last-command-event) | |
2294 | (posn-point (event-start last-command-event))) | |
15c9d04e | 2295 | (t (cl-assert nil)))) |
d221e780 | 2296 | |
15c9d04e | 2297 | (defun ert--results-progress-bar-button-action (_button) |
d221e780 CO |
2298 | "Jump to details for the test represented by the character clicked in BUTTON." |
2299 | (goto-char (ert--button-action-position)) | |
2300 | (ert-results-jump-between-summary-and-result)) | |
2301 | ||
2302 | (defun ert-results-rerun-all-tests () | |
2303 | "Re-run all tests, using the same selector. | |
2304 | ||
2305 | To be used in the ERT results buffer." | |
2306 | (interactive) | |
15c9d04e | 2307 | (cl-assert (eql major-mode 'ert-results-mode)) |
d221e780 CO |
2308 | (let ((selector (ert--stats-selector ert--results-stats))) |
2309 | (ert-run-tests-interactively selector (buffer-name)))) | |
2310 | ||
2311 | (defun ert-results-rerun-test-at-point () | |
2312 | "Re-run the test at point. | |
2313 | ||
2314 | To be used in the ERT results buffer." | |
2315 | (interactive) | |
15c9d04e | 2316 | (cl-destructuring-bind (test redefinition-state) |
d221e780 CO |
2317 | (ert--results-test-at-point-allow-redefinition) |
2318 | (when (null test) | |
2319 | (error "No test at point")) | |
2320 | (let* ((stats ert--results-stats) | |
2321 | (progress-message (format "Running %stest %S" | |
15c9d04e | 2322 | (cl-ecase redefinition-state |
d221e780 CO |
2323 | ((nil) "") |
2324 | (redefined "new definition of ") | |
2325 | (deleted "deleted ")) | |
2326 | (ert-test-name test)))) | |
2327 | ;; Need to save and restore point manually here: When point is on | |
2328 | ;; the first visible ewoc entry while the header is updated, point | |
2329 | ;; moves to the top of the buffer. This is undesirable, and a | |
2330 | ;; simple `save-excursion' doesn't prevent it. | |
2331 | (let ((point (point))) | |
2332 | (unwind-protect | |
2333 | (unwind-protect | |
2334 | (progn | |
2335 | (message "%s..." progress-message) | |
2336 | (ert-run-or-rerun-test stats test | |
2337 | ert--results-listener)) | |
2338 | (ert--results-update-stats-display ert--results-ewoc stats) | |
2339 | (message "%s...%s" | |
2340 | progress-message | |
2341 | (let ((result (ert-test-most-recent-result test))) | |
2342 | (ert-string-for-test-result | |
2343 | result (ert-test-result-expected-p test result))))) | |
2344 | (goto-char point)))))) | |
2345 | ||
2346 | (defun ert-results-rerun-test-at-point-debugging-errors () | |
2347 | "Re-run the test at point with `ert-debug-on-error' bound to t. | |
2348 | ||
2349 | To be used in the ERT results buffer." | |
2350 | (interactive) | |
2351 | (let ((ert-debug-on-error t)) | |
2352 | (ert-results-rerun-test-at-point))) | |
2353 | ||
2354 | (defun ert-results-pop-to-backtrace-for-test-at-point () | |
2355 | "Display the backtrace for the test at point. | |
2356 | ||
2357 | To be used in the ERT results buffer." | |
2358 | (interactive) | |
2359 | (let* ((test (ert--results-test-at-point-no-redefinition)) | |
2360 | (stats ert--results-stats) | |
2361 | (pos (ert--stats-test-pos stats test)) | |
2362 | (result (aref (ert--stats-test-results stats) pos))) | |
15c9d04e | 2363 | (cl-etypecase result |
d221e780 CO |
2364 | (ert-test-passed (error "Test passed, no backtrace available")) |
2365 | (ert-test-result-with-condition | |
2366 | (let ((backtrace (ert-test-result-with-condition-backtrace result)) | |
2367 | (buffer (get-buffer-create "*ERT Backtrace*"))) | |
2368 | (pop-to-buffer buffer) | |
d221e780 CO |
2369 | (let ((inhibit-read-only t)) |
2370 | (buffer-disable-undo) | |
2371 | (erase-buffer) | |
5da16a86 | 2372 | (ert-simple-view-mode) |
d221e780 CO |
2373 | ;; Use unibyte because `debugger-setup-buffer' also does so. |
2374 | (set-buffer-multibyte nil) | |
2375 | (setq truncate-lines t) | |
2376 | (ert--print-backtrace backtrace) | |
2377 | (debugger-make-xrefs) | |
2378 | (goto-char (point-min)) | |
2379 | (insert "Backtrace for test `") | |
2380 | (ert-insert-test-name-button (ert-test-name test)) | |
5da16a86 | 2381 | (insert "':\n"))))))) |
d221e780 CO |
2382 | |
2383 | (defun ert-results-pop-to-messages-for-test-at-point () | |
2384 | "Display the part of the *Messages* buffer generated during the test at point. | |
2385 | ||
2386 | To be used in the ERT results buffer." | |
2387 | (interactive) | |
2388 | (let* ((test (ert--results-test-at-point-no-redefinition)) | |
2389 | (stats ert--results-stats) | |
2390 | (pos (ert--stats-test-pos stats test)) | |
2391 | (result (aref (ert--stats-test-results stats) pos))) | |
2392 | (let ((buffer (get-buffer-create "*ERT Messages*"))) | |
2393 | (pop-to-buffer buffer) | |
d221e780 CO |
2394 | (let ((inhibit-read-only t)) |
2395 | (buffer-disable-undo) | |
2396 | (erase-buffer) | |
5da16a86 | 2397 | (ert-simple-view-mode) |
d221e780 CO |
2398 | (insert (ert-test-result-messages result)) |
2399 | (goto-char (point-min)) | |
2400 | (insert "Messages for test `") | |
2401 | (ert-insert-test-name-button (ert-test-name test)) | |
5da16a86 | 2402 | (insert "':\n"))))) |
d221e780 CO |
2403 | |
2404 | (defun ert-results-pop-to-should-forms-for-test-at-point () | |
2405 | "Display the list of `should' forms executed during the test at point. | |
2406 | ||
2407 | To be used in the ERT results buffer." | |
2408 | (interactive) | |
2409 | (let* ((test (ert--results-test-at-point-no-redefinition)) | |
2410 | (stats ert--results-stats) | |
2411 | (pos (ert--stats-test-pos stats test)) | |
2412 | (result (aref (ert--stats-test-results stats) pos))) | |
2413 | (let ((buffer (get-buffer-create "*ERT list of should forms*"))) | |
2414 | (pop-to-buffer buffer) | |
d221e780 CO |
2415 | (let ((inhibit-read-only t)) |
2416 | (buffer-disable-undo) | |
2417 | (erase-buffer) | |
5da16a86 | 2418 | (ert-simple-view-mode) |
d221e780 CO |
2419 | (if (null (ert-test-result-should-forms result)) |
2420 | (insert "\n(No should forms during this test.)\n") | |
15c9d04e SM |
2421 | (cl-loop for form-description |
2422 | in (ert-test-result-should-forms result) | |
2423 | for i from 1 do | |
2424 | (insert "\n") | |
2425 | (insert (format "%s: " i)) | |
2426 | (let ((begin (point))) | |
2427 | (ert--pp-with-indentation-and-newline form-description) | |
2428 | (ert--make-xrefs-region begin (point))))) | |
d221e780 CO |
2429 | (goto-char (point-min)) |
2430 | (insert "`should' forms executed during test `") | |
2431 | (ert-insert-test-name-button (ert-test-name test)) | |
2432 | (insert "':\n") | |
2433 | (insert "\n") | |
2434 | (insert (concat "(Values are shallow copies and may have " | |
2435 | "looked different during the test if they\n" | |
2436 | "have been modified destructively.)\n")) | |
5da16a86 | 2437 | (forward-line 1))))) |
d221e780 CO |
2438 | |
2439 | (defun ert-results-toggle-printer-limits-for-test-at-point () | |
2440 | "Toggle how much of the condition to print for the test at point. | |
2441 | ||
2442 | To be used in the ERT results buffer." | |
2443 | (interactive) | |
2444 | (let* ((ewoc ert--results-ewoc) | |
2445 | (node (ert--results-test-node-at-point)) | |
2446 | (entry (ewoc-data node))) | |
2447 | (setf (ert--ewoc-entry-extended-printer-limits-p entry) | |
2448 | (not (ert--ewoc-entry-extended-printer-limits-p entry))) | |
2449 | (ewoc-invalidate ewoc node))) | |
2450 | ||
2451 | (defun ert-results-pop-to-timings () | |
2452 | "Display test timings for the last run. | |
2453 | ||
2454 | To be used in the ERT results buffer." | |
2455 | (interactive) | |
2456 | (let* ((stats ert--results-stats) | |
d221e780 | 2457 | (buffer (get-buffer-create "*ERT timings*")) |
15c9d04e SM |
2458 | (data (cl-loop for test across (ert--stats-tests stats) |
2459 | for start-time across (ert--stats-test-start-times | |
2460 | stats) | |
2461 | for end-time across (ert--stats-test-end-times stats) | |
2462 | collect (list test | |
2463 | (float-time (subtract-time | |
2464 | end-time start-time)))))) | |
d221e780 | 2465 | (setq data (sort data (lambda (a b) |
15c9d04e | 2466 | (> (cl-second a) (cl-second b))))) |
d221e780 | 2467 | (pop-to-buffer buffer) |
d221e780 CO |
2468 | (let ((inhibit-read-only t)) |
2469 | (buffer-disable-undo) | |
2470 | (erase-buffer) | |
5da16a86 | 2471 | (ert-simple-view-mode) |
d221e780 CO |
2472 | (if (null data) |
2473 | (insert "(No data)\n") | |
2474 | (insert (format "%-3s %8s %8s\n" "" "time" "cumul")) | |
15c9d04e SM |
2475 | (cl-loop for (test time) in data |
2476 | for cumul-time = time then (+ cumul-time time) | |
2477 | for i from 1 do | |
2478 | (progn | |
2479 | (insert (format "%3s: %8.3f %8.3f " i time cumul-time)) | |
2480 | (ert-insert-test-name-button (ert-test-name test)) | |
2481 | (insert "\n")))) | |
d221e780 CO |
2482 | (goto-char (point-min)) |
2483 | (insert "Tests by run time (seconds):\n\n") | |
5da16a86 | 2484 | (forward-line 1)))) |
d221e780 CO |
2485 | |
2486 | ;;;###autoload | |
2487 | (defun ert-describe-test (test-or-test-name) | |
2488 | "Display the documentation for TEST-OR-TEST-NAME (a symbol or ert-test)." | |
2489 | (interactive (list (ert-read-test-name-at-point "Describe test"))) | |
2490 | (when (< emacs-major-version 24) | |
2491 | (error "Requires Emacs 24")) | |
2492 | (let (test-name | |
2493 | test-definition) | |
15c9d04e | 2494 | (cl-etypecase test-or-test-name |
d221e780 CO |
2495 | (symbol (setq test-name test-or-test-name |
2496 | test-definition (ert-get-test test-or-test-name))) | |
2497 | (ert-test (setq test-name (ert-test-name test-or-test-name) | |
2498 | test-definition test-or-test-name))) | |
2499 | (help-setup-xref (list #'ert-describe-test test-or-test-name) | |
2500 | (called-interactively-p 'interactive)) | |
2501 | (save-excursion | |
2502 | (with-help-window (help-buffer) | |
2503 | (with-current-buffer (help-buffer) | |
2504 | (insert (if test-name (format "%S" test-name) "<anonymous test>")) | |
2505 | (insert " is a test") | |
2506 | (let ((file-name (and test-name | |
2507 | (symbol-file test-name 'ert-deftest)))) | |
2508 | (when file-name | |
2509 | (insert " defined in `" (file-name-nondirectory file-name) "'") | |
2510 | (save-excursion | |
2511 | (re-search-backward "`\\([^`']+\\)'" nil t) | |
2512 | (help-xref-button 1 'help-function-def test-name file-name))) | |
2513 | (insert ".") | |
2514 | (fill-region-as-paragraph (point-min) (point)) | |
2515 | (insert "\n\n") | |
2516 | (unless (and (ert-test-boundp test-name) | |
2517 | (eql (ert-get-test test-name) test-definition)) | |
2518 | (let ((begin (point))) | |
2519 | (insert "Note: This test has been redefined or deleted, " | |
2520 | "this documentation refers to an old definition.") | |
2521 | (fill-region-as-paragraph begin (point))) | |
2522 | (insert "\n\n")) | |
2523 | (insert (or (ert-test-documentation test-definition) | |
2524 | "It is not documented.") | |
2525 | "\n"))))))) | |
2526 | ||
2527 | (defun ert-results-describe-test-at-point () | |
2528 | "Display the documentation of the test at point. | |
2529 | ||
2530 | To be used in the ERT results buffer." | |
2531 | (interactive) | |
2532 | (ert-describe-test (ert--results-test-at-point-no-redefinition))) | |
2533 | ||
2534 | ||
2535 | ;;; Actions on load/unload. | |
2536 | ||
2537 | (add-to-list 'find-function-regexp-alist '(ert-deftest . ert--find-test-regexp)) | |
2538 | (add-to-list 'minor-mode-alist '(ert--current-run-stats | |
2539 | (:eval | |
2540 | (ert--tests-running-mode-line-indicator)))) | |
2541 | (add-to-list 'emacs-lisp-mode-hook 'ert--activate-font-lock-keywords) | |
2542 | ||
2543 | (defun ert--unload-function () | |
2544 | "Unload function to undo the side-effects of loading ert.el." | |
2545 | (ert--remove-from-list 'find-function-regexp-alist 'ert-deftest :key #'car) | |
2546 | (ert--remove-from-list 'minor-mode-alist 'ert--current-run-stats :key #'car) | |
2547 | (ert--remove-from-list 'emacs-lisp-mode-hook | |
2548 | 'ert--activate-font-lock-keywords) | |
2549 | nil) | |
2550 | ||
2551 | (defvar ert-unload-hook '()) | |
2552 | (add-hook 'ert-unload-hook 'ert--unload-function) | |
2553 | ||
2554 | ||
2555 | (provide 'ert) | |
2556 | ||
2557 | ;;; ert.el ends here |