Merge branch 'maint'
[org-mode.git] / testing / README
blobae32d91f4487b0640d2336f8e0d717a3f9cea120
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.  Note that this speed up comes to the price of possibly
57 weird errors due to the unclean build.
59 The dirty target for testing is called ~test-dirty~.
61 #+BEGIN_SRC sh :dir (expand-file-name "..") :results silent
62 make test-dirty
63 #+END_SRC
65 ** Select tests by regexp
67 Variable ~BTEST_RE~ can be set to limit the tests which are performed.
68 ~BTEST_RE~ is interpreted as regexp.
70 Example:
72 #+begin_src shell
73 make BTEST_RE='test-.*-inlinetask' test-dirty
74 #+end_src
76 yields
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
85 Ran 2 tests, 2 results as expected (2017-12-28 15:04:45+0100)
86 ...
87 #+end_example
89 * Interactive testing from within Emacs
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.
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
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
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
118    When a test fails, run it interactively and investigate the problem
119    in the ERT results buffer.
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.
137    To run several tests: ~M-x ert RET "<your regexp here>" RET~.
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~.
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.
153 * Troubleshooting
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.