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
  16   emacs -Q --batch -l lisp/org.el -l testing/org-test.el \
  17       --eval "(progn (org-reload) (setq org-confirm-babel-evaluate nil))" \
  18       -f org-test-run-batch-tests
  19 #+END_SRC
  20
  21 The options in the above command are explained below.
  22 | -Q      | ignores any personal configuration ensuring a vanilla Emacs instance is used |
  23 | --batch | runs Emacs in "batch" mode with no gui and termination after execution       |
  24 | -l      | loads Org-mode and the org mode test suite defined in testing/org-test.el    |
  25 | --eval  | reloads Org-mode and allows evaluation of code blocks by the tests           |
  26 | -f      | actually runs the tests using the `org-test-run-batch-tests' function        |
  27
  28 * interactive testing from within Emacs
  29 To run the Org-mode test suite from a current Emacs instance simply
  30 load and run the test suite with the following commands.
  31
  32 1) First load the test suite.
  33    #+BEGIN_SRC emacs-lisp :var here=(buffer-file-name)
  34      (add-to-list 'load-path (file-name-directory here))
  35      (require 'org-test)
  36    #+END_SRC
  37
  38 2) Then run the test suite.
  39    #+BEGIN_SRC emacs-lisp
  40      (org-test-run-all-tests)
  41    #+END_SRC
  42 * troubleshooting
  43 - If the value of the =org-babel-no-eval-on-ctrl-c-ctrl-c= is non-nil
  44   then it will result in some test failure, as there are tests which
  45   rely on this behavior.