updated testing/README.org describing how to get started writing tests
This commit is contained in:
Eric Schulte
parent
af4bd933d0
commit
d9e4469c1c
|
|
@ -1,99 +1,50 @@
|
|||
#+OPTIONS: ^:nil
|
||||
#+Title: Org-mode Testing
|
||||
#+Babel: results silent
|
||||
|
||||
The following instructions describe how to get started using the
|
||||
Org-mode test framework.
|
||||
|
||||
* Testing elisp files with ERT
|
||||
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
|
||||
|
||||
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.
|
||||
2) Load the [[file:org-test.el][org-test.el]] file
|
||||
#+begin_src emacs-lisp
|
||||
(load-file "org-test.el")
|
||||
#+end_src
|
||||
|
||||
Currently three commands are provided:
|
||||
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.
|
||||
|
||||
* =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.
|
||||
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]].
|
||||
|
||||
* =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'.
|
||||
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.
|
||||
|
||||
* =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.
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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 ()
|
||||
|
|
|
|||
Loading…
Reference in New Issue