test/file-organization.org

   1 #+TITLE: The Location of Emacs-Lisp Tests
   2
   3
   4
   5 * The Main Emacs Repository
   6
   7 The Emacs repository contains a very large number of Emacs-Lisp files, many of
   8 which pre-date both formal package support for Emacs and automated unit
   9 testing.
  10
  11 All paths are relative to the Emacs root directory.
  12
  13 ** Source
  14
  15 Lisp files are stored in the ~lisp~ directory or its sub-directories.
  16 Sub-directories are in many cases themed after packages (~gnus~, ~org~,
  17 ~calc~), related functionality (~net~, ~emacs-lisp~, ~progmodes~) or status
  18 (~obsolete~).
  19
  20 C source is stored in the ~src~ directory, which is flat.
  21
  22 ** Test Files
  23
  24 Automated tests should be stored in the ~test/lisp~ directory for
  25 tests of functionality implemented in Lisp, and in the ~test/src~
  26 directory for functionality implemented in C.  Tests should reflect
  27 the directory structure of the source tree; so tests for files in the
  28 ~lisp/emacs-lisp~ source directory should reside in the
  29 ~test/lisp/emacs-lisp~ directory.
  30
  31 Tests should normally reside in a file with ~-tests.el~ added to the
  32 base-name of the tested source file; hence ~ert.el~ is tested in
  33 ~ert-tests.el~, and ~pcase.el~ is tested in ~pcase-tests.el~.  As n
  34 exception, tests for a single feature may be placed into multiple
  35 files of any name which are themselves placed in a directory named
  36 after the feature with ~-tests~ appended, such as
  37 ~/test/lisp/emacs-lisp/eieio-tests~
  38
  39 Similarly, features implemented in C should reside in ~/test/src~ and
  40 be named after the C file with ~-tests.el~ added to the base-name of
  41 the tested source file.  Thus, tests for ~src/fileio.c~ should be in
  42 ~test/src/fileio-tests.el~.
  43
  44 There are also some test materials that cannot be run automatically
  45 (i.e. via ert).  These should be placed in ~/test/manual~; they are
  46 not run by the "make check" command and its derivatives.
  47
  48 ** Resource Files
  49
  50 Resource files for tests (containing test data) should reside in a
  51 directory named after the feature with a ~-resources~ suffix, and
  52 located in the same directory as the feature.  Hence, the lisp file
  53 ~lisp/progmodes/flymake.el~, with tests in
  54 ~test/lisp/progmodes/flymake-tests.el~, should have resources in a
  55 directory called ~test/lisp/progmodes/flymake-resources~.
  56
  57 No guidance is given for the organization of resource files inside the
  58 ~-resource~ directory; files can be organized at the author's
  59 discretion.