testing/README

   1 # -*- mode:org -*-
   2 #+TITLE: Org-mode Testing
   3 #+PROPERTY: results silent
   4
   5 * Dependencies
   6
   7 The only dependency is [[http://www.emacswiki.org/emacs/ErtTestLibrary][ERT]] the Emacs testing library which ships with
   8 Emacs24.  If you are running an older version of Emacs and don't
   9 already have ERT installed it can be installed from its old [[https://github.com/ohler/ert][git
  10 repository]].
  11
  12 * Non-interactive batch testing from the command line
  13
  14 The simplest way to run the Org-mode test suite is from the command
  15 line with the following invocation.  Note that the paths below are
  16 relative to the base of the Org-mode directory.
  17
  18 #+BEGIN_SRC sh :dir (expand-file-name "..")
  19   # For Emacs earlier than 24, add -L /path/to/ert
  20   emacs -Q --batch \
  21         -L lisp/ -L testing/ -L testing/lisp -l lisp/org.el \
  22         -l lisp/org-id.el -l testing/org-test.el \
  23         --eval "(progn (org-reload) (setq org-confirm-babel-evaluate nil))" \
  24         -f org-test-run-batch-tests
  25 #+END_SRC
  26
  27 The options in the above command are explained below.
  28
  29 | -Q      | ignores any personal configuration ensuring a vanilla Emacs instance is used |
  30 | --batch | runs Emacs in "batch" mode with no gui and termination after execution       |
  31 | -l      | loads Org-mode and the org mode test suite defined in testing/org-test.el    |
  32 | --eval  | reloads Org-mode and allows evaluation of code blocks by the tests           |
  33 | -f      | actually runs the tests using the `org-test-run-batch-tests' function        |
  34
  35 * Interactive testing from within Emacs
  36
  37 To run the Org-mode test suite from a current Emacs instance simply
  38 load and run the test suite with the following commands.
  39
  40 1) First load the test suite.
  41    #+BEGIN_SRC emacs-lisp :var here=(buffer-file-name)
  42      (add-to-list 'load-path (file-name-directory here))
  43      (require 'org-test)
  44    #+END_SRC
  45
  46 2) Then run the test suite.
  47    #+BEGIN_SRC emacs-lisp
  48      (org-test-run-all-tests)
  49    #+END_SRC
  50
  51 * Troubleshooting
  52
  53 - If the value of the =org-babel-no-eval-on-ctrl-c-ctrl-c= is non-nil
  54   then it will result in some test failure, as there are tests which
  55   rely on this behavior.