Merge branch 'maint'
[org-mode.git] / testing / README
blob2135990cb19b2928c9115cd83373971dd2985ec5
1 # -*- mode:org -*-
2 #+TITLE: Org-mode Testing
3 #+PROPERTY: results silent
5 * Dependencies
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]].
12 * Non-interactive batch testing from the command line
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.
18 Also note that many of the current tests uses babel evaluation...
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
31 The options in the above command are explained below.
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        |
39 * Trigger the tests with 'make'
41 ** Recompile all
43 Target ~test~ can be used to trigger a test run.  The tests start
44 after cleaning up and recompilation.
46 #+BEGIN_SRC sh :dir (expand-file-name "..") :results silent
47 make test
48 #+END_SRC
50 See ../mk/default.mk for details.
52 ** Test dirty
54 The 'dirty' targets are for recompiling without cleaning and
55 rebuilding everything.  This usually speeds up the recompilation
56 considerably.
58 The 'dirty' target is called test-dirty.
60 #+BEGIN_SRC sh :dir (expand-file-name "..") :results silent
61 make test-dirty
62 #+END_SRC
64 Note that the outcome may /not/ be in perfect shape.
66 * Interactive testing from within Emacs
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.
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
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
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
95    When a test fails, run it interactively and investigate the problem
96    in the ERT results buffer.
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.
114    To run several tests: ~M-x ert RET "<your regexp here>" RET~.
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~.
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.
130 * Troubleshooting
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.