docs/manual.txt

   1 = FiveAM Manual =
   2 Marco Baringer <mb@bese.it>
   3 Fall/Winter 2012
   4 :Author Initials: MB
   5 :toc:
   6 :icons:
   7 :numbered:
   8 :website: http://common-lisp.net/project/fiveam
   9 :stylesheet: fiveam.css
  10 :linkcss:
  11
  12 == Introduction ==
  13
  14 === The Super Brief Introduction ===
  15
  16 |================================
  17 | (xref:OP_DEF-TEST[`def-test`] `NAME` () &body `BODY`) | define tests
  18 | (xref:OP_IS[`is`] (`PREDICATE` `EXPECTED` `ACTUAL`)) | check that, according to `PREDICATE` our `ACTUAL` is the same as our `EXPECTED`
  19 | (xref:OP_IS[`is-true`] VALUE) | check that a value is non-NIL
  20 | (xref:OP_RUN![`run!`] TEST-NAME) | run one (or more) tests and print the results
  21 |================================
  22
  23 See the xref:API_REFERENCE[api] for details.
  24
  25 === An Ever So Slightly Longer Introduction ===
  26
  27 You use define some xref:TESTS[tests] (using
  28 xref:OP_DEF-TEST[`def-test`]), each of which consists of some
  29 xref:CHECKS[checks] (with xref:OP_IS[`is`] and friends) which can pass
  30 or fail:
  31
  32 --------------------------------
  33 (def-test a-test ()
  34   (is (= 4 (+ 2 2)))
  35   (is-false (= 5 (+ 2 2))))
  36 --------------------------------
  37
  38 you xref:RUNNING_TESTS[run] some tests (using xref:OP_RUN[run] and
  39 friends) and you look at the results (using using
  40 xref:OP_EXPLAIN[explain]); or you do both at once (using
  41 xref:OP_RUN-EPOINT-[run!]):
  42
  43 --------------------------------
  44 CL-USER> (run! 'a-test)
  45 ..
  46 Did 2 checks.
  47   Pass: 2 (100%)
  48   Skip: 0 (  0%)
  49   Fail: 0 (  0%)
  50 --------------------------------
  51
  52 Lather, rinse, repeat:
  53
  54 --------------------------------
  55 CL-USER> (run!)
  56 ..
  57 Did 2 checks.
  58   Pass: 2 (100%)
  59   Skip: 0 (  0%)
  60   Fail: 0 (  0%)
  61 --------------------------------
  62
  63 === The Real Introduction ===
  64
  65 FiveAM is a testing framework, this is a rather vague concept, so
  66 before talking about how to use FiveAM it's worth knowing what task(s)
  67 FiveAM was built to do and, in particular, which styles of testing
  68 FiveAM was designed to facilitate:
  69
  70 `test driven development`:: sometimes you know what you're trying to
  71   do (lucky you) and you can figure out what your code should do
  72   before you've written the code itself. The idea here is that you
  73   write a bunch of tests and when all these test pass your code is
  74   done.
  75
  76 `interactive testing`:: sometimes as you're writing code you'll see
  77   certain constraints that your code has to meet. For example you'll
  78   realize there's a specific border case your code, which you're
  79   probably not even done writing, has to deal with. In this work flow
  80   you'll write code and tests more or less simultaneously and by the
  81   time you're satisfied that your code does what it should you'll have
  82   a set of tests which prove that it does what you think it does.
  83
  84 `regression testing`:: sometimes you're pretty confident, just by
  85   looking at the code, that your program does what it should, but you
  86   want an automatic way to make sure that it continues to do what it
  87   does even if (when) you change other parts of the code.
  88
  89 [NOTE]
  90 There's also `beaviour driven development`. this works under
  91 the assumption that you can write tests in a natural-ish lanugage and
  92 they'll be easier to maintain than tests writen in code (have we
  93 learned nothing from cobol?). FiveAM does not, in its current
  94 implementation, support link:http://cukes.info/[cucumber] like
  95 behaviour driven development. patches welcome (they'll get laughed at
  96 at first, but they'll get applied, and then they'll get used, and then
  97 they'll be an essential part of fiveam itself...)
  98
  99 ==== Words ====
 100
 101 Since there are far many more testing frameworks than there are words
 102 for talking about testing frameworks, the same words end up meaning
 103 different things in different frameworks. Just to be clear, here are
 104 the words fiveam uses:
 105
 106 `check`:: a single expression which has an expected value.
 107
 108 `test`:: a set of checks which we want to always run together.
 109
 110 `suite`:: a group of tests we often want to run all at once.
 111
 112 [[TESTS]]
 113 == Tests ==
 114
 115 Tests are created with the xref:OP_DEF-TEST[`def-test`] macro and
 116 consist of:
 117
 118 A name::
 119
 120 Because everything deserves a name. Names in FiveAM are symbols (or
 121 anything that can be sensibly put in an `eql` hash table) and they are
 122 used both to select which test to run (as arguments to `run!` and
 123 family) and when reporting test failures.
 124
 125 A body::
 126
 127 Every test has a function which is the actual code that gets executed
 128 when the test is run. This code, whatever it is, will, bugs aside,
 129 xref:CHECKS[create a set of test result objects] (failures, successes
 130 and skips) and store these in a few dynamic variables (you don't need
 131 to worry about those).
 132 +
 133 The body is actually the only real part of the test, everything else
 134 is administrativia. Sometimes usefel administrativia, but none the
 135 less overhead.
 136
 137 A suite::
 138
 139 Generally speaking you'll have so many tests that you'll not want to
 140 run them all every single time you need to run one of them (automated
 141 regression testing is another use case). Tests can be grouped into
 142 suites, and suites can also be grouped into suites, and suites have
 143 names, so by specfying the name of a suite we only run those tests
 144 that are a part of that suite.
 145 +
 146 Unless otherwise specified tests add themselves to the xref:THE_CURRENT_SUITE[current suite].
 147
 148 There are two other properties, also set via parameters to
 149 xref:OP_DEF-TEST[`def-test`], which influence how the tests are
 150 run:
 151
 152 When to compile the test::
 153
 154 Often enough, when working with lisp macros especially, it's useful to
 155 delay compilation of the test's body until the test is run. A useful
 156 side effect of this delay is that the code will be recompiled every
 157 time its run, so if the macro definition has changed that will be
 158 picked up at the next run of the test. While this is the default mode
 159 of operation for FiveAM it can be turned off and tests will be
 160 compiled at the 'normal' time (when the enclosing def-test form is
 161 compiled).
 162
 163 Whether to run the test at all::
 164
 165 Sometimes, but far less often than the designer of FiveAM expected,
 166 it's useful to run a test only when some other test passes. The
 167 assumption being that if the lower level tests have failed there's no
 168 point in cluttering up the output by running the higher level tests as
 169 well.
 170 +
 171 YMMV. (i got really bad mileage out of this feature)
 172
 173 [[CHECKS]]
 174 == Checks ==
 175
 176 At the heart of every test is something which compares the result of
 177 some code to some expected value, in FiveAM these are called
 178 checks. All checks in FiveAM do something, exactly what depends on the
 179 check, and then either:
 180
 181 . generate a "this check passed" result
 182
 183 . generate a "this check failed" result and a corresponding failure
 184   description message.
 185
 186 . generate a "for some reason this check was skipped" result.
 187
 188 All checks take, as an optional argument, so called "reason format
 189 control arguments." Should the check fail (or be skipped) these
 190 arguments will be passed to format, via something like `(curry
 191 #'format nil)`, and the result will be used as the
 192 explanation/description of the failure.
 193
 194 When it comes to the actual check functions themeselves, there are
 195 three basic kinds:
 196
 197 . xref:CHECKING_RETURN_VALUES[those that take a value and compare it
 198 to another value]
 199
 200 . xref:CHECKING_CONTROL_FLOW[those that make sure the program's
 201 execution takes, or does not take, a certain path]
 202
 203 . xref:ARBITRARY_CHECK_RESULTS[those that just force a success or
 204 failure to be recorded].
 205
 206 [[CHECKING_RETURN_VALUES]]
 207 === Checking return values ===
 208
 209 xref:OP_IS[`IS`], xref:OP_IS-TRUE[`IS-TRUE`],
 210 xref:OP_IS[`IS-FALSE`] will take one form and compare its return
 211 value to some known value (the so called expected vaule) and report an
 212 error if these two are not equal.
 213
 214 --------------------------------
 215 ;; Pass if (+ 2 2) is = to 5
 216 (is (= 5 (+ 2 2)))
 217 ;; Pass if (zerop 0) is not-NIL
 218 (is-true (zerop 0))
 219 ;; Pass if (zerop 1) is NIL
 220 (is-false (zerop 1))
 221 --------------------------------
 222
 223 Often enough we want to test a set of expected values against a set of
 224 test values using the same operator. If, for example, we were
 225 implementing a string formatting functions, then `IS-EVERY` provides a
 226 concise way to line up N different inputs along with their expected
 227 outputs. For example, let's say we were testing `cl:+`, we could setup
 228 a list of tests like this:
 229
 230 --------------------------------
 231 (is-every #'= (5 (+ 2 2))
 232               (0 (+ -1 1))
 233               (-1 (+ -1 0))
 234               (1 (+ 0 1))
 235               (1 (+ 1 0)))
 236 --------------------------------
 237
 238 We'd do this instead of writing out 5 seperate `IS` or `IS-TRUE`
 239 checks.
 240
 241 [[CHECKING_CONTROL_FLOW]]
 242 === Checking control flow ===
 243
 244 xref:OP_SIGNALS[`SIGNALS`] and xref:OP_FINISHES[`FINISHES`] create
 245 pass/fail results depending on whether their body code did or did not
 246 terminat normally.
 247
 248 Both of these checks assume that there is a single block of code and
 249 it either runs to completion or it doesn't. Sometimes though the logic
 250 is more complex and you can't easily represent it as a single progn
 251 with a flag at the end. See xref:ARBITRARY_CHECK_RESULTS[below].
 252
 253 [[ARBITRARY_CHECK_RESULTS]]
 254 === Recording arbitrary test results ===
 255
 256 Very simply these three checks, xref:OP_PASS[`PASS`],
 257 xref:OP_FAIL[`FAIL`] and xref:OP_SKIP[`SKIP`] generate the specified
 258 result. They're intended to be used when what we're trying to test
 259 doesn't quite fit into any of the two preceding ways of working.
 260
 261 == Suites ==
 262
 263 Suites serve to group tests into managable (and runnable) chunks, they
 264 make it easy to have many tests defined, but only run those that
 265 pertain to what we're currently working on. Suites, like tests, have a
 266 name which can be used to retrieve the suite, and running a suite
 267 simply causes all of the suite's tests to be run, if the suite
 268 contains other suites, then those are run as well (and so on and so
 269 on).
 270
 271 There is one suite that's a little special (in so far as it always
 272 exists), the `T` suite. If you ignore suites completely, which is a
 273 good idea at first or for small(ish) code bases, you're actually
 274 putting all your tests into the `T` suite.
 275
 276 === Creating Suites ===
 277
 278 Suites are created in one of two ways: Either explicitly via the
 279 xref:OP_DEF-SUITE[`def-suite`] macro, or implicity via the
 280 xref:OP_DEF-SUITE-STAR-[`def-suite*`] and/or
 281 xref:OP_IN-SUITE-STAR-[`in-suite*`] macros:
 282
 283 Suites, very much like tests, have a name (which is globally unique)
 284 which can be used to retrieve the suite (so that you can run it), and,
 285 most of the time, suites are part of a suite (the exception being the
 286 special suite `T`, which is never a part of any suite).
 287
 288 For example these two forms will first define a suite called
 289 `:my-project`, then define a second suite called `:my-db-layer`, which
 290 is a sub suite of `:my-project` and set the current suite to
 291 `:my-db-layer`:
 292
 293 --------------------------------
 294 (def-suite :my-project)
 295
 296 (in-suite* :my-db-layer :in :my-project)
 297 --------------------------------
 298
 299 [[THE_CURRENT_SUITE]]
 300 === The Current Suite ===
 301
 302 FiveAM also has the concept of a current suite and everytime a test is
 303 created it adds itself to the current suite's set of tests. The
 304 `IN-SUITE` and `IN-SUITE*` macros, in a similar fashion to
 305 `IN-PACKAGE`, change the current suite.
 306
 307 Unless changed via `IN-SUITE` and `IN-SUITE*` the current suite is the
 308 `T` suite.
 309
 310 Having a default current suite allows developers to ignore suites
 311 completly and still have FiveAM's suite mechanism in place if they
 312 want to add suites in later.
 313
 314 [[RUNNING_SUITES]]
 315 === Running Suites ===
 316
 317 When a suite is run we do nothing more than run all the tests (and any
 318 other suites) in the named suite. And, on one level, that's it, suites
 319 allow you run a whole set of tests at once just by passing in the name
 320 of the suite.
 321
 322 [[SUITE_FIXTURES]]
 323 === Per-suite Fixtures ===
 324
 325 xref:FIXTURES[Fixtures] can also be associated with suite. Often
 326 enough when testing an external component, a database or a network
 327 server or something, we'll have multiple tests which all use a mock
 328 version of this component. It is often easier to associate the fixture
 329 with the suite directly than have to do this for every individual
 330 test. Associating a fixture to a suite doesn't change the suite at
 331 all, only when a test is then defined in that suite, then the fixture
 332 will be applied to the test's body (unless the test's own `def-test`
 333 form explicitly uses another fixture).
 334
 335 [[RUNNING_TESTS]]
 336 == Running Tests ==
 337
 338 The general interface is `run`, this takes a set of tests (or symbol
 339 that name tests or suites) and returns a list of test results (one
 340 element for each check that was executed). The output of `run` is,
 341 generally, passed to the `explain` function which, given an explainer
 342 object, produces some human readable text describing the test
 343 failures. The 99% of the time a human will be using 5am (as opposed to
 344 a continuous integration bot) they'll want to run the tests and
 345 immediately see the results with detailed failure info, this can be
 346 done in one step via: `run!` (see the first example).
 347
 348 If you want to run a specific test:
 349
 350 --------------------------------
 351 (run! TEST-NAME)
 352 --------------------------------
 353
 354 Where `TEST-NAME` is either a test object (as returned by `get-test`)
 355 or a symbol naming a single test or a test suite.
 356
 357 === Running Tests at Test Definition Time ===
 358
 359 Often enough, especially when fixing regression bugs, we'll always
 360 want to run a test right after having changed it. To facilitate this
 361 set the variable `*run-test-when-defined*` to T and after compiling a
 362 def-test form we'll call `run!` on the name of the test. For obvious
 363 reasons you have to set this variable manually after having loaded
 364 your test suite.
 365
 366 === Debugging failures and errors ===
 367
 368 `*debug-on-error*`::
 369
 370 Normally fiveam will simply capture unexpected errors, record them as
 371 failures, and move on to the next test (any following checks in the
 372 test body will not be run). However sometimes, well, all the time
 373 unless you're running an automated regression test, it's better to not
 374 capture the error but open up a debugger, set `*debug-on-error*` to
 375 `T` to get this effect.
 376
 377 `*debug-on-failure*`::
 378
 379 Normally FiveAM will simply record a check failure and move on to the
 380 next check, however it can be helpful to stop the check and use the
 381 debugger to see what the state of execution is at the time of the
 382 test's failure. Setting `*debug-on-failure*` to T will cause FiveAM to
 383 enter the debugger whenever a test check fails. Exactly what
 384 information is available is, obviously, implementation dependent.
 385
 386 [[VIEWING_TEST_RESULTS]]
 387 == Viewing test results ==
 388
 389 FiveAM provides two "explainers", these are classes which, given a set
 390 of results, produce some human readable/understandable
 391 output. Explainers are just normal CLOS classes (and can be easily
 392 subclassed) with one important method: `explain`.
 393
 394 The `run!` and `explain!` functions use the detailed-text-explainer,
 395 if you want another explainer you'll have to call `run` and `explain`
 396 yourself:
 397
 398 --------------------------------
 399 (explain (make-instance MY-EXPLAINER)
 400          (run THE-TEST)
 401          THE-STREAM)
 402 --------------------------------
 403
 404 == Random Testing (QuickCheck) ==
 405
 406 Sometimes it's hard to come up with edge cases for tests, or sometimes
 407 there are so many that it's hard to list them all one by one. Random
 408 testing is a way to tell the test suite how to generate input and how
 409 to test that certain conditions always hold. One issue when writing
 410 random tests is that you can't, usually, test for specific results,
 411 you have to test that certain relationships hold.
 412
 413 For example, if we had a function which reverses a list, we could
 414 define a relationship like this:
 415
 416 --------------------------------
 417 (equalp the-list (reverse (reverse the-list)))
 418 --------------------------------
 419
 420 or
 421
 422 --------------------------------
 423 (equalp (length the-list) (length (reverse the-list)))
 424 --------------------------------
 425
 426 Random tests are defined via `def-test`, but the random part is then
 427 wrapped in a xref:OP_FOR-ALL[`for-all`] macro which runs its body
 428 `*num-trials*` times with different inputs:
 429
 430 --------------------------------
 431 (for-all ((the-list (gen-list :length (gen-integer :min 0 :max 37)
 432                               :elements (gen-integer :min -10 :max 10))))
 433   (is (equalp a (reverse (reverse the-list))))
 434   (is (= (length the-list) (length (reverse the-list)))))
 435 --------------------------------
 436
 437 == Fixtures ==
 438
 439 Fixtures are, much like macros, ways to hide common code so that the
 440 essential functionality we're trying to test is easier to see. Unlike
 441 normal macros fixtures are not allowed to inspect the source code of
 442 their arguments, all they can really do is wrap one form (or multiple
 443 forms in a progn) in something else.
 444
 445 [NOTE]
 446 Fixtures exist for the common case where we want to bind some
 447 variables to some mock (or test) values and run our test in this
 448 state. If anything more complicated than this is neccessary just use a
 449 normal macro.
 450
 451 Fixtures are defined via the `def-fixture` macro and used either with
 452 `with-fixture` directory or, more commonly, using the `:fixture`
 453 argument to `def-test` or `def-suite`. A common example of a fixture
 454 would be this:
 455
 456 --------------------------------
 457 (def-fixture mock-db ()
 458   (let ((*database* (make-instance 'mock-db))
 459         (*connection* (make-instance 'mock-connection)))
 460     (unwind-protect
 461         (&body) <1>
 462       (mock-close-connection *connection*))))
 463
 464 (with-fixture mock-db ()
 465   (is-true (database-p *database*)))
 466
 467 <1> This is a local macro named 5AM:&BODY (the user of def-fixture can
 468 not change this name)
 469
 470 --------------------------------
 471
 472 The body of the `def-fixture` has one local function (actually a local
 473 macro) called `&body` which will expand into whatever the body passed
 474 to `with-fixture` is. `def-fixture` also has an argument list, but
 475 there are two things to note: 1) in practice it's rarely used; 2)
 476 these are arguments will be bound to values (like defun) and not
 477 source code (like defmacro).
 478
 479 [[API_REFERENCE]]
 480 == API Reference ==
 481
 482 [[OP_DEF-TEST]]
 483 === DEF-TEST ===
 484
 485 ================================
 486 --------------------------------
 487 (def-test NAME (&key DEPENDS-ON SUITE FIXTURE COMPILE-AT PROFILE) &body BODY)
 488 --------------------------------
 489
 490 include::docstrings/OP_DEF-TEST.txt[]
 491 ================================
 492
 493 [[OP_DEF-SUITE]]
 494 === DEF-SUITE ===
 495
 496 ================================
 497 ----
 498 (def-suite NAME &key DESCRIPTION IN FIXTURE)
 499 ----
 500
 501 include::docstrings/OP_DEF-SUITE.txt[]
 502 ================================
 503
 504 [[OP_IN-SUITE]]
 505 [[OP_IN-SUITE-STAR-]]
 506 === IN-SUITE / IN-SUITE* ===
 507
 508 ================================
 509 ----
 510 (in-suite NAME)
 511 ----
 512
 513 include::docstrings/OP_IN-SUITE.txt[]
 514 ================================
 515
 516 ================================
 517 ----
 518 (in-suite* NAME &key IN)
 519 ----
 520
 521 include::docstrings/OP_IN-SUITE-STAR-.txt[]
 522 ================================
 523
 524 [[OP_IS]]
 525 === IS ===
 526
 527 ================================
 528 ----
 529 (is (PREDICATE EXPECTED ACTUAL) &rest REASON-ARGS)
 530
 531 (is (PREDICATE ACTUAL) &rest REASON-ARGS)
 532 ----
 533
 534 include::docstrings/OP_IS.txt[]
 535 ================================
 536
 537 [[OP_IS-TRUE]]
 538 [[OP_IS-FALSE]]
 539 === IS-TRUE / IS-FALSE / IS-EVERY ===
 540
 541 ================================
 542 ----
 543 (is-true CONDITION &rest reason)
 544 ----
 545
 546 include::docstrings/OP_IS-TRUE.txt[]
 547 ================================
 548
 549 ================================
 550 ----
 551 (is-false CONDITION &rest reason)
 552 ----
 553
 554 include::docstrings/OP_IS-FALSE.txt[]
 555 ================================
 556
 557 ////////////////////////////////
 558 //// the actual doc string of talks about functionality i don't want
 559 //// to publises (since it's just weird). se we use our own here
 560 ////////////////////////////////
 561 ================================
 562 ----
 563 (is-every predicate &rest (EXPECTED ACTUAL &rest REASON))
 564 ----
 565
 566 Designed for those cases where you have a large set of expected/actual
 567 pairs that must be compared using the same predicate function.
 568
 569 Expands into:
 570
 571 ----
 572 (progn
 573   (is (,PREDICATE ,EXPECTED ,ACTUAL) ,@REASON)
 574   ...
 575 ----
 576
 577 for each argument.
 578 ================================
 579
 580 [[OP_SIGNALS]]
 581 [[OP_FINISHES]]
 582 === SIGNALS / FINISHES ===
 583
 584 ================================
 585 ----
 586 (signals CONDITION &body body)
 587 ----
 588
 589 include::docstrings/OP_SIGNALS.txt[]
 590 ================================
 591
 592 ================================
 593 ----
 594 (finishes &body body)
 595 ----
 596
 597 include::docstrings/OP_FINISHES.txt[]
 598 ================================
 599
 600 [[OP_PASS]]
 601 [[OP_FAIL]]
 602 [[OP_SKIP]]
 603 === PASS / FAIL / SKIP ===
 604
 605 ================================
 606 ----
 607 (skip &rest REASON-ARGS)
 608 ----
 609
 610 include::docstrings/OP_SKIP.txt[]
 611 ================================
 612
 613 ================================
 614 ----
 615 (pass &rest REASON-ARGS)
 616 ----
 617
 618 include::docstrings/OP_PASS.txt[]
 619 ================================
 620
 621 ================================
 622 ----
 623 (fail &rest REASON-ARGS)
 624 ----
 625
 626 include::docstrings/OP_FAIL.txt[]
 627 ================================
 628
 629 [[OP_-EPOINT-]]
 630 [[OP_-EPOINT--EPOINT-]]
 631 [[OP_-EPOINT--EPOINT--EPOINT-]]
 632
 633 [[OP_RUN-EPOINT-]]
 634 [[OP_EXPLAIN-EPOINT-]]
 635 [[OP_DEBUG-EPOINT-]]
 636 === RUN! / EXPLAIN! / DEBUG! ===
 637
 638 ================================
 639 ----
 640 (run! &optional TEST-NAME)
 641 ----
 642
 643 include::docstrings/OP_RUN-EPOINT-.txt[]
 644 ================================
 645
 646 ================================
 647 ----
 648 (explain! RESULT-LIST)
 649 ----
 650
 651 include::docstrings/OP_EXPLAIN-EPOINT-.txt[]
 652 ================================
 653
 654 ================================
 655 ----
 656 (debug! TEST-NAME)
 657 ----
 658
 659 include::docstrings/OP_DEBUG-EPOINT-.txt[]
 660 ================================
 661
 662 [[OP_RUN]]
 663 === RUN ===
 664
 665 ================================
 666 ----
 667 (run TEST-SPEC)
 668 ----
 669
 670 include::docstrings/OP_RUN.txt[]
 671 ================================
 672
 673 [[OP_DEF-FIXTURE]]
 674 === DEF-FIXTURE ===
 675
 676 ================================
 677 ----
 678 (def-fixture (NAME (&rest ARGS) &body BODY)
 679 ----
 680
 681 include::docstrings/OP_DEF-FIXTURE.txt[]
 682 ================================
 683
 684 [[OP_WITH-FIXTURE]]
 685 === WITH-FIXTURE ===
 686
 687 ================================
 688 ----
 689 (with-fixture NAME (&rest ARGS) &body BODY)
 690 ----
 691
 692 include::docstrings/OP_WITH-FIXTURE.txt[]
 693 ================================
 694
 695 [[OP_FOR-ALL]]
 696 === FOR-ALL ===
 697
 698 ================================
 699 --------------------------------
 700 (for-all (&rest (NAME VALUE &optional GUARD))
 701   &body body)
 702 --------------------------------
 703
 704 include::docstrings/OP_FOR-ALL.txt[]
 705 ================================
 706
 707 [[VAR_-STAR-NUM-TRIALS-STAR-]]
 708 [[VAR_-STAR-MAX-TRIALS-STAR-]]
 709 === \*NUM-TRIALS* / \*MAX-TRIALS* ===
 710
 711 ================================
 712 ----
 713 *num-trials*
 714 ----
 715
 716 include::docstrings/VAR_-STAR-NUM-TRIALS-STAR-.txt[]
 717 ================================
 718
 719 ================================
 720 ----
 721 *max-trials*
 722 ----
 723
 724 include::docstrings/VAR_-STAR-MAX-TRIALS-STAR-.txt[]
 725 ================================
 726
 727 [[OP_GEN-INTEGER]]
 728 [[OP_GEN-FLOAT]]
 729 === GEN-INTEGER / GEN-FLOAT ===
 730
 731 ================================
 732 ----
 733 (gen-integer &key MIN MAX)
 734 ----
 735
 736 include::docstrings/OP_GEN-INTEGER.txt[]
 737 ================================
 738
 739 ================================
 740 ----
 741 (gen-float &key BOUND TYPE MIN MAX)
 742 ----
 743
 744 include::docstrings/OP_GEN-FLOAT.txt[]
 745 ================================
 746
 747 [[OP_GEN-CHARACTER]]
 748 [[OP_GEN-STRING]]
 749 === GEN-CHARACTER / GEN-STRING ===
 750
 751 ================================
 752 ----
 753 (gen-character &key CODE-LIMIT CODE ALPHANUMERICP)
 754 ----
 755
 756 include::docstrings/OP_GEN-CHARACTER.txt[]
 757 ================================
 758
 759 ================================
 760 ----
 761 (gen-string &key LENGTH ELEMENTS)
 762 ----
 763
 764 include::docstrings/OP_GEN-STRING.txt[]
 765 ================================
 766
 767 [[OP_GEN-BUFFER]]
 768 === GEN-BUFFER ===
 769
 770 ================================
 771 ----
 772 (gen-buffer &key LENGTH ELEMENTS ELEMENT-TYPE)
 773 ----
 774
 775 include::docstrings/OP_GEN-STRING.txt[]
 776 ================================
 777
 778 [[OP_GEN-LIST]]
 779 [[OP_GEN-TREE]]
 780 === GEN-LIST / GEN-TREE ===
 781
 782 ================================
 783 ----
 784 (gen-list &key LENGTH ELEMENTS)
 785 ----
 786
 787 include::docstrings/OP_GEN-LIST.txt[]
 788 ================================
 789
 790 ================================
 791
 792 ----
 793 (gen-tree &key SIZE ELEMENTS)
 794 ----
 795
 796 include::docstrings/OP_GEN-TREE.txt[]
 797 ================================
 798
 799 [[OP_GEN-ONE-ELEMENT]]
 800 === GEN-ONE-ELEMENT ===
 801
 802 ================================
 803 ----
 804 (gen-one-element &rest ELEMENTS)
 805 ----
 806
 807 include::docstrings/OP_GEN-ONE-ELEMENT.txt[]
 808 ================================
 809
 810
 811
 812 ////////////////////////////////
 813
 814 ////////////////////////////////