Remove in-suite* and def-suite*.

[fiveam.git] / docs / manual.txt

diff --git a/docs/manual.txt b/docs/manual.txt
index ee7b77d..a059f53 100644 (file)
--- a/docs/manual.txt
+++ b/docs/manual.txt
@@ -275,11 +275,6 @@ putting all your tests into the `T` suite.
 
 === Creating Suites ===
 
-Suites are created in one of two ways: Either explicitly via the
-xref:OP_DEF-SUITE[`def-suite`] macro, or implicity via the
-xref:OP_DEF-SUITE-STAR-[`def-suite*`] and/or
-xref:OP_IN-SUITE-STAR-[`in-suite*`] macros:
-
 Suites, very much like tests, have a name (which is globally unique)
 which can be used to retrieve the suite (so that you can run it), and,
 most of the time, suites are part of a suite (the exception being the
@@ -293,7 +288,9 @@ is a sub suite of `:my-project` and set the current suite to
 --------------------------------
 (def-suite :my-project)
 
-(in-suite* :my-db-layer :in :my-project)
+(def-suite :my-db-layer :in :my-project)
+
+(in-suite :my-db-layer)
 --------------------------------
 
 [[THE_CURRENT_SUITE]]
@@ -301,10 +298,8 @@ is a sub suite of `:my-project` and set the current suite to
 
 FiveAM also has the concept of a current suite and everytime a test is
 created it adds itself to the current suite's set of tests. The
-`IN-SUITE` and `IN-SUITE*` macros, in a similar fashion to
-`IN-PACKAGE`, change the current suite.
-
-Unless changed via `IN-SUITE` and `IN-SUITE*` the current suite is the
+`IN-SUITE` macro, in a similar fashion to `IN-PACKAGE`, changes the
+current suite. Unless changed via `IN-SUITE` the current suite is the
 `T` suite.
 
 Having a default current suite allows developers to ignore suites
@@ -403,9 +398,36 @@ yourself:
 
 == Random Testing (QuickCheck) ==
 
-TODO.
+Sometimes it's hard to come up with edge cases for tests, or sometimes
+there are so many that it's hard to list them all one by one. Random
+testing is a way to tell the test suite how to generate input and how
+to test that certain conditions always hold. One issue when writing
+random tests is that you can't, usually, test for specific results,
+you have to test that certain relationships hold. 
+
+For example, if we had a function which reverses a list, we could
+define a relationship like this:
+
+--------------------------------
+(equalp the-list (reverse (reverse the-list)))
+--------------------------------
+
+or
+
+--------------------------------
+(equalp (length the-list) (length (reverse the-list)))
+--------------------------------
+
+Random tests are defined via `def-test`, but the random part is then
+wrapped in a xref:OP_FOR-ALL[`for-all`] macro which runs its body
+`*num-trials*` times with different inputs:
 
-Every FiveAM test can be a random test, just use the for-all macro.
+--------------------------------
+(for-all ((the-list (gen-list :length (gen-integer :min 0 :max 37)
+                              :elements (gen-integer :min -10 :max 10))))
+  (is (equalp a (reverse (reverse the-list))))
+  (is (= (length the-list) (length (reverse the-list)))))
+--------------------------------
 
 == Fixtures ==
 
@@ -476,7 +498,7 @@ include::docstrings/OP_DEF-SUITE.txt[]
 
 [[OP_IN-SUITE]]
 [[OP_IN-SUITE-STAR-]]
-=== IN-SUITE / IN-SUITE* ===
+=== IN-SUITE ===
 
 ================================
 ----
@@ -486,14 +508,6 @@ include::docstrings/OP_DEF-SUITE.txt[]
 include::docstrings/OP_IN-SUITE.txt[]
 ================================
 
-================================
-----
-(in-suite* NAME &key IN)
-----
-
-include::docstrings/OP_IN-SUITE-STAR-.txt[]
-================================
-
 [[OP_IS]]
 === IS ===