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/automated/lisp~ directory. Tests
  25 should reflect the directory structure of the source tree; so tests for files
  26 in the ~emacs-lisp~ source directory should reside in the
  27 ~test/lisp/emacs-lisp~ directory.
  28
  29 Tests should normally reside in a file with ~-tests~ added to the name of
  30 the tested source file; hence ~ert.el~ is tested in ~ert-tests.el~, or
  31 ~pcase.el~ is tested in ~pcase-tests.el~. Exceptionally, tests for a
  32 single feature may be placed into multiple files of any name which are
  33 themselves placed in a directory named after the feature with ~-tests~
  34 appended, such as ~/test/lisp/emacs-lisp/eieio-tests~
  35
  36 Where features of the C source are tested using Emacs-Lisp test files, these
  37 should reside in ~/test/src~ and be named after the C file.
  38
  39 A few test suites which predate this scheme and do not fit cleanly
  40 into it are placed in ~/test/lisp/legacy~.
  41
  42 There are also some test materials that cannot be run automatically
  43 (i.e. via ert). These should be placed in ~/test/manual~
  44
  45 ** Resource Files
  46
  47 Resource files for tests (containing test data) should reside in a directory
  48 named after the feature with a ~-resources~ suffix, and located in the same
  49 directory as the feature. Hence, the lisp file ~flymake.el~ should have test
  50 files in ~/test/automated/lisp/progmodes/flymake-tests.el~ should reside in a
  51 directory called ~/test/automated/lisp/progmodes/flymake-resources~.
  52
  53 No guidance is given for the organization of resource files inside the
  54 ~-resource~ directory; files can be organized at the author's discretion.