#+Title: Org-mode Testing
#+Babel: results silent

The following instructions describe how to get started using the
Org-mode test framework.

1) Install the jump.el testing dependency which is included as a git
   submodule in the org-mode repository.  To do so run the following
   git submodule commands from inside the base of the Org-mode
   directory (or just execute the following code block).

   #+begin_src sh
     cd ..
     git submodule init
     git submodule update
   #+end_src

2) The ERT testing library is included in Emacs 24. On Emacs prior to
   version 24 it is required to install a recent version of ERT and
   set up its load-path in your init file. A recent package can be
   downloaded [[https://github.com/ohler/ert/archives/fb3c278d3c8ddc6a558779d2c5262acc7cea4204][here.]] Copy the files into testing/ert and follow the
   installation instructions in README.txt

3) Load the [[file:org-test.el][org-test.el]] file
   #+begin_src emacs-lisp
     (load-file "org-test.el")
   #+end_src

4) The =org-test-jump= command is now bound to =M-C-j= in all
   emacs-lisp files.  Call this command from any file in the =lisp/=
   directory of the org-mode repository to jump to the related test
   file in the =testing/= directory.  Call this functions with a
   prefix argument, and the corresponding test file will be stubbed
   out if it doesn't already exist.

5) Ingest the library-of-babel.org file since some tests require this.
   #+begin_src emacs-lisp
     (org-babel-lob-ingest "../contrib/babel/library-of-babel.org")
   #+end_src

6) [[info:ert#Top][Review the ERT documentation]] 

7) A number of org-mode-specific functions and macros are provided in
   =org-test.el= see the [[file:org-test.el::%3B%3B%3B%20Functions%20for%20writing%20tests][;;; Functions for Writing Tests]] subsection of
   that file.  Some of these functions make use of example org-mode
   files located in the [[file:examples][examples/]] directory.

8) Functions for loading and running the Org-mode tests are provided
   in the [[file:org-test.el::%3B%3B%3B%20Load%20and%20Run%20tests][;;; Load and Run Tests]] subsection, the most important of
   which are
   - =org-test-load= which loads the entire Org-mode test suite
   - =org-test-current-defun= which runs all tests for the current
     function around point (should be called from inside of an
     Org-mode elisp file)
   - =org-test-run-all-tests= which runs the entire Org-mode test suite
   - also note that the =ert= command can also be used to run tests

9) Load and run all tests
   #+begin_src emacs-lisp 
     (load-file "org-test.el")
     (org-babel-lob-ingest "../contrib/babel/library-of-babel.org")
     (org-test-load)
     (org-test-run-all-tests)
   #+end_src