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    To run one test: Use this as a demo example of a failing test
  82    #+BEGIN_SRC emacs-lisp
  83      (ert-deftest test-org/org-link-escape-ascii-character-demo-of-fail ()
  84        (should (string= "%5B"  ; Expecting %5B is correct.
  85                         (org-link-escape "[")))
  86        (should (string= "%5C"  ; Expecting %5C is wrong, %5D correct.
  87                         (org-link-escape "]"))))
  88    #+END_SRC
  89    or evaluate the ~ert-deftest form~ of the test you want to run.
  90    Then ~M-x ert RET
  91    test-org/org-link-escape-ascii-character-demo-of-fail RET~.  When
  92    not visible yet switch to the ERT results buffer named ~*ert*~.
  93    When a test failed the ERT results buffer shows the details of the
  94    first ~should~ that failed.  See ~(info "(ert)Running Tests
  95    Interactively")~ on how to re-run, start the debugger etc.
  96
  97    To run several tests: ~M-x ert RET "<your regexp here>" RET~.
  98
  99    To run all tests of a single test file: ~M-x ert-delete-all-tests
 100    RET~ and confirm.  ~M-x load-file RET testing/lisp/<file>.el RET
 101    M-x ert RET t RET~.
 102
 103    Consider to set
 104    #+BEGIN_SRC emacs-lisp
 105      (setq pp-escape-newlines nil)
 106    #+END_SRC
 107    before running the test when looking at ~should~ in the ERT results
 108    buffer.  Especially when using ~l~ to look at passed test results
 109    and possibly missing an appropriate setting of ~pp-escape-newlines~
 110    made only temporarily for the running time of the test as
 111    e. g. tests using ~org-test-table-target-expect-tblfm~ do.
 112
 113 * Troubleshooting
 114
 115 - If the variable ~org-babel-no-eval-on-ctrl-c-ctrl-c~ is non-nil then
 116   it will result in some test failure, as there are tests which rely
 117   on this behavior.