test/README

   1 Copyright (C) 2008-2024 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 For tests in the manual/ subdirectory, look there for separate README
  11 files, or look for instructions in the test files themselves.
  12
  13 Emacs uses ERT, Emacs Lisp Regression Testing, for testing.  See (info
  14 "(ert)") or https://www.gnu.org/software/emacs/manual/html_node/ert/
  15 for more information on writing and running tests.
  16
  17 Tests could be tagged by the developer.  In this test directory, the
  18 following tags are recognized:
  19
  20 * :expensive-test
  21   The test needs a serious amount of time to run.  It is not intended
  22   to run on a regular basis by users.  Instead, it runs on demand
  23   only, or during regression tests.
  24
  25 * :nativecomp
  26   The test runs only if Emacs is configured with Lisp native compiler
  27   support.
  28
  29 * :unstable
  30   The test is under development.  It shall run on demand only.
  31
  32 The Makefile sets the environment variable $EMACS_TEST_DIRECTORY,
  33 which points to this directory.  This environment variable does not
  34 exist when the tests are run outside make.  The Makefile supports the
  35 following targets:
  36
  37 * make check
  38   Run all tests as defined in the directory.  Expensive and unstable
  39   tests are suppressed.  The result of the tests for <filename>.el is
  40   stored in <filename>.log.
  41
  42 * make check-maybe
  43   Like "make check", but run only the tests for files which have
  44   unresolved prerequisites.
  45
  46 * make check-expensive
  47   Like "make check", but run also the tests marked as expensive.
  48
  49 * make check-all
  50   Like "make check", but run all tests.
  51
  52 * make check-<dirname>
  53   Like "make check", but run only the tests in test/<dirname>/*.el.
  54   <dirname> is a relative directory path, which has replaced "/" by "-",
  55   like in "check-src" or "check-lisp-net".
  56
  57 * make <filename>  -or-  make <filename>.log
  58   Run all tests declared in <filename>.el.  This includes expensive
  59   tests.  In the former case the output is shown on the terminal, in
  60   the latter case the output is written to <filename>.log.
  61
  62 <filename> could be either a relative file name like
  63 "lisp/files-tests", or a package name like "files-tests".
  64
  65 ERT offers selectors, which make it possible to filter out which test
  66 cases shall run.  The make variable $(SELECTOR) gives you a simple
  67 mean to use your own selectors.  The ERT manual describes how
  68 selectors are constructed, see (info "(ert)Test Selectors") or
  69 https://www.gnu.org/software/emacs/manual/html_node/ert/Test-Selectors.html
  70
  71 You could use predefined selectors of the Makefile.  "make <filename>
  72 SELECTOR='$(SELECTOR_DEFAULT)'" runs all tests for <filename>.el
  73 except the tests tagged as expensive or unstable.  Other predefined
  74 selectors are $(SELECTOR_EXPENSIVE) (run all tests except unstable
  75 ones) and $(SELECTOR_ALL) (run all tests).
  76
  77 If your test file contains the tests "test-foo", "test2-foo" and
  78 "test-foo-remote", and you want to run only the former two tests, you
  79 could use a selector regexp (note that the "$" needs to be doubled to
  80 protect against "make" variable expansion):
  81
  82     make <filename> SELECTOR='"foo$$"'
  83
  84 In case you want to use the symbol name of a test as selector, you can
  85 use it directly:
  86
  87     make <filename> SELECTOR='test-foo-remote'
  88
  89 Note that although the test files are always compiled (unless they set
  90 no-byte-compile), the source files will be run when expensive or
  91 unstable tests are involved, to give nicer backtraces.  To run the
  92 compiled version of a test use
  93
  94     make TEST_LOAD_EL=no ...
  95
  96 Some tests might take long time to run.  In order to summarize the
  97 <nn> tests with the longest duration, call
  98
  99     make SUMMARIZE_TESTS=<nn> ...
 100
 101 The backtrace of failing tests are truncated to the default value of
 102 'ert-batch-backtrace-right-margin'.  To see more of the backtrace, use
 103
 104     make TEST_BACKTRACE_LINE_LENGTH=<nn> ...
 105
 106 The tests are run in batch mode by default; sometimes it's useful to
 107 get precisely the same environment but run in interactive mode for
 108 debugging.  To do that, use
 109
 110     make TEST_INTERACTIVE=yes ...
 111
 112 Sometimes, some further settings are needed in order to run the batch
 113 test.  This can be indicated by the $EMACS_EXTRAOPT environment
 114 variable, like
 115
 116     make ... EMACS_EXTRAOPT="--eval '(setopt ert-batch-print-length nil ert-batch-print-level nil)'"
 117
 118 By default, ERT test failure summaries are quite brief in batch
 119 mode--only the names of the failed tests are listed.  If the
 120 $EMACS_TEST_VERBOSE environment variable is set and non-empty, the
 121 failure summaries will also include the data from the failing test.
 122
 123 If the $EMACS_TEST_JUNIT_REPORT environment variable is set to a file
 124 name, a JUnit test report is generated under this name.
 125
 126 Some of the tests require a remote temporary directory
 127 (autorevert-tests.el, dnd-tests.el, eglot-tests.el, filenotify-tests.el,
 128 shadowfile-tests.el and tramp-tests.el).  Per default, a mock-up
 129 connection method is used (this might not be possible when running on
 130 MS Windows).  If you want to test a real remote connection, set
 131 $REMOTE_TEMPORARY_FILE_DIRECTORY to a suitable value in order to
 132 overwrite the default value:
 133
 134     env REMOTE_TEMPORARY_FILE_DIRECTORY=/ssh:host:/tmp make ...
 135
 136 \f
 137 There are also continuous integration tests on
 138 <https://hydra.nixos.org/jobset/gnu/emacs-trunk> (see
 139 admin/notes/hydra) and <https://emba.gnu.org/emacs/emacs> (see
 140 admin/notes/emba).  Both environments provide an environment variable,
 141 which could be used to determine, whether the tests run in one of
 142 these test environments.
 143
 144 $EMACS_HYDRA_CI indicates the hydra environment, and $EMACS_EMBA_CI
 145 indicates the emba environment, respectively.
 146
 147 If tests on these premises take too long, and it is needed to create a
 148 core dump for further analysis, the environment variable
 149 $EMACS_TEST_TIMEOUT could set a limit (in seconds) when this shall
 150 happen.
 151
 152 \f
 153 (Also, see etc/compilation.txt for compilation mode font lock tests
 154 and etc/grep.txt for grep mode font lock tests.)
 155
 156 \f
 157 This file is part of GNU Emacs.
 158
 159 GNU Emacs is free software: you can redistribute it and/or modify
 160 it under the terms of the GNU General Public License as published by
 161 the Free Software Foundation, either version 3 of the License, or
 162 (at your option) any later version.
 163
 164 GNU Emacs is distributed in the hope that it will be useful,
 165 but WITHOUT ANY WARRANTY; without even the implied warranty of
 166 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 167 GNU General Public License for more details.
 168
 169 You should have received a copy of the GNU General Public License
 170 along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.