Add: README.org

1 files changed, 175 insertions, 0 deletions

diff --git a/README.org b/README.org
new file mode 100644
index 0000000..f224b46
--- /dev/null
+++ b/README.org
@@ -0,0 +1,175 @@
+A [[https://en.wiktionary.org/wiki/testiere][testiere]] is armor for the head of a horse and ~testiere~ is armor
+for the head of your ~defun~ forms.  
+
+* Testiere
+
+With ~testiere~ you can program in an interactive TDD-like
+fashion. Tests are included at the top of a ~defun/t~ form. When you
+recompile your functions interactively, the tests are run. If any
+fail, you are dropped into a debugger where you can decide to revert
+the definition to the last known working version, or you can choose to
+unbind it altogether.
+
+The system supports mocking and stubbing in your tests, so that you
+can, e.g. test the system in different dynamic contexts or by mocking
+network request functions.
+
+Here is an example:
+
+#+begin_src lisp
+
+(defun/t sum-3 (x y &key (z 10))
+  "Sums three numbers, Z has a default value of 10"
+  :tests
+  (:program some-test-function)
+  (= (1 2) 13)        ; (sum-3 1 2) == 13
+  (= (1 2 :z 3) 6)    ; (sum-3 1 2 :z 3) == 6
+  (:output (0 0)      ; tests that (sum-3 0 0) passes the predicate
+           (lambda (result) (= 10 result)))
+  (:fails             ; ensures that (sum-3 "strings" "ain't" :z "numbers") fails
+   ("strings" "ain't" :z "numbers"))
+  :end
+  (+ x y z))
+
+#+end_src
+
+In the above, a function ~sum-3~ is defined with five embedded
+tests. The test specification syntax is detailed below. If any of the
+tests fail, the function will not be redefined and you will drop into
+the debugger, which asks you how you'd like to proceed.
+
+The approach to TDD-like development taking by ~testiere~ may not be
+appropriate to all circumstances, but it is good for interactive
+application development of interactive applications (😉) whose "main
+loop" involves a good sized collection of unit-testable functions.
+
+** Test Specification 
+
+There are a few kinds of tests available. 
+
+*** For the Impatient, Just Use =:program= Tests
+
+Most users will probably benefit from the ~:program~ style test.  Here
+is a quick example:
+
+#+begin_src lisp
+
+(defun test-fibble ()
+  (assert (= 13 (fibble 1 2))))
+
+(defun/t fibble (x y &key (z 10))
+  "Adds three numbers, one of which defaults to 10."
+  :tests
+  (:program test-fibble)
+  :end
+  (+ x y z))
+
+#+end_src
+
+In the above test, we insist that the ~test-fibble~ function not
+signal an error condition in order for ~fibble~ to be successfully
+(re)compiled.
+
+*** Basic Test Specifications
+
+A test suite is a list of forms that appear between ~:tests~ and
+~:end~ in the body of a ~defun/t~ form.  The test suite must appear
+after any optional docstring and before the function body actually
+begins.
+
+A catalog of test form specifications follows.
+
+**** Comparator Test Specifications
+
+: (comparator (&rest args...) value)
+
+The ~comparator~ should be the name of a binary predicate (like ~<~ or
+~eql~).  These tests proceed by calling ~(comparator (apply my-fun args) value)~
+If the comparison fails, an error condition is signaled. 
+
+Amending the above example, we include a comparator test:
+
+
+#+begin_src lisp
+(defun/t fibble (x y &key (z 10))
+  "Adds three numbers, one of which defaults to 10."
+  :tests
+  (:program test-fibble)
+  (= (0 0 :z 39) 30)     ; (assert (= (fibble 0 0 :z 30) 30))
+  :end
+  (+ x y z))
+
+#+end_src
+
+**** Other Test Specifications
+
+Every other form appearing in a test suite is a list that starts with
+a keyword. 
+
+- ~(:program FUNCTION-NAME ARGS...)~ runs a function named
+  FUNCTION-NAME with arguments ARGS. This function is meant to act as
+  a test suite for the function being defined with defun/t. It may
+  call that function and ASSERT things about it.
+- ~(:outputp (..ARGS...) PREDICATE)~ asserts that the output passes
+  the one-argument predicate.
+- ~(:afterp (...ARGS...) THUNK)~ asserts that the thunk should return
+  non-nil after the function has run. Good for testing values of
+  dynamic variables that the function might interact with.
+- ~(:fails (...ARGS...))~ asserts that the function will produce an
+  error with the given arguments.
+- ~(:signals (...ARGS...) CONDITION)~ where ~CONDITION~ is the name of
+  a condition. Asserts that the function will signal a condition of
+  the supplied type when called with the provided arguments.
+
+
+*** Mocking and Stubbing 
+
+The following test forms allow for the running of tests inside a
+context in which certain functions or global values are bound:
+
+Binding variables looks like
+
+: (:let LET-BINDINGS TESTS) 
+    
+and are useful for binding dynamic variables for use during a set of
+tests.
+
+For example 
+
+#+begin_src lisp
+
+    (defvar *count*)
+    
+    (defun/t increment-count ()
+      "Increments the *count* variable."
+      :tests
+      (:let ((*count* 4))
+        (:afterp () (lambda () (= *count* 5))) ; 5 after the first call
+        (= () 6)                               ; 6 after the second
+        (:outputp () (lambda (x) (= x 7))))    ; and 7 after the third
+      :end
+      (incf *count*))
+#+end_src
+    
+The ~:with-stubs~ form is similar, except that it binds temporary
+values to functions that might be called by the form in
+questions. Useful for mocking.
+
+#+begin_src lisp
+
+
+    (defun just-a-function ()
+      (print "Just a function."))
+    
+    (defun/t call-just-a-function ()
+      "Calls JUST-A-FUNCTION."
+      :tests
+      (:with-stubs ((just-a-function () (print "TEMP JUST-A-FUNCTION.")))
+        (equal () "TEMP JUST-A-FUNCTION."))
+      :end
+      (just-a-function))
+
+#+end_src
+      
+In the above, the temporary redefinition of ~JUST-A-FUNCTION~ is used.
+