Use inactive timestamps when re-scheduling or re-deadlining
[org-mode.git] / testing / README
Commit [+]AuthorDateLineData
e1d0311d Eric Schulte2012-01-28 15:38:03 -07001# -*- mode:org -*-
b857974f
BG
Bastien Guerry2012-04-21 00:59:14 +02002#+TITLE: Org-mode Testing
3#+PROPERTY: results silent
4
5* Dependencies
e1d0311d Eric Schulte2012-01-28 15:38:03 -07006
e1d0311d
ES
Eric Schulte2012-01-28 15:38:03 -07007The only dependency is [[http://www.emacswiki.org/emacs/ErtTestLibrary][ERT]] the Emacs testing library which ships with
8Emacs24. If you are running an older version of Emacs and don't
9already have ERT installed it can be installed from its old [[https://github.com/ohler/ert][git
10repository]].
11
b857974f
BG
Bastien Guerry2012-04-21 00:59:14 +020012* Non-interactive batch testing from the command line
13
e1d0311d
ES
Eric Schulte2012-01-28 15:38:03 -070014The simplest way to run the Org-mode test suite is from the command
15line with the following invocation. Note that the paths below are
16relative to the base of the Org-mode directory.
b857974f Bastien Guerry2012-04-21 00:59:14 +020017
8e8f40ce
YS
Yasushi SHOJI2013-01-30 17:35:09 +010018Also note that many of the current tests uses babel evaluation...
19
1977df99
IS
Ilya Shlyakhter2012-03-30 22:11:22 -040020#+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 \
8e8f40ce
YS
Yasushi SHOJI2013-01-30 17:35:09 +010025 --eval "(progn (org-reload) (setq org-confirm-babel-evaluate nil) \
26 (org-babel-do-load-languages 'org-babel-load-languages \
5f0ca0ee Nicolas Richard2014-01-31 17:02:03 +010027 '((emacs-lisp . t) (shell . t) (org . t))))" \
1977df99 Ilya Shlyakhter2012-03-30 22:11:22 -040028 -f org-test-run-batch-tests
e1d0311d
ES
Eric Schulte2012-01-28 15:38:03 -070029#+END_SRC
30
31The options in the above command are explained below.
b857974f Bastien Guerry2012-04-21 00:59:14 +020032
e1d0311d
ES
Eric Schulte2012-01-28 15:38:03 -070033| -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
b857974f
BG
Bastien Guerry2012-04-21 00:59:14 +020039* Interactive testing from within Emacs
40
e1d0311d
ES
Eric Schulte2012-01-28 15:38:03 -070041To run the Org-mode test suite from a current Emacs instance simply
42load and run the test suite with the following commands.
43
441) First load the test suite.
45 #+BEGIN_SRC emacs-lisp :var here=(buffer-file-name)
46 (add-to-list 'load-path (file-name-directory here))
47 (require 'org-test)
48 #+END_SRC
49
46a45905 Rasmus2014-07-18 17:19:01 +0200502) Load required Babel languages
8e8f40ce Yasushi SHOJI2013-01-30 17:35:09 +010051 #+BEGIN_SRC emacs-lisp
46a45905
R
Rasmus2014-07-18 17:19:01 +020052 (org-babel-do-load-languages
53 'org-babel-load-languages
54 (and
55 (mapc (lambda (lang) (add-to-list 'org-babel-load-languages (cons lang t)))
56 '(emacs-lisp shell org))
57 org-babel-load-languages))
8e8f40ce
YS
Yasushi SHOJI2013-01-30 17:35:09 +010058 #+END_SRC
59
46a45905
R
Rasmus2014-07-18 17:19:01 +0200603) Then run the test suite. Babel evaluation confirmation is disabled
61 and ~C-c C-c~ is enabled while running the tests.
e1d0311d Eric Schulte2012-01-28 15:38:03 -070062 #+BEGIN_SRC emacs-lisp
46a45905
R
Rasmus2014-07-18 17:19:01 +020063 (let (org-babel-no-eval-on-ctrl-c-ctrl-c
64 org-confirm-babel-evaluate)
65 (org-test-run-all-tests))
e1d0311d Eric Schulte2012-01-28 15:38:03 -070066 #+END_SRC
b857974f Bastien Guerry2012-04-21 00:59:14 +020067
46a45905
R
Rasmus2014-07-18 17:19:01 +020068 When a test fails, run it interactively and investigate the problem
69 in the ERT results buffer.
710f4457
MB
Michael Brand2012-12-28 14:58:24 +010070
71 How to run one test:
72 Use this as a demo example of a failing test
73 #+BEGIN_SRC emacs-lisp
74 (ert-deftest test-org/org-link-escape-ascii-character-demo-of-fail ()
e04a22ed Michael Brand2013-10-05 15:00:25 +020075 (should (string= "%5B" ;; expecting %5B is right
710f4457 Michael Brand2012-12-28 14:58:24 +010076 (org-link-escape "[")))
e04a22ed Michael Brand2013-10-05 15:00:25 +020077 (should (string= "%5C" ;; expecting %5C is wrong, %5D right
710f4457
MB
Michael Brand2012-12-28 14:58:24 +010078 (org-link-escape "]"))))
79 #+END_SRC
80 or evaluate the ert-deftest form of the test you want to run. Then
81 "M-x ert RET test-org/org-link-escape-ascii-character-demo-of-fail RET"
82 When not visible yet switch to the ERT results buffer named
83 "\*ert\*". When a test failed the ERT results buffer shows the
84 details of the first "should" that failed. See
85 (info "(ert)Running Tests Interactively") on how to re-run, start
86 the debugger etc.
87
88 How to run all tests of a single test file:
89 "M-x ert-delete-all-tests RET", confirm. Open the file
90 ./lisp/test-*.el, "M-x eval-buffer RET", "M-x ert RET t RET"
91
92 Consider to set pp-escape-newlines nil before running the test when
93 looking at "should" in the ERT results buffer. Especially when
94 using "l" to look at passed test results and possibly missing an
95 appropriate setting of pp-escape-newlines made only temporarily for
96 the running time of the test as e. g. tests using
97 org-test-table-target-expect-tblfm do.
98
b857974f
BG
Bastien Guerry2012-04-21 00:59:14 +020099* Troubleshooting
100
9fb3e136
ES
Eric Schulte2012-01-28 15:51:57 -0700101- If the value of the =org-babel-no-eval-on-ctrl-c-ctrl-c= is non-nil
102 then it will result in some test failure, as there are tests which
103 rely on this behavior.