updated testing/README.org describing how to get started writing tests

2 files changed, 52 insertions, 100 deletions

diff --git a/testing/README.org b/testing/README.org
index be6ccc7..8a3b390 100644
--- a/testing/README.org
+++ b/testing/README.org
@@ -1,99 +1,50 @@
-#+OPTIONS:  ^:nil
-
-
-* Testing elisp files with ERT
-
-  The aim is to provide a few simple yet helpfull commands for testing
-  while hacking on elisp files.  The entire thing is based on
-  conventions.  You don't need to care for those conventions, but it
-  makes live easier.
-
-  Currently three commands are provided:
-
-  * =org-test-edit-buffer-file-tests= :: Open the file with tests for
-      the current buffer.  If the file and it's parent directories do
-      not yet exist, create them.  If the file did not yet exist,
-      insert a little template test to get started.
-
-  * =org-test-edit-current-defuns-tests= :: Open the file with tests for
-      the current defun.  Note: this opens a file with the name of the
-      current defun.  If you do not expect many tests for a file to be
-      written, you could as call `org-test-edit-buffer-file-tests'.
-
-  * =org-test-test-current-defun= :: Look up test files for defun at
-       point and execute the tests.  This is done by searching an
-       elisp file with the name of the current defun plus ".el".  In
-       case your point is in defun DEFUN in the file
-       =proj/lisp/FILE.el=, this command will search the directory tree
-       up until it finds a directory named =testing/=.  If there is a
-       directory =proj/testing/= it assumes your tests are in
-       =proj/testing/lisp/FILE.el/DEFUN.el=.  If that file is found, it
-       will be loaded and all ERT tests for the selector "^DEFUN" will
-       be executed.  If that file does not exist, fall back on loading
-       =proj/testing/lisp/FILE.el/tests.el=.
-
-  * =org-test-test-buffer-file= :: Look up a test file for
-       `buffer-file-name' and execute the tests.  This is done by
-       searching for a directory =testing/= from `buffer-file-name's
-       directory upwards and then apply the relative path to your
-       source file there.  In case you're editing =proj/lisp/FILE.el=,
-       and a directory =proj/testing/= exists, this command will try to
-       load =proj/testing/lisp/FILE.el/tests.el= and other elisp files
-       in that directory.  The resulting list of files will be loaded
-       and all ERT tests for selector "^FILE" will be executed.  With
-       a prefix argument, load only =tests.el=.
-
-  * =org-test-run-all-tests= :: Run all tests for all lisp files and all
-       defuns in your project.
-
-
-  The first two commands call `ert-delete-all-tests' to make sure that
-  only the desired tests are executed.  All functions load the test
-  files for each call, hence always a current version of tests are
-  used.  (This might change in the future...)
-
-
-* Getting started
-
-  You should obtain ERT by cloning Christian Ohler's public git
-  repository:
-
-  : sh$ git clone http://github.com/ohler/ert.git
-
-  Ensure that the =ert/= directory is in your loadpath:
-
-  : (add-to-list 'load-path "~/path/to/ert/")
-
-
-*** Where to put the tests
-
-    The tests live in a directory (e.g. =proj/testing/=) that closely
-    resembles the directory structure below =proj/=.
-
-    For example let's assume a file =proj/lisp/FILE.el= exists.  To write tests
-    for this file, create a directory structure in =proj/testing/= with the relative
-    path to your file plus the name of that file as directory:
-    =proj/testing/lisp/FILE.el/=
-
-    Org-test searches that directory for a file named =tests.el= and
-    executes all ERT tests that match the selector "=^FILE=".
-
-    To run a test, you might want to use one of the two commands
-    provided by =org-test.el= (see above).
-
-
-* TODOs
-
-*** TODO Setup a buffers for testing
-
-***** TODO Compare the contents of such a buffer
-      ...with a control file.
-
-*** TODO Provide directory and file functions
-    Provide little services to help test writers with temporary
-    buffers, files and directories.
-
-    Or just use temp-files for that?
-
-*** TODO let-bind different setups for tests
-    Maybe just provide an example on how to do that.
+#+Title: Org-mode Testing
+#+Babel: results silent
+
+The following instructions describe how to get started using the
+Org-mode test framework.
+
+1) Install the ERT and jump.el testing dependencies which are included
+   as git submodules 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) Load the [[file:org-test.el][org-test.el]] file
+   #+begin_src emacs-lisp
+     (load-file "org-test.el")
+   #+end_src
+
+3) 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 just 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.
+
+4) Review the ERT documentation, to do this run =makeinfo= in the
+   =testing/ert= directory,
+   #+begin_src sh
+     cd ert
+     makeinfo ert.texinfo
+   #+end_src
+   then browse the [[elisp:(info (expand-file-name "ert/ert.info"))][resulting info file]].
+
+5) 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.
+
+6) 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
diff --git a/testing/org-test.el b/testing/org-test.el
index 5248952..faafa2e 100644
--- a/testing/org-test.el
+++ b/testing/org-test.el
@@ -70,7 +70,6 @@ org-test searches this directory up the directory tree.")
 
 
 ;;; Functions for writing tests
-
 (defun org-test-buffer (&optional file)
   "TODO:  Setup and return a buffer to work with.
 If file is non-nil insert it's contents in there.")
@@ -152,6 +151,8 @@ files."
        ";;; " file-name " ends here\n") full-path))
   (lambda () ((lambda (res) (if (listp res) (car res) res)) (which-function))))
 
+(define-key emacs-lisp-mode-map "\M-\C-j" 'org-test-jump)
+
 
 ;;; Load and Run tests
 (defun org-test-load ()