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 1) Install the jump.el testing dependency which is included as a git
   8    submodule in the org-mode repository.  To do so run the following
   9    git submodule commands from inside the base of the Org-mode
  10    directory (or just execute the following code block).
  11
  12    #+begin_src sh
  13      cd ..
  14      git submodule init
  15      git submodule update
  16    #+end_src
  17
  18 2) Load the [[file:org-test.el][org-test.el]] file
  19    #+begin_src emacs-lisp
  20      (load-file "org-test.el")
  21    #+end_src
  22
  23 3) The =org-test-jump= command is now bound to =M-C-j= in all
  24    emacs-lisp files.  Call this command from any file in the =lisp/=
  25    directory of the org-mode repository to jump to the related test
  26    file in the =testing/= directory.  Call this functions with a
  27    prefix argument, and the corresponding test file will be stubbed
  28    out if it doesn't already exist.
  29
  30 4) Ingest the library-of-babel.org file since some tests require this.
  31    #+begin_src emacs-lisp
  32      (org-babel-lob-ingest "../contrib/babel/library-of-babel.org")
  33    #+end_src
  34
  35 5) [[info:ert#Top][Review the ERT documentation]]
  36
  37 6) A number of org-mode-specific functions and macros are provided in
  38    =org-test.el= see the [[file:org-test.el::%3B%3B%3B%20Functions%20for%20writing%20tests][;;; Functions for Writing Tests]] subsection of
  39    that file.  Some of these functions make use of example org-mode
  40    files located in the [[file:examples][examples/]] directory.
  41
  42 7) Functions for loading and running the Org-mode tests are provided
  43    in the [[file:org-test.el::%3B%3B%3B%20Load%20and%20Run%20tests][;;; Load and Run Tests]] subsection, the most important of
  44    which are
  45    - =org-test-load= which loads the entire Org-mode test suite
  46    - =org-test-current-defun= which runs all tests for the current
  47      function around point (should be called from inside of an
  48      Org-mode elisp file)
  49    - =org-test-run-all-tests= which runs the entire Org-mode test suite
  50    - also note that the =ert= command can also be used to run tests
  51
  52 8) Load and run all tests
  53    #+begin_src emacs-lisp
  54      (load-file "org-test.el")
  55      (org-babel-lob-ingest "../contrib/babel/library-of-babel.org")
  56      (org-test-load)
  57      (org-test-run-all-tests)
  58    #+end_src
  59