From eedfcb237f0ab49fac63c806625aedba25f0847d Mon Sep 17 00:00:00 2001 From: Colin Okay Date: Wed, 7 Sep 2022 10:30:25 -0500 Subject: Del: README.md --- README.md | 146 -------------------------------------------------------------- 1 file changed, 146 deletions(-) delete mode 100644 README.md diff --git a/README.md b/README.md deleted file mode 100644 index 3f27f87..0000000 --- a/README.md +++ /dev/null @@ -1,146 +0,0 @@ -A [testiere](https://www.vocabulary.com/dictionary/testiere) is armor -for the head of a horse. - -Testiere is a Common Lisp library for putting "protection" (tests) in -the "head" of functions. - -# testiere - -Embed tests inside function defintions. Tests are run when you compile -a function, signalling errors when they fail. Great for running tests -during interactive development! - -A work in progress. But here is the basic idea: - - (defun/t sum-3 (x y &key (z 10)) - "Sums three numbers, Z has a default value of 10" - :tests - (= (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)) - - -Here we define a function with four embedded tests. If any of these -tests fail, *the function is not defined*. If the funtion is already -defined, it is not redefined. - -## basic tests - -The most basic tests look like - - (COMPARATOR (ARG1 ARG2 ...) VALUE) - -Which will call the function with the provided arguments are compare -it to a VALUE. - -For example, `(>= (1 2 :z 1) -5)` runs the test - - (assert (>= (sum-3 1 2 :z 1) -5)) - - -## additional tests - - -In addition to basic assertions on the output of functions, testire -supports more elaborate vocubulary for embedding tests. Most of these look -like: - - (KEYWORD (ARG1 ARG2 ...) TERM) - -Where `TERM` varies according to the `KEYWORD` supplied. - -A few of these are - -- `(:program FUNCTION-NAME ARGS...)` runs a funcion 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. - - -## Stubs and Bindings - -Tests can also embed bindings or mock-functions aka stubs. - -Binding variables looks like - - (:with-bindings LET-BINDINGS TESTS) - -and are useful for binding dynamic variables for use during a set of -tests. - -For example - - (defvar *count*) - - (defun/t increment-count () - "Increments the *count* variable." - :tests - (:with-bindings ((*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*)) - -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. - - (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)) - -In the above, the temporary redefinition of JUST-A-FUNCTION is used. - - -## `WITH-STUBS` and `:PROGRAM` Style Tests - -By using the `:program` test and the `with-stubs` macro, you can -define just about any kind of test. In the following, you use -`with-stubs` to mock a function that makes an http request and returns -a string. - -It is assumed that `make-drakma-request` is defined somewhere else and -performs some network IO. It is stubbed here so that we do not need to -actually access the network. - - - (defun test-url-word-counter () - "Stub the function that makes requests that word-counter uses, and then test word counter." - (with-stubs - ((make-drakma-request () "one two three four five six seven")) - (assert (= (count-words) 7)))) - - (defun/t count-words () - "Fetches a url and counts now many words the page contains." - :tests - (:program test-url-word-counter) - :end - (let ((fetched - (make-drakma-request))) - (1+ (count #\space fetched)))) - - -If `test-url-word-counter` fails, `count-words` isn't defined. -- cgit v1.2.3