org-index.el with new command 'focus'
[org-mode.git] / testing / README
1 # -*- mode:org -*-
2 #+TITLE: Org-mode Testing
3 #+PROPERTY: results silent
5 * Dependencies
7 The only dependency is [[][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 [[][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 testing with 'make test'
41 Target ~test~ can be used to trigger a test run.
43 #+BEGIN_SRC sh :dir (expand-file-name "..")
44 make test
45 #+END_SRC
47 See ../mk/ for details.
49 * Interactive testing from within Emacs
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.
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
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
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
78    When a test fails, run it interactively and investigate the problem
79    in the ERT results buffer.
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.
97    To run several tests: ~M-x ert RET "<your regexp here>" RET~.
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~.
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.
113 * Troubleshooting
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.