testing/README.org

   1 #+Title: Org-mode Testing
   2 #+Babel: results silent
   3
   4 The following instructions describe how to get started using the
   5 Org-mode test framework.
   6
   7 * To run the tests interactively
   8   :PROPERTIES:
   9   :tangle:   no
  10   :END:
  11 1) Install the jump.el testing dependency which is included as a git
  12    submodule in the org-mode repository.  To do so run the following
  13    git submodule commands from inside the base of the Org-mode
  14    directory (or just execute the following code block).
  15
  16    #+begin_src sh
  17      cd ..
  18      git submodule init
  19      git submodule update
  20    #+end_src
  21
  22 2) Load the [[file:org-test.el][org-test.el]] file
  23    #+begin_src emacs-lisp
  24      (load-file "org-test.el")
  25    #+end_src
  26
  27 3) The =org-test-jump= command is now bound to =M-C-j= in all
  28    emacs-lisp files.  Call this command from any file in the =lisp/=
  29    directory of the org-mode repository to jump to the related test
  30    file in the =testing/= directory.  Call this functions with a
  31    prefix argument, and the corresponding test file will be stubbed
  32    out if it doesn't already exist.
  33
  34 4) Ingest the library-of-babel.org file since some tests require this.
  35    #+begin_src emacs-lisp
  36      (org-babel-lob-ingest "../contrib/babel/library-of-babel.org")
  37    #+end_src
  38
  39 5) [[info:ert#Top][Review the ERT documentation]]
  40
  41 6) A number of org-mode-specific functions and macros are provided in
  42    =org-test.el= see the [[file:org-test.el::%3B%3B%3B%20Functions%20for%20writing%20tests][;;; Functions for Writing Tests]] subsection of
  43    that file.  Some of these functions make use of example org-mode
  44    files located in the [[file:examples][examples/]] directory.
  45
  46 7) Functions for loading and running the Org-mode tests are provided
  47    in the [[file:org-test.el::%3B%3B%3B%20Load%20and%20Run%20tests][;;; Load and Run Tests]] subsection, the most important of
  48    which are
  49    - =org-test-load= which loads the entire Org-mode test suite
  50    - =org-test-current-defun= which runs all tests for the current
  51      function around point (should be called from inside of an
  52      Org-mode elisp file)
  53    - =org-test-run-all-tests= which runs the entire Org-mode test suite
  54    - also note that the =ert= command can also be used to run tests
  55
  56 8) Load and run all tests
  57    #+begin_src emacs-lisp
  58      (load-file "org-test.el")
  59      (org-babel-lob-ingest "../contrib/babel/library-of-babel.org")
  60      (org-test-load)
  61      (org-test-run-all-tests)
  62    #+end_src
  63
  64 * To run the tests in batch mode
  65 First tangle this file out to your desktop.
  66 #+headers: :tangle ~/Desktop/run-org-tests.el
  67 #+begin_src emacs-lisp :var org-dir=(expand-file-name ".." (file-name-directory (or load-file-name (buffer-file-name))))
  68   ;; add to the load path
  69   (add-to-list 'load-path (concat org-dir "/lisp/"))
  70   (add-to-list 'load-path (concat org-dir "/lisp/testing/"))
  71   (add-to-list 'load-path (concat org-dir "/lisp/testing/ert/"))
  72
  73   ;; load Org-mode
  74   (require 'org)
  75
  76   ;; setup the ID locations used in tests
  77   (require 'org-id)
  78   (org-id-update-id-locations
  79    (list (concat org-dir "/testing/examples/babel.org")
  80          (concat org-dir "/testing/examples/normal.org")
  81          (concat org-dir "/testing/examples/link-in-heading.org")
  82          (concat org-dir "/testing/examples/links.org")))
  83
  84   ;; ensure that the latest Org-mode is loaded
  85   (org-reload)
  86
  87   ;; load the test suite
  88   (load-file (concat org-dir "/testing/org-test.el"))
  89
  90   ;; configure Babel
  91   (org-babel-lob-ingest (concat org-dir "/contrib/babel/library-of-babel.org"))
  92   (org-babel-do-load-languages
  93    'org-babel-load-languages
  94    '((emacs-lisp . t)
  95      (sh . t)))
  96   (setq org-confirm-babel-evaluate nil)
  97
  98   ;; run the test suite
  99   (org-test-run-all-tests)
 100
 101   ;; print the results
 102   (with-current-buffer "*ert*"
 103     (print (buffer-string)))
 104 #+end_src
 105
 106 Then run the test suite with the following command which could use any
 107 version of Emacs.
 108 #+begin_src sh :results output silent
 109   emacs --batch -Q -l ~/Desktop/run-org-tests.el
 110 #+end_src