testing/README

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