From 710f445768cb9eaf6ae7c7c17c11fc16016befca Mon Sep 17 00:00:00 2001
From: Michael Brand <michael.ch.brand@gmail.com>
Date: Fri, 28 Dec 2012 14:58:24 +0100
Subject: [PATCH] testing/README: add howto run ERT partially

* testing/README (Interactive testing from within Emacs): Add a
description how to run a single ERT or all tests of a single test
file.
---
 testing/README | 33 ++++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/testing/README b/testing/README
index a81efa022..8ce7a1923 100644
--- a/testing/README
+++ b/testing/README
@@ -43,11 +43,42 @@ load and run the test suite with the following commands.
      (require 'org-test)
    #+END_SRC
 
-2) Then run the test suite.
+2) Then run the test suite,
    #+BEGIN_SRC emacs-lisp
      (org-test-run-all-tests)
    #+END_SRC
 
+   or when a test fails run it interactively and investigate the
+   problem in the ERT results buffer.
+
+   How to run one test:
+   Use this as a demo example of a failing test
+   #+BEGIN_SRC emacs-lisp
+     (ert-deftest test-org/org-link-escape-ascii-character-demo-of-fail ()
+       (should (string= "%5B"  ;; expected is right
+                        (org-link-escape "[")))
+       (should (string= "%5C"  ;; expected is wrong, "%5D" would be right
+                        (org-link-escape "]"))))
+   #+END_SRC
+   or evaluate the ert-deftest form of the test you want to run.  Then
+   "M-x ert RET test-org/org-link-escape-ascii-character-demo-of-fail RET"
+   When not visible yet switch to the ERT results buffer named
+   "\*ert\*".  When a test failed the ERT results buffer shows the
+   details of the first "should" that failed.  See
+   (info "(ert)Running Tests Interactively") on how to re-run, start
+   the debugger etc.
+
+   How to run all tests of a single test file:
+   "M-x ert-delete-all-tests RET", confirm.  Open the file
+   ./lisp/test-*.el, "M-x eval-buffer RET", "M-x ert RET t RET"
+
+   Consider to set pp-escape-newlines nil before running the test when
+   looking at "should" in the ERT results buffer.  Especially when
+   using "l" to look at passed test results and possibly missing an
+   appropriate setting of pp-escape-newlines made only temporarily for
+   the running time of the test as e. g. tests using
+   org-test-table-target-expect-tblfm do.
+
 * Troubleshooting
 
 - If the value of the =org-babel-no-eval-on-ctrl-c-ctrl-c= is non-nil