1 ;;; flycheck-ert.el --- Flycheck: ERT extensions -*- lexical-binding: t; -*-
3 ;; Copyright (C) 2017-2018 Flycheck contributors
4 ;; Copyright (C) 2013-2016 Sebastian Wiesner and Flycheck contributors
6 ;; Author: Sebastian Wiesner <swiesner@lunaryorn.com>
7 ;; Maintainer: Clément Pit-Claudel <clement.pitclaudel@live.com>
8 ;; fmdkdd <fmdkdd@gmail.com>
9 ;; URL: https://github.com/flycheck/flycheck
11 ;; This file is not part of GNU Emacs.
13 ;; This program is free software; you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published by
15 ;; the Free Software Foundation, either version 3 of the License, or
16 ;; (at your option) any later version.
18 ;; This program is distributed in the hope that it will be useful,
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 ;; GNU General Public License for more details.
23 ;; You should have received a copy of the GNU General Public License
24 ;; along with this program. If not, see <http://www.gnu.org/licenses/>.
28 ;; Unit testing library for Flycheck, the modern on-the-fly syntax checking
29 ;; extension for GNU Emacs.
31 ;; Provide various utility functions and unit test helpers to test Flycheck and
32 ;; Flycheck extensions.
38 (require 'macroexp) ; For macro utilities
44 ;; Provide `ert-skip' and friends for Emacs 24.3
45 (defconst flycheck-ert-ert-can-skip (fboundp 'ert-skip)
46 "Whether ERT supports test skipping.")
48 (unless (fboundp 'define-error)
49 ;; from Emacs `subr.el'
50 (defun define-error (name message &optional parent)
51 "Define NAME as a new error signal.
52 MESSAGE is a string that will be output to the echo area if such an error
53 is signaled without being caught by a `condition-case'.
54 PARENT is either a signal or a list of signals from which it inherits.
56 (unless parent (setq parent 'error))
63 (or (get parent 'error-conditions)
64 (error "Unknown signal `%s'" parent))))
66 (cons parent (get parent 'error-conditions)))))
67 (put name 'error-conditions
68 (delete-dups (copy-sequence (cons name conditions))))
69 (when message (put name 'error-message message)))))
71 (unless flycheck-ert-ert-can-skip
74 (define-error 'flycheck-ert-skipped "Test skipped")
76 (defun ert-skip (data)
77 (signal 'flycheck-ert-skipped data))
79 (defmacro skip-unless (form)
80 `(unless (ignore-errors ,form)
81 (signal 'flycheck-ert-skipped ',form)))
83 (defun ert-test-skipped-p (result)
84 (and (ert-test-failed-p result)
85 (eq (car (ert-test-failed-condition result))
86 'flycheck-ert-skipped)))))
89 ;;; Internal variables
91 (defvar flycheck-ert--resource-directory nil
92 "The directory to get resources from in this test suite.")
95 ;;; Resource management macros
97 (defmacro flycheck-ert-with-temp-buffer (&rest body)
98 "Eval BODY within a temporary buffer.
100 Like `with-temp-buffer', but resets the modification state of the
101 temporary buffer to make sure that it is properly killed even if
102 it has a backing file and is modified."
106 ,(macroexp-progn body)
107 ;; Reset modification state of the buffer, and unlink it from its backing
108 ;; file, if any, because Emacs refuses to kill modified buffers with
109 ;; backing files, even if they are temporary.
110 (set-buffer-modified-p nil)
111 (set-visited-file-name nil 'no-query))))
113 (defmacro flycheck-ert-with-file-buffer (file-name &rest body)
114 "Create a buffer from FILE-NAME and eval BODY.
116 BODY is evaluated with `current-buffer' being a buffer with the
119 `(let ((file-name ,file-name))
120 (unless (file-exists-p file-name)
121 (error "%s does not exist" file-name))
122 (flycheck-ert-with-temp-buffer
123 (insert-file-contents file-name 'visit)
124 (set-visited-file-name file-name 'no-query)
125 (cd (file-name-directory file-name))
126 ;; Mark the buffer as not modified, because we just loaded the file up to
128 (set-buffer-modified-p nil)
131 (defmacro flycheck-ert-with-help-buffer (&rest body)
132 "Execute BODY and kill the help buffer afterwards.
134 Use this macro to test functions that create a Help buffer."
137 ,(macroexp-progn body)
138 (when (buffer-live-p (get-buffer (help-buffer)))
139 (kill-buffer (help-buffer)))))
141 (defmacro flycheck-ert-with-global-mode (&rest body)
142 "Execute BODY with Global Flycheck Mode enabled.
144 After BODY, restore the old state of Global Flycheck Mode."
146 `(let ((old-state global-flycheck-mode))
149 (global-flycheck-mode 1)
151 (global-flycheck-mode (if old-state 1 -1)))))
153 (defmacro flycheck-ert-with-env (env &rest body)
154 "Add ENV to `process-environment' in BODY.
156 Execute BODY with a `process-environment' which contains all
157 variables from ENV added.
159 ENV is an alist, where each cons cell `(VAR . VALUE)' is a
160 environment variable VAR to be added to `process-environment'
163 `(let ((process-environment (copy-sequence process-environment)))
164 (pcase-dolist (`(,var . ,value) ,env)
170 (defun flycheck-ert-resource-filename (resource-file)
171 "Determine the absolute file name of a RESOURCE-FILE.
173 Relative file names are expanded against
174 `flycheck-ert--resource-directory'."
175 (expand-file-name resource-file flycheck-ert--resource-directory))
177 (defmacro flycheck-ert-with-resource-buffer (resource-file &rest body)
178 "Create a temp buffer from a RESOURCE-FILE and execute BODY.
180 The absolute file name of RESOURCE-FILE is determined with
181 `flycheck-ert-resource-filename'."
183 `(flycheck-ert-with-file-buffer
184 (flycheck-ert-resource-filename ,resource-file)
188 ;;; Test suite initialization
190 (defun flycheck-ert-initialize (resource-dir)
191 "Initialize a test suite with RESOURCE-DIR.
193 RESOURCE-DIR is the directory, `flycheck-ert-resource-filename'
194 should use to lookup resource files."
195 (when flycheck-ert--resource-directory
196 (error "Test suite already initialized"))
197 (let ((tests (ert-select-tests t t)))
200 (error "No tests defined. \
201 Call `flycheck-ert-initialize' after defining all tests!"))
203 (setq flycheck-ert--resource-directory resource-dir)
205 ;; Emacs 24.3 don't support skipped tests, so we add poor man's test
206 ;; skipping: We mark skipped tests as expected failures by adjusting the
207 ;; expected result of all test cases. Not particularly pretty, but works :)
208 (unless flycheck-ert-ert-can-skip
210 (let ((result (ert-test-expected-result-type test)))
211 (setf (ert-test-expected-result-type test)
212 `(or ,result (satisfies ert-test-skipped-p))))))))
215 ;;; Test case definitions
216 (defmacro flycheck-ert-def-checker-test (checker language name
218 "Define a test case for a syntax CHECKER for LANGUAGE.
220 CHECKER is a symbol or a list of symbols denoting syntax checkers
221 being tested by the test. The test case is skipped, if any of
222 these checkers cannot be used. LANGUAGE is a symbol or a list of
223 symbols denoting the programming languages supported by the
224 syntax checkers. This is currently only used for tagging the
227 NAME is a symbol denoting the local name of the test. The test
228 itself is ultimately named
229 `flycheck-define-checker/CHECKER/NAME'. If CHECKER is a list,
230 the first checker in the list is used for naming the test.
232 Optionally, the keyword arguments `:tags' and `:expected-result'
233 may be given. They have the same meaning as in `ert-deftest.',
234 and are added to the tags and result expectations set up by this
237 The remaining forms KEYS-AND-BODY denote the body of the test
238 case, including assertions and setup code."
241 (error "No syntax checkers specified"))
243 (error "No languages specified"))
244 (let* ((checkers (if (symbolp checker) (list checker) checker))
245 (checker (car checkers))
246 (languages (if (symbolp language) (list language) language))
247 (language-tags (mapcar (lambda (l) (intern (format "language-%s" l)))
249 (checker-tags (mapcar (lambda (c) (intern (format "checker-%s" c)))
251 (local-name (or name 'default))
252 (full-name (intern (format "flycheck-define-checker/%s/%s"
253 checker local-name)))
254 (keys-and-body (ert--parse-keys-and-body keys-and-body))
255 (body (cadr keys-and-body))
256 (keys (car keys-and-body))
257 (default-tags '(syntax-checker external-tool)))
258 `(ert-deftest ,full-name ()
259 :expected-result ,(or (plist-get keys :expected-result) :passed)
260 :tags (append ',(append default-tags language-tags checker-tags)
261 ,(plist-get keys :tags))
262 ,@(mapcar (lambda (c)
264 ;; Ignore non-command checkers
265 (or (not (flycheck-checker-get ',c 'command))
266 (executable-find (flycheck-checker-executable ',c)))))
271 ;;; Test case results
273 (defun flycheck-ert-syntax-check-timed-out-p (result)
274 "Whether RESULT denotes a timed-out test.
276 RESULT is an ERT test result object."
277 (and (ert-test-failed-p result)
278 (eq (car (ert-test-failed-condition result))
279 'flycheck-ert-syntax-check-timed-out)))
282 ;;; Syntax checking in tests
284 (defvar-local flycheck-ert-syntax-checker-finished nil
285 "Non-nil if the current checker has finished.")
287 (add-hook 'flycheck-after-syntax-check-hook
288 (lambda () (setq flycheck-ert-syntax-checker-finished t)))
290 (defconst flycheck-ert-checker-wait-time 10
291 "Time to wait until a checker is finished in seconds.
293 After this time has elapsed, the checker is considered to have
294 failed, and the test aborted with failure.")
296 (define-error 'flycheck-ert-syntax-check-timed-out "Syntax check timed out.")
298 (defun flycheck-ert-wait-for-syntax-checker ()
299 "Wait until the syntax check in the current buffer is finished."
300 (let ((starttime (float-time)))
301 (while (and (not flycheck-ert-syntax-checker-finished)
302 (< (- (float-time) starttime) flycheck-ert-checker-wait-time))
304 (unless (< (- (float-time) starttime) flycheck-ert-checker-wait-time)
306 (signal 'flycheck-ert-syntax-check-timed-out nil)))
307 (setq flycheck-ert-syntax-checker-finished nil))
309 (defun flycheck-ert-buffer-sync ()
310 "Like `flycheck-buffer', but synchronously."
311 (setq flycheck-ert-syntax-checker-finished nil)
312 (should (not (flycheck-running-p)))
313 (flycheck-mode) ; This will only start a deferred check,
314 (flycheck-buffer) ; so we need an explicit manual check
315 ;; After starting the check, the checker should either be running now, or
316 ;; already be finished (if it was fast).
317 (should (or flycheck-current-syntax-check
318 flycheck-ert-syntax-checker-finished))
319 ;; Also there should be no deferred check pending anymore
320 (should-not (flycheck-deferred-check-p))
321 (flycheck-ert-wait-for-syntax-checker))
323 (defun flycheck-ert-ensure-clear ()
324 "Clear the current buffer.
326 Raise an assertion error if the buffer is not clear afterwards."
328 (should (not flycheck-current-errors))
329 (should (not (-any? (lambda (ov) (overlay-get ov 'flycheck-overlay))
330 (overlays-in (point-min) (point-max))))))
335 (defun flycheck-error-without-group (err)
336 "Return a copy ERR with the `group' property set to nil."
337 (let ((copy (copy-flycheck-error err)))
338 (setf (flycheck-error-group copy) nil)
341 (defun flycheck-ert-should-overlay (error)
342 "Test that ERROR has a proper overlay in the current buffer.
344 ERROR is a Flycheck error object."
345 (let* ((overlay (-first (lambda (ov)
346 (equal (flycheck-error-without-group
347 (overlay-get ov 'flycheck-error))
348 (flycheck-error-without-group error)))
349 (flycheck-overlays-in 0 (+ 1 (buffer-size)))))
351 ;; Overlays of errors from other files are on the first line
352 (if (flycheck-relevant-error-other-file-p error)
354 (save-excursion (goto-char (point-min)) (point-at-eol)))
355 (flycheck-error-region-for-mode error 'symbols)))
356 (level (flycheck-error-level error))
357 (category (flycheck-error-level-overlay-category level))
358 (face (get category 'face))
359 (fringe-bitmap (flycheck-error-level-fringe-bitmap level))
360 (fringe-face (flycheck-error-level-fringe-face level))
361 (fringe-icon (list 'left-fringe fringe-bitmap fringe-face)))
363 (should (overlay-get overlay 'flycheck-overlay))
364 (should (= (overlay-start overlay) (car region)))
365 (should (= (overlay-end overlay) (cdr region)))
366 (should (eq (overlay-get overlay 'face) face))
367 (should (equal (get-char-property 0 'display
368 (overlay-get overlay 'before-string))
370 (should (eq (overlay-get overlay 'category) category))
371 (should (equal (flycheck-error-without-group (overlay-get overlay
373 (flycheck-error-without-group error)))))
375 (defun flycheck-ert-should-errors (&rest errors)
376 "Test that the current buffers has ERRORS.
378 ERRORS is a list of errors expected to be present in the current
379 buffer. Each error is given as a list of arguments to
380 `flycheck-error-new-at'.
382 If ERRORS are omitted, test that there are no errors at all in
385 With ERRORS, test that each error in ERRORS is present in the
386 current buffer, and that the number of errors in the current
387 buffer is equal to the number of given ERRORS. In other words,
388 check that the buffer has all ERRORS, and no other errors."
389 (let ((expected (mapcar (apply-partially #'apply #'flycheck-error-new-at)
391 (should (equal (mapcar #'flycheck-error-without-group expected)
392 (mapcar #'flycheck-error-without-group
393 flycheck-current-errors)))
394 ;; Check that related errors are the same
395 (cl-mapcar (lambda (err1 err2)
396 (should (equal (mapcar #'flycheck-error-without-group
397 (flycheck-related-errors err1 expected))
398 (mapcar #'flycheck-error-without-group
399 (flycheck-related-errors err2)))))
400 expected flycheck-current-errors)
401 (mapc #'flycheck-ert-should-overlay expected))
402 (should (= (length errors)
403 (length (flycheck-overlays-in (point-min) (point-max))))))
405 (define-error 'flycheck-ert-suspicious-checker "Suspicious state from checker")
407 (defun flycheck-ert-should-syntax-check (resource-file modes &rest errors)
408 "Test a syntax check in RESOURCE-FILE with MODES.
410 RESOURCE-FILE is the file to check. MODES is a single major mode
411 symbol or a list thereof, specifying the major modes to syntax
412 check with. If more than one major mode is specified, the test
413 is run for each mode separately, so if you give three major
414 modes, the entire test will run three times. ERRORS is the list
415 of expected errors, as in `flycheck-ert-should-errors'. If
416 omitted, the syntax check must not emit any errors. The errors
417 are cleared after each test.
419 The syntax checker is selected via standard syntax checker
420 selection. To test a specific checker, you need to set
421 `flycheck-checker' or `flycheck-disabled-checkers' accordingly
422 before using this predicate, depending on whether you want to use
423 manual or automatic checker selection.
425 During the syntax check, configuration files of syntax checkers
426 are also searched in the `config-files' sub-directory of the
428 (when (symbolp modes)
429 (setq modes (list modes)))
431 (unless (fboundp mode)
432 (ert-skip (format "%S missing" mode)))
433 (flycheck-ert-with-resource-buffer resource-file
435 ;; Load safe file-local variables because some tests depend on them
436 (let ((enable-local-variables :safe)
437 ;; Disable all hooks at this place, to prevent 3rd party packages
439 (hack-local-variables-hook))
440 (hack-local-variables))
441 ;; Configure config file locating for unit tests
442 (let ((process-hook-called 0))
443 (add-hook 'flycheck-process-error-functions
445 (setq process-hook-called (1+ process-hook-called))
448 (add-hook 'flycheck-status-changed-functions
450 (when (eq status 'suspicious)
451 (signal 'flycheck-ert-suspicious-checker nil))))
452 (flycheck-ert-buffer-sync)
453 (apply #'flycheck-ert-should-errors errors)
454 (should (= process-hook-called (length errors))))
455 (flycheck-ert-ensure-clear))))
457 (defun flycheck-ert-at-nth-error (n)
458 "Determine whether point is at the N'th Flycheck error.
460 Return non-nil if the point is at the N'th Flycheck error in the
461 current buffer. Otherwise return nil."
462 (let* ((error (nth (1- n) flycheck-current-errors))
463 (mode flycheck-highlighting-mode)
464 (region (flycheck-error-region-for-mode error mode)))
465 (and (member error (flycheck-overlay-errors-at (point)))
466 (= (point) (car region)))))
468 (defun flycheck-ert-explain--at-nth-error (n)
469 "Explain a failed at-nth-error predicate at N."
470 (let ((errors (flycheck-overlay-errors-at (point))))
472 (format "Expected to be at error %s, but no error at point %s"
474 (let ((pos (cl-position (car errors) flycheck-current-errors)))
475 (format "Expected to be at error %s, but point %s is at error %s"
476 n (point) (1+ pos))))))
478 (put 'flycheck-ert-at-nth-error 'ert-explainer
479 'flycheck-ert-explain--at-nth-error)
481 (provide 'flycheck-ert)
483 ;;; flycheck-ert.el ends here