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 the tests with 'make'
  40
  41 ** Recompile all
  42
  43 Target ~test~ can be used to trigger a test run.  The tests start
  44 after cleaning up and recompilation.
  45
  46 #+BEGIN_SRC sh :dir (expand-file-name "..") :results silent
  47 make test
  48 #+END_SRC
  49
  50 See ../mk/default.mk for details.
  51
  52 ** Test dirty
  53
  54 The 'dirty' targets are for recompiling without cleaning and
  55 rebuilding everything.  This usually speeds up the recompilation
  56 considerably.
  57
  58 The 'dirty' target is called test-dirty.
  59
  60 #+BEGIN_SRC sh :dir (expand-file-name "..") :results silent
  61 make test-dirty
  62 #+END_SRC
  63
  64 Note that the outcome may /not/ be in perfect shape.
  65
  66 * Interactive testing from within Emacs
  67
  68 To run the Org-mode test suite from a current Emacs instance simply
  69 load and run the test suite with the following commands.
  70
  71 1) First load the test suite.
  72    #+BEGIN_SRC emacs-lisp :var here=(buffer-file-name)
  73      (add-to-list 'load-path (file-name-directory here))
  74      (require 'org-test)
  75    #+END_SRC
  76
  77 2) Load required Babel languages
  78    #+BEGIN_SRC emacs-lisp
  79      (org-babel-do-load-languages
  80       'org-babel-load-languages
  81       (and
  82        (mapc (lambda (lang) (add-to-list 'org-babel-load-languages (cons lang t)))
  83              '(emacs-lisp shell org))
  84        org-babel-load-languages))
  85    #+END_SRC
  86
  87 3) Then run the test suite.  Babel evaluation confirmation is disabled
  88    and ~C-c C-c~ is enabled while running the tests.
  89    #+BEGIN_SRC emacs-lisp
  90      (let (org-babel-no-eval-on-ctrl-c-ctrl-c
  91            org-confirm-babel-evaluate)
  92        (org-test-run-all-tests))
  93    #+END_SRC
  94
  95    When a test fails, run it interactively and investigate the problem
  96    in the ERT results buffer.
  97
  98    To run one test: Use this as a demo example of a failing test
  99    #+BEGIN_SRC emacs-lisp
 100      (ert-deftest test-org/org-link-escape-ascii-character-demo-of-fail ()
 101        (should (string= "%5B"  ; Expecting %5B is correct.
 102                         (org-link-escape "[")))
 103        (should (string= "%5C"  ; Expecting %5C is wrong, %5D correct.
 104                         (org-link-escape "]"))))
 105    #+END_SRC
 106    or evaluate the ~ert-deftest form~ of the test you want to run.
 107    Then ~M-x ert RET
 108    test-org/org-link-escape-ascii-character-demo-of-fail RET~.  When
 109    not visible yet switch to the ERT results buffer named ~*ert*~.
 110    When a test failed the ERT results buffer shows the details of the
 111    first ~should~ that failed.  See ~(info "(ert)Running Tests
 112    Interactively")~ on how to re-run, start the debugger etc.
 113
 114    To run several tests: ~M-x ert RET "<your regexp here>" RET~.
 115
 116    To run all tests of a single test file: ~M-x ert-delete-all-tests
 117    RET~ and confirm.  ~M-x load-file RET testing/lisp/<file>.el RET
 118    M-x ert RET t RET~.
 119
 120    Consider to set
 121    #+BEGIN_SRC emacs-lisp
 122      (setq pp-escape-newlines nil)
 123    #+END_SRC
 124    before running the test when looking at ~should~ in the ERT results
 125    buffer.  Especially when using ~l~ to look at passed test results
 126    and possibly missing an appropriate setting of ~pp-escape-newlines~
 127    made only temporarily for the running time of the test as
 128    e. g. tests using ~org-test-table-target-expect-tblfm~ do.
 129
 130 * Troubleshooting
 131
 132 - If the variable ~org-babel-no-eval-on-ctrl-c-ctrl-c~ is non-nil then
 133   it will result in some test failure, as there are tests which rely
 134   on this behavior.