tools.test.fuzz: add documentation

diff --git a/basis/tools/test/fuzz/fuzz-docs.factor b/basis/tools/test/fuzz/fuzz-docs.factor
new file mode 100644 (file)
index 0000000..23a46e4
--- /dev/null
+++ b/basis/tools/test/fuzz/fuzz-docs.factor
@@ -0,0 +1,46 @@
+! Copyright (C) 2023 Raghu Ranganathan.
+! See https://factorcode.org/license.txt for BSD license.
+USING: help.markup help.syntax kernel namespaces ;
+IN: tools.test.fuzz
+
+HELP: fuzz-test
+{ $syntax "[ generator ] [ predicate ] fuzz-test " }
+{ $description "A fuzz test trial is run by generating a set of inputs from the generator"
+    " quotation and checking the properties of those inputs using the predicate quotation."
+    $nl
+    "The number of fuzz test trials that are run is indicated by " { $link fuzz-test-trials } "." } ;
+
+HELP: fuzz-test-failures
+{ $values
+    { "generator" object } { "predicate" object }
+    { "failures" object }
+}
+{ $description "Similar to " { $link \ fuzz-test } ", but returns a list of failing inputs generated by the "
+    { $snippet "generator" } " quotation." } ;
+
+HELP: fuzz-test-failures*
+{ $values
+    { "trials" object } { "generator" object } { "predicate" object }
+    { "failures" object }
+}
+{ $description "Similar to " { $link \ fuzz-test } ", but with a number of " { $snippet "trials" } " specified. "
+    "Returns a list of failing inputs generated by the "
+    { $snippet "generator" } " quotation." } ;
+
+HELP: fuzz-test-trials
+{ $var-description "Indicates the number of trials to run for any " { $link \ fuzz-test } " definition."
+    $nl
+    "Often used with " { $link with-variable } "."
+} ;
+
+ARTICLE: "tools.test.fuzz" "Fuzz Testing"
+{ $vocab-link "tools.test.fuzz" } " provides a single word " { $link \ fuzz-test } " that can be used alongside "
+{ $link "tools.test" } " definitions."
+$nl
+"The goal of fuzz testing is to check randomly generated, potentially erroneous "
+"inputs for specific traits when run through a program. Factor's fuzz testing support takes a generator quotation, and a predicate "
+"quotation, running 100 trials by default. You can set the number of trials using the " { $link fuzz-test-trials }
+" symbol."
+;
+
+ABOUT: "tools.test.fuzz"