test/README

   1 Copyright (C) 2008-2018 Free Software Foundation, Inc.
   2 See the end of the file for license conditions.
   3
   4 This directory contains files intended to test various aspects of
   5 Emacs's functionality.  Please help add tests!
   6
   7 See the file file-organization.org for the details of the directory
   8 structure and file-naming conventions.
   9
  10 Emacs uses ERT, Emacs Lisp Regression Testing, for testing.  See (info
  11 "(ert)") or https://www.gnu.org/software/emacs/manual/html_node/ert/
  12 for more information on writing and running tests.
  13
  14 Tests could be tagged by the developer.  In this test directory, the
  15 following tags are recognized:
  16
  17 * :expensive-test
  18   The test needs a serious amount of time to run.  It is not intended
  19   to run on a regular basis by users.  Instead, it runs on demand
  20   only, or during regression tests.
  21
  22 * :unstable
  23   The test is under development.  It shall run on demand only.
  24
  25 The Makefile in this directory supports the following targets:
  26
  27 * make check
  28   Run all tests as defined in the directory.  Expensive and unstable
  29   tests are suppressed.  The result of the tests for <filename>.el is
  30   stored in <filename>.log.
  31
  32 * make check-maybe
  33   Like "make check", but run only the tests for files which have
  34   unresolved prerequisites.
  35
  36 * make check-expensive
  37   Like "make check", but run also the tests marked as expensive.
  38
  39 * make check-all
  40   Like "make check", but run all tests.
  41
  42 * make <filename>  or  make <filename>.log
  43   Run all tests declared in <filename>.el.  This includes expensive
  44   tests.  In the former case the output is shown on the terminal, in
  45   the latter case the output is written to <filename>.log.
  46
  47 ERT offers selectors, which make it possible to filter out which test
  48 cases shall run.  The make variable $(SELECTOR) gives you a simple
  49 mean to use your own selectors.  The ERT manual describes how
  50 selectors are constructed, see (info "(ert)Test Selectors") or
  51 https://www.gnu.org/software/emacs/manual/html_node/ert/Test-Selectors.html
  52
  53 You could use predefined selectors of the Makefile.  "make <filename>
  54 SELECTOR='$(SELECTOR_DEFAULT)'" runs all tests for <filename>.el
  55 except the tests tagged as expensive or unstable.
  56
  57 If your test file contains the tests "test-foo", "test2-foo" and
  58 "test-foo-remote", and you want to run only the former two tests, you
  59 could use a selector regexp: "make <filename> SELECTOR='\"foo$$\"'".
  60
  61 Note that although the test files are always compiled (unless they set
  62 no-byte-compile), the source files will be run when expensive or
  63 unstable tests are involved, to give nicer backtraces.  To run the
  64 compiled version of a test use
  65
  66     make TEST_LOAD_EL=no ...
  67
  68 Some tests might take long time to run.  In order to summarize the
  69 <nn> tests with the longest duration, call
  70
  71     make SUMMARIZE_TESTS=<nn> ...
  72
  73 \f
  74 (Also, see etc/compilation.txt for compilation mode font lock tests.)
  75
  76 \f
  77 This file is part of GNU Emacs.
  78
  79 GNU Emacs is free software: you can redistribute it and/or modify
  80 it under the terms of the GNU General Public License as published by
  81 the Free Software Foundation, either version 3 of the License, or
  82 (at your option) any later version.
  83
  84 GNU Emacs is distributed in the hope that it will be useful,
  85 but WITHOUT ANY WARRANTY; without even the implied warranty of
  86 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  87 GNU General Public License for more details.
  88
  89 You should have received a copy of the GNU General Public License
  90 along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.