From 526421d21a514dfbd190ae5956cbbb95035c0dc2 Mon Sep 17 00:00:00 2001 From: Marco Baringer Date: Sat, 8 Dec 2012 21:10:37 +0100 Subject: [PATCH] Put some code examples into the manual --- docs/Makefile.lisp | 2 +- docs/fiveam.css | 10 ++++++---- docs/manual.txt | 53 ++++++++++++++++++++++++++++++++++++++++++---------- 3 files changed, 50 insertions(+), 15 deletions(-) diff --git a/docs/Makefile.lisp b/docs/Makefile.lisp index 1bb2176..a831d8a 100644 --- a/docs/Makefile.lisp +++ b/docs/Makefile.lisp @@ -20,7 +20,7 @@ (target* `(static-file ,name) () (when (file-newer-p source destination) - (path:cp source destination)))) + (path:cp source destination :overwrite t)))) (static-file "asciidoc.css" (path:catfile *asciidoc-root* "stylesheets/" "asciidoc.css")) diff --git a/docs/fiveam.css b/docs/fiveam.css index 56b8cf9..7b40666 100644 --- a/docs/fiveam.css +++ b/docs/fiveam.css @@ -1,6 +1,8 @@ body { - width: 560px; - margin-left: auto; - margin-right: auto; - margin-top: 20px; + width: 42em; + margin-left: auto; + margin-right: auto; + margin-top: 20px; } + +h1, h2 { width: 30em; } \ No newline at end of file diff --git a/docs/manual.txt b/docs/manual.txt index aedfe12..8d4ed3f 100644 --- a/docs/manual.txt +++ b/docs/manual.txt @@ -13,18 +13,53 @@ Fall/Winter 2012 === The Super Brief Introduction === -FiveAM is a testing framework. See the xref:API_REFERENCE[api] for -details. +|================================ +| (xref:OP_DEF-TEST[`def-test`] `NAME` () &body `BODY`) | define tests +| (xref:OP_IS[`is`] (`PREDICATE` `EXPECTED` `ACTUAL`)) | check that, according to `PREDICATE` our `ACTUAL` is the same as our `EXPECTED` +| (xref:OP_IS[`is-true`] VALUE) | check that a value is non-NIL +| (xref:OP_RUN![`run!`] TEST-NAME) | run one (or more) tests and print the results +| (xref:OP_RUN![`!`]) | rerun the most recently run test. +|================================ + +See the xref:API_REFERENCE[api] for details. === An Ever So Slightly Longer Introduction === You use define some xref:TESTS[tests] (using xref:OP_DEF-TEST[`def-test`]), each of which consists of some xref:CHECKS[checks] (with xref:OP_IS[`is`] and friends) which can pass -or fail; you xref:RUNNING_TESTS[run] some tests (using -xref:OP_RUN-EPOINT-[run!] and friends) and you look at the results -(probably using xref:OP_RUN-EPOINT-[run!] again). Lather, rinse, -repeat. +or fail: + +-------------------------------- +(def-test a-test () + (is (= 4 (+ 2 2))) + (is-false (= 5 (+ 2 2)))) +-------------------------------- + +you xref:RUNNING_TESTS[run] some tests (using xref:OP_RUN[run] and +friends) and you look at the results (using using +xref:OP_EXPLAIN[explain]); or you do both at once (using +xref:OP_RUN-EPOINT-[run!]): + +-------------------------------- +CL-USER> (run! 'a-test) +.. +Did 2 checks. + Pass: 2 (100%) + Skip: 0 ( 0%) + Fail: 0 ( 0%) +-------------------------------- + +Lather, rinse, repeat: + +-------------------------------- +CL-USER> (!) +.. +Did 2 checks. + Pass: 2 (100%) + Skip: 0 ( 0%) + Fail: 0 ( 0%) +-------------------------------- === The Real Introduction === @@ -62,7 +97,7 @@ behaviour driven development. patches welcome (they'll get laughed at at first, but they'll get applied, and then they'll get used, and then they'll be an essential part of fiveam itself...) -=== Words === +==== Words ==== Since there are far many more testing frameworks than there are words for talking about testing frameworks, the same words end up meaning @@ -442,9 +477,7 @@ source code (like defmacro). ================================ -------------------------------- -(def-test NAME - (&key DEPENDS-ON SUITE FIXTURE COMPILE-AT PROFILE) - &body BODY) +(def-test NAME (&key DEPENDS-ON SUITE FIXTURE COMPILE-AT PROFILE) &body BODY) -------------------------------- include::docstrings/OP_DEF-TEST.txt[] -- 1.7.10.4