From e1d0311dd4caad1a41288cfd339e9412e541dc44 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Sat, 28 Jan 2012 15:38:03 -0700 Subject: [PATCH] greatly simplified the testing README --- testing/README.org | 140 +++++++++++---------------------------------- 1 file changed, 33 insertions(+), 107 deletions(-) diff --git a/testing/README.org b/testing/README.org index faa0dd50a..b83c39ca4 100644 --- a/testing/README.org +++ b/testing/README.org @@ -1,115 +1,41 @@ +# -*- mode:org -*- #+Title: Org-mode Testing -#+Babel: results silent +#+Property: results silent -The following instructions describe how to get started using the -Org-mode test framework. +* dependencies +The only dependency is [[http://www.emacswiki.org/emacs/ErtTestLibrary][ERT]] the Emacs testing library which ships with +Emacs24. If you are running an older version of Emacs and don't +already have ERT installed it can be installed from its old [[https://github.com/ohler/ert][git +repository]]. -* To run the tests interactively - :PROPERTIES: - :tangle: no - :END: -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). +* non-interactive batch testing from the command line +The simplest way to run the Org-mode test suite is from the command +line with the following invocation. Note that the paths below are +relative to the base of the Org-mode directory. +#+BEGIN_SRC sh + emacs -Q --batch -l lisp/org.el -l testing/org-test.el \ + --eval "(progn (org-reload) (setq org-confirm-babel-evaluate nil))" \ + -f org-test-run-batch-tests +#+END_SRC - #+begin_src sh - cd .. - git submodule init - git submodule update - #+end_src +The options in the above command are explained below. +| -Q | ignores any personal configuration ensuring a vanilla Emacs instance is used | +| --batch | runs Emacs in "batch" mode with no gui and termination after execution | +| -l | loads Org-mode and the org mode test suite defined in testing/org-test.el | +| --eval | reloads Org-mode and allows evaluation of code blocks by the tests | +| -f | actually runs the tests using the `org-test-run-batch-tests' function | -2) Load the [[file:org-test.el][org-test.el]] file - #+begin_src emacs-lisp - (load-file "org-test.el") - #+end_src +* interactive testing from within Emacs +To run the Org-mode test suite from a current Emacs instance simply +load and run the test suite with the following commands. -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 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. +1) First load the test suite. + #+BEGIN_SRC emacs-lisp :var here=(buffer-file-name) + (add-to-list 'load-path (file-name-directory here)) + (require 'org-test) + #+END_SRC -4) 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 - -5) [[info:ert#Top][Review the ERT documentation]] - -6) 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. - -7) 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 - -8) 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) +2) Then run the test suite. + #+BEGIN_SRC emacs-lisp (org-test-run-all-tests) - #+end_src - -* To run the tests in batch mode -First tangle this file out to your desktop. -#+headers: :tangle ~/Desktop/run-org-tests.el -#+begin_src emacs-lisp :var org-dir=(expand-file-name ".." (file-name-directory (or load-file-name (buffer-file-name)))) - ;; add to the load path - (add-to-list 'load-path (concat org-dir "/lisp/")) - (add-to-list 'load-path (concat org-dir "/lisp/testing/")) - (add-to-list 'load-path (concat org-dir "/lisp/testing/ert/")) - - ;; load Org-mode - (require 'org) - - ;; setup the ID locations used in tests - (require 'org-id) - (org-id-update-id-locations - (list (concat org-dir "/testing/examples/babel.org") - (concat org-dir "/testing/examples/ob-C-test.org") - (concat org-dir "/testing/examples/normal.org") - (concat org-dir "/testing/examples/ob-awk-test.org") - (concat org-dir "/testing/examples/ob-octave.org") - (concat org-dir "/testing/examples/ob-fortran-test.org") - (concat org-dir "/testing/examples/ob-maxima-test.org") - (concat org-dir "/testing/examples/link-in-heading.org") - (concat org-dir "/testing/examples/links.org"))) - - ;; ensure that the latest Org-mode is loaded - (org-reload) - - ;; load the test suite - (load-file (concat org-dir "/testing/org-test.el")) - - ;; configure Babel - (org-babel-lob-ingest (concat org-dir "/contrib/babel/library-of-babel.org")) - (org-babel-do-load-languages - 'org-babel-load-languages - '((emacs-lisp . t) - (sh . t))) - (setq org-confirm-babel-evaluate nil) - - ;; run the test suite - (org-test-run-all-tests) - - ;; print the results - (with-current-buffer "*ert*" - (print (buffer-string))) -#+end_src - -Then run the test suite with the following command which could use any -version of Emacs. -#+begin_src sh :results output silent - emacs --batch -Q -l ~/Desktop/run-org-tests.el -#+end_src + #+END_SRC