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 Also note that many of the current tests uses babel evaluation...
  19
  20 #+BEGIN_SRC sh :dir (expand-file-name "..")
  21   # For Emacs earlier than 24, add -L /path/to/ert
  22   emacs -Q --batch \
  23         -L lisp/ -L testing/ -L testing/lisp -l lisp/org.el \
  24         -l lisp/org-id.el -l testing/org-test.el \
  25         --eval "(progn (org-reload) (setq org-confirm-babel-evaluate nil) \
  26         (org-babel-do-load-languages 'org-babel-load-languages \
  27         '((emacs-lisp . t) (shell . t) (org . t))))" \
  28         -f org-test-run-batch-tests
  29 #+END_SRC
  30
  31 The options in the above command are explained below.
  32
  33 | -Q      | ignores any personal configuration ensuring a vanilla Emacs instance is used |
  34 | --batch | runs Emacs in "batch" mode with no gui and termination after execution       |
  35 | -l      | loads Org-mode and the org mode test suite defined in testing/org-test.el    |
  36 | --eval  | reloads Org-mode and allows evaluation of code blocks by the tests           |
  37 | -f      | actually runs the tests using the `org-test-run-batch-tests' function        |
  38
  39 * Trigger testing with 'make test'
  40
  41 Target =test= can be used to trigger a test run.
  42
  43 #+BEGIN_SRC sh :dir (expand-file-name "..")
  44 make test
  45 #+END_SRC
  46
  47 See ../mk/default.mk for details.
  48
  49 * Interactive testing from within Emacs
  50
  51 To run the Org-mode test suite from a current Emacs instance simply
  52 load and run the test suite with the following commands.
  53
  54 1) First load the test suite.
  55    #+BEGIN_SRC emacs-lisp :var here=(buffer-file-name)
  56      (add-to-list 'load-path (file-name-directory here))
  57      (require 'org-test)
  58    #+END_SRC
  59
  60 2) Load required Babel languages
  61    #+BEGIN_SRC emacs-lisp
  62      (org-babel-do-load-languages
  63       'org-babel-load-languages
  64       (and
  65        (mapc (lambda (lang) (add-to-list 'org-babel-load-languages (cons lang t)))
  66              '(emacs-lisp shell org))
  67        org-babel-load-languages))
  68    #+END_SRC
  69
  70 3) Then run the test suite.  Babel evaluation confirmation is disabled
  71    and ~C-c C-c~ is enabled while running the tests.
  72    #+BEGIN_SRC emacs-lisp
  73      (let (org-babel-no-eval-on-ctrl-c-ctrl-c
  74            org-confirm-babel-evaluate)
  75        (org-test-run-all-tests))
  76    #+END_SRC
  77
  78    When a test fails, run it interactively and investigate the problem
  79    in the ERT results buffer.
  80
  81    How to run one test:
  82    Use this as a demo example of a failing test
  83    #+BEGIN_SRC emacs-lisp
  84      (ert-deftest test-org/org-link-escape-ascii-character-demo-of-fail ()
  85        (should (string= "%5B"  ;; expecting %5B is right
  86                         (org-link-escape "[")))
  87        (should (string= "%5C"  ;; expecting %5C is wrong, %5D right
  88                         (org-link-escape "]"))))
  89    #+END_SRC
  90    or evaluate the ert-deftest form of the test you want to run.  Then
  91    "M-x ert RET test-org/org-link-escape-ascii-character-demo-of-fail RET"
  92    When not visible yet switch to the ERT results buffer named
  93    "\*ert\*".  When a test failed the ERT results buffer shows the
  94    details of the first "should" that failed.  See
  95    (info "(ert)Running Tests Interactively") on how to re-run, start
  96    the debugger etc.
  97
  98    How to run all tests of a single test file:
  99    "M-x ert-delete-all-tests RET", confirm.  Open the file
 100    ./lisp/test-*.el, "M-x eval-buffer RET", "M-x ert RET t RET"
 101
 102    Consider to set pp-escape-newlines nil before running the test when
 103    looking at "should" in the ERT results buffer.  Especially when
 104    using "l" to look at passed test results and possibly missing an
 105    appropriate setting of pp-escape-newlines made only temporarily for
 106    the running time of the test as e. g. tests using
 107    org-test-table-target-expect-tblfm do.
 108
 109 * Troubleshooting
 110
 111 - If the value of the =org-babel-no-eval-on-ctrl-c-ctrl-c= is non-nil
 112   then it will result in some test failure, as there are tests which
 113   rely on this behavior.