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.  Note that this speed up comes to the price of possibly
  57 weird errors due to the unclean build.
  58
  59 The dirty target for testing is called ~test-dirty~.
  60
  61 #+BEGIN_SRC sh :dir (expand-file-name "..") :results silent
  62 make test-dirty
  63 #+END_SRC
  64
  65 ** Select tests by regexp
  66
  67 Variable ~BTEST_RE~ can be set to limit the tests which are performed.
  68 ~BTEST_RE~ is interpreted as regexp.
  69
  70 Example:
  71
  72 #+begin_src shell
  73 make BTEST_RE='test-.*-inlinetask' test-dirty
  74 #+end_src
  75
  76 yields
  77
  78 #+begin_example
  79 ...
  80 selected tests: test-.*-inlinetask
  81 Running 2 tests (2017-12-28 15:04:45+0100)
  82    passed  1/2  test-org-export/handle-inlinetasks
  83    passed  2/2  test-org-inlinetask/goto-end
  84
  85 Ran 2 tests, 2 results as expected (2017-12-28 15:04:45+0100)
  86 ...
  87 #+end_example
  88
  89 * Interactive testing from within Emacs
  90
  91 To run the Org-mode test suite from a current Emacs instance simply
  92 load and run the test suite with the following commands.
  93
  94 1) First load the test suite.
  95    #+BEGIN_SRC emacs-lisp :var here=(buffer-file-name)
  96      (add-to-list 'load-path (file-name-directory here))
  97      (require 'org-test)
  98    #+END_SRC
  99
 100 2) Load required Babel languages
 101    #+BEGIN_SRC emacs-lisp
 102      (org-babel-do-load-languages
 103       'org-babel-load-languages
 104       (and
 105        (mapc (lambda (lang) (add-to-list 'org-babel-load-languages (cons lang t)))
 106              '(emacs-lisp shell org))
 107        org-babel-load-languages))
 108    #+END_SRC
 109
 110 3) Then run the test suite.  Babel evaluation confirmation is disabled
 111    and ~C-c C-c~ is enabled while running the tests.
 112    #+BEGIN_SRC emacs-lisp
 113      (let (org-babel-no-eval-on-ctrl-c-ctrl-c
 114            org-confirm-babel-evaluate)
 115        (org-test-run-all-tests))
 116    #+END_SRC
 117
 118    When a test fails, run it interactively and investigate the problem
 119    in the ERT results buffer.
 120
 121    To run one test: Use this as a demo example of a failing test
 122    #+BEGIN_SRC emacs-lisp
 123      (ert-deftest test-org/org-link-escape-ascii-character-demo-of-fail ()
 124        (should (string= "%5B"  ; Expecting %5B is correct.
 125                         (org-link-escape "[")))
 126        (should (string= "%5C"  ; Expecting %5C is wrong, %5D correct.
 127                         (org-link-escape "]"))))
 128    #+END_SRC
 129    or evaluate the ~ert-deftest form~ of the test you want to run.
 130    Then ~M-x ert RET
 131    test-org/org-link-escape-ascii-character-demo-of-fail RET~.  When
 132    not visible yet switch to the ERT results buffer named ~*ert*~.
 133    When a test failed the ERT results buffer shows the details of the
 134    first ~should~ that failed.  See ~(info "(ert)Running Tests
 135    Interactively")~ on how to re-run, start the debugger etc.
 136
 137    To run several tests: ~M-x ert RET "<your regexp here>" RET~.
 138
 139    To run all tests of a single test file: ~M-x ert-delete-all-tests
 140    RET~ and confirm.  ~M-x load-file RET testing/lisp/<file>.el RET
 141    M-x ert RET t RET~.
 142
 143    Consider to set
 144    #+BEGIN_SRC emacs-lisp
 145      (setq pp-escape-newlines nil)
 146    #+END_SRC
 147    before running the test when looking at ~should~ in the ERT results
 148    buffer.  Especially when using ~l~ to look at passed test results
 149    and possibly missing an appropriate setting of ~pp-escape-newlines~
 150    made only temporarily for the running time of the test as
 151    e. g. tests using ~org-test-table-target-expect-tblfm~ do.
 152
 153 * Troubleshooting
 154
 155 - If the variable ~org-babel-no-eval-on-ctrl-c-ctrl-c~ is non-nil then
 156   it will result in some test failure, as there are tests which rely
 157   on this behavior.