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, very much like tests, have a name (which is globally unique)
 279 which can be used to retrieve the suite (so that you can run it), and,
 280 most of the time, suites are part of a suite (the exception being the
 281 special suite `T`, which is never a part of any suite).
 282
 283 For example these two forms will first define a suite called
 284 `:my-project`, then define a second suite called `:my-db-layer`, which
 285 is a sub suite of `:my-project` and set the current suite to
 286 `:my-db-layer`:
 287
 288 --------------------------------
 289 (def-suite :my-project)
 290
 291 (def-suite :my-db-layer :in :my-project)
 292
 293 (in-suite :my-db-layer)
 294 --------------------------------
 295
 296 [[THE_CURRENT_SUITE]]
 297 === The Current Suite ===
 298
 299 FiveAM also has the concept of a current suite and everytime a test is
 300 created it adds itself to the current suite's set of tests. The
 301 `IN-SUITE` macro, in a similar fashion to `IN-PACKAGE`, changes the
 302 current suite. Unless changed via `IN-SUITE` the current suite is the
 303 `T` suite.
 304
 305 Having a default current suite allows developers to ignore suites
 306 completly and still have FiveAM's suite mechanism in place if they
 307 want to add suites in later.
 308
 309 [[RUNNING_SUITES]]
 310 === Running Suites ===
 311
 312 When a suite is run we do nothing more than run all the tests (and any
 313 other suites) in the named suite. And, on one level, that's it, suites
 314 allow you run a whole set of tests at once just by passing in the name
 315 of the suite.
 316
 317 [[SUITE_FIXTURES]]
 318 === Per-suite Fixtures ===
 319
 320 xref:FIXTURES[Fixtures] can also be associated with suite. Often
 321 enough when testing an external component, a database or a network
 322 server or something, we'll have multiple tests which all use a mock
 323 version of this component. It is often easier to associate the fixture
 324 with the suite directly than have to do this for every individual
 325 test. Associating a fixture to a suite doesn't change the suite at
 326 all, only when a test is then defined in that suite, then the fixture
 327 will be applied to the test's body (unless the test's own `def-test`
 328 form explicitly uses another fixture).
 329
 330 [[RUNNING_TESTS]]
 331 == Running Tests ==
 332
 333 The general interface is `run`, this takes a set of tests (or symbol
 334 that name tests or suites) and returns a list of test results (one
 335 element for each check that was executed). The output of `run` is,
 336 generally, passed to the `explain` function which, given an explainer
 337 object, produces some human readable text describing the test
 338 failures. The 99% of the time a human will be using 5am (as opposed to
 339 a continuous integration bot) they'll want to run the tests and
 340 immediately see the results with detailed failure info, this can be
 341 done in one step via: `run!` (see the first example).
 342
 343 If you want to run a specific test:
 344
 345 --------------------------------
 346 (run! TEST-NAME)
 347 --------------------------------
 348
 349 Where `TEST-NAME` is either a test object (as returned by `get-test`)
 350 or a symbol naming a single test or a test suite.
 351
 352 === Running Tests at Test Definition Time ===
 353
 354 Often enough, especially when fixing regression bugs, we'll always
 355 want to run a test right after having changed it. To facilitate this
 356 set the variable `*run-test-when-defined*` to T and after compiling a
 357 def-test form we'll call `run!` on the name of the test. For obvious
 358 reasons you have to set this variable manually after having loaded
 359 your test suite.
 360
 361 === Debugging failures and errors ===
 362
 363 `*debug-on-error*`::
 364
 365 Normally fiveam will simply capture unexpected errors, record them as
 366 failures, and move on to the next test (any following checks in the
 367 test body will not be run). However sometimes, well, all the time
 368 unless you're running an automated regression test, it's better to not
 369 capture the error but open up a debugger, set `*debug-on-error*` to
 370 `T` to get this effect.
 371
 372 `*debug-on-failure*`::
 373
 374 Normally FiveAM will simply record a check failure and move on to the
 375 next check, however it can be helpful to stop the check and use the
 376 debugger to see what the state of execution is at the time of the
 377 test's failure. Setting `*debug-on-failure*` to T will cause FiveAM to
 378 enter the debugger whenever a test check fails. Exactly what
 379 information is available is, obviously, implementation dependent.
 380
 381 [[VIEWING_TEST_RESULTS]]
 382 == Viewing test results ==
 383
 384 FiveAM provides two "explainers", these are classes which, given a set
 385 of results, produce some human readable/understandable
 386 output. Explainers are just normal CLOS classes (and can be easily
 387 subclassed) with one important method: `explain`.
 388
 389 The `run!` and `explain!` functions use the detailed-text-explainer,
 390 if you want another explainer you'll have to call `run` and `explain`
 391 yourself:
 392
 393 --------------------------------
 394 (explain (make-instance MY-EXPLAINER)
 395          (run THE-TEST)
 396          THE-STREAM)
 397 --------------------------------
 398
 399 == Random Testing (QuickCheck) ==
 400
 401 Sometimes it's hard to come up with edge cases for tests, or sometimes
 402 there are so many that it's hard to list them all one by one. Random
 403 testing is a way to tell the test suite how to generate input and how
 404 to test that certain conditions always hold. One issue when writing
 405 random tests is that you can't, usually, test for specific results,
 406 you have to test that certain relationships hold.
 407
 408 For example, if we had a function which reverses a list, we could
 409 define a relationship like this:
 410
 411 --------------------------------
 412 (equalp the-list (reverse (reverse the-list)))
 413 --------------------------------
 414
 415 or
 416
 417 --------------------------------
 418 (equalp (length the-list) (length (reverse the-list)))
 419 --------------------------------
 420
 421 Random tests are defined via `def-test`, but the random part is then
 422 wrapped in a xref:OP_FOR-ALL[`for-all`] macro which runs its body
 423 `*num-trials*` times with different inputs:
 424
 425 --------------------------------
 426 (for-all ((the-list (gen-list :length (gen-integer :min 0 :max 37)
 427                               :elements (gen-integer :min -10 :max 10))))
 428   (is (equalp a (reverse (reverse the-list))))
 429   (is (= (length the-list) (length (reverse the-list)))))
 430 --------------------------------
 431
 432 == Fixtures ==
 433
 434 Fixtures are, much like macros, ways to hide common code so that the
 435 essential functionality we're trying to test is easier to see. Unlike
 436 normal macros fixtures are not allowed to inspect the source code of
 437 their arguments, all they can really do is wrap one form (or multiple
 438 forms in a progn) in something else.
 439
 440 [NOTE]
 441 Fixtures exist for the common case where we want to bind some
 442 variables to some mock (or test) values and run our test in this
 443 state. If anything more complicated than this is neccessary just use a
 444 normal macro.
 445
 446 Fixtures are defined via the `def-fixture` macro and used either with
 447 `with-fixture` directory or, more commonly, using the `:fixture`
 448 argument to `def-test` or `def-suite`. A common example of a fixture
 449 would be this:
 450
 451 --------------------------------
 452 (def-fixture mock-db ()
 453   (let ((*database* (make-instance 'mock-db))
 454         (*connection* (make-instance 'mock-connection)))
 455     (unwind-protect
 456         (&body) <1>
 457       (mock-close-connection *connection*))))
 458
 459 (with-fixture mock-db ()
 460   (is-true (database-p *database*)))
 461
 462 <1> This is a local macro named 5AM:&BODY (the user of def-fixture can
 463 not change this name)
 464
 465 --------------------------------
 466
 467 The body of the `def-fixture` has one local function (actually a local
 468 macro) called `&body` which will expand into whatever the body passed
 469 to `with-fixture` is. `def-fixture` also has an argument list, but
 470 there are two things to note: 1) in practice it's rarely used; 2)
 471 these are arguments will be bound to values (like defun) and not
 472 source code (like defmacro).
 473
 474 [[API_REFERENCE]]
 475 == API Reference ==
 476
 477 [[OP_DEF-TEST]]
 478 === DEF-TEST ===
 479
 480 ================================
 481 --------------------------------
 482 (def-test NAME (&key DEPENDS-ON SUITE FIXTURE COMPILE-AT PROFILE) &body BODY)
 483 --------------------------------
 484
 485 include::docstrings/OP_DEF-TEST.txt[]
 486 ================================
 487
 488 [[OP_DEF-SUITE]]
 489 === DEF-SUITE ===
 490
 491 ================================
 492 ----
 493 (def-suite NAME &key DESCRIPTION IN FIXTURE)
 494 ----
 495
 496 include::docstrings/OP_DEF-SUITE.txt[]
 497 ================================
 498
 499 [[OP_IN-SUITE]]
 500 [[OP_IN-SUITE-STAR-]]
 501 === IN-SUITE ===
 502
 503 ================================
 504 ----
 505 (in-suite NAME)
 506 ----
 507
 508 include::docstrings/OP_IN-SUITE.txt[]
 509 ================================
 510
 511 [[OP_IS]]
 512 === IS ===
 513
 514 ================================
 515 ----
 516 (is (PREDICATE EXPECTED ACTUAL) &rest REASON-ARGS)
 517
 518 (is (PREDICATE ACTUAL) &rest REASON-ARGS)
 519 ----
 520
 521 include::docstrings/OP_IS.txt[]
 522 ================================
 523
 524 [[OP_IS-TRUE]]
 525 [[OP_IS-FALSE]]
 526 === IS-TRUE / IS-FALSE / IS-EVERY ===
 527
 528 ================================
 529 ----
 530 (is-true CONDITION &rest reason)
 531 ----
 532
 533 include::docstrings/OP_IS-TRUE.txt[]
 534 ================================
 535
 536 ================================
 537 ----
 538 (is-false CONDITION &rest reason)
 539 ----
 540
 541 include::docstrings/OP_IS-FALSE.txt[]
 542 ================================
 543
 544 ////////////////////////////////
 545 //// the actual doc string of talks about functionality i don't want
 546 //// to publises (since it's just weird). se we use our own here
 547 ////////////////////////////////
 548 ================================
 549 ----
 550 (is-every predicate &rest (EXPECTED ACTUAL &rest REASON))
 551 ----
 552
 553 Designed for those cases where you have a large set of expected/actual
 554 pairs that must be compared using the same predicate function.
 555
 556 Expands into:
 557
 558 ----
 559 (progn
 560   (is (,PREDICATE ,EXPECTED ,ACTUAL) ,@REASON)
 561   ...
 562 ----
 563
 564 for each argument.
 565 ================================
 566
 567 [[OP_SIGNALS]]
 568 [[OP_FINISHES]]
 569 === SIGNALS / FINISHES ===
 570
 571 ================================
 572 ----
 573 (signals CONDITION &body body)
 574 ----
 575
 576 include::docstrings/OP_SIGNALS.txt[]
 577 ================================
 578
 579 ================================
 580 ----
 581 (finishes &body body)
 582 ----
 583
 584 include::docstrings/OP_FINISHES.txt[]
 585 ================================
 586
 587 [[OP_PASS]]
 588 [[OP_FAIL]]
 589 [[OP_SKIP]]
 590 === PASS / FAIL / SKIP ===
 591
 592 ================================
 593 ----
 594 (skip &rest REASON-ARGS)
 595 ----
 596
 597 include::docstrings/OP_SKIP.txt[]
 598 ================================
 599
 600 ================================
 601 ----
 602 (pass &rest REASON-ARGS)
 603 ----
 604
 605 include::docstrings/OP_PASS.txt[]
 606 ================================
 607
 608 ================================
 609 ----
 610 (fail &rest REASON-ARGS)
 611 ----
 612
 613 include::docstrings/OP_FAIL.txt[]
 614 ================================
 615
 616 [[OP_-EPOINT-]]
 617 [[OP_-EPOINT--EPOINT-]]
 618 [[OP_-EPOINT--EPOINT--EPOINT-]]
 619
 620 [[OP_RUN-EPOINT-]]
 621 [[OP_EXPLAIN-EPOINT-]]
 622 [[OP_DEBUG-EPOINT-]]
 623 === RUN! / EXPLAIN! / DEBUG! ===
 624
 625 ================================
 626 ----
 627 (run! &optional TEST-NAME)
 628 ----
 629
 630 include::docstrings/OP_RUN-EPOINT-.txt[]
 631 ================================
 632
 633 ================================
 634 ----
 635 (explain! RESULT-LIST)
 636 ----
 637
 638 include::docstrings/OP_EXPLAIN-EPOINT-.txt[]
 639 ================================
 640
 641 ================================
 642 ----
 643 (debug! TEST-NAME)
 644 ----
 645
 646 include::docstrings/OP_DEBUG-EPOINT-.txt[]
 647 ================================
 648
 649 [[OP_RUN]]
 650 === RUN ===
 651
 652 ================================
 653 ----
 654 (run TEST-SPEC)
 655 ----
 656
 657 include::docstrings/OP_RUN.txt[]
 658 ================================
 659
 660 [[OP_DEF-FIXTURE]]
 661 === DEF-FIXTURE ===
 662
 663 ================================
 664 ----
 665 (def-fixture (NAME (&rest ARGS) &body BODY)
 666 ----
 667
 668 include::docstrings/OP_DEF-FIXTURE.txt[]
 669 ================================
 670
 671 [[OP_WITH-FIXTURE]]
 672 === WITH-FIXTURE ===
 673
 674 ================================
 675 ----
 676 (with-fixture NAME (&rest ARGS) &body BODY)
 677 ----
 678
 679 include::docstrings/OP_WITH-FIXTURE.txt[]
 680 ================================
 681
 682 [[OP_FOR-ALL]]
 683 === FOR-ALL ===
 684
 685 ================================
 686 --------------------------------
 687 (for-all (&rest (NAME VALUE &optional GUARD))
 688   &body body)
 689 --------------------------------
 690
 691 include::docstrings/OP_FOR-ALL.txt[]
 692 ================================
 693
 694 [[VAR_-STAR-NUM-TRIALS-STAR-]]
 695 [[VAR_-STAR-MAX-TRIALS-STAR-]]
 696 === \*NUM-TRIALS* / \*MAX-TRIALS* ===
 697
 698 ================================
 699 ----
 700 *num-trials*
 701 ----
 702
 703 include::docstrings/VAR_-STAR-NUM-TRIALS-STAR-.txt[]
 704 ================================
 705
 706 ================================
 707 ----
 708 *max-trials*
 709 ----
 710
 711 include::docstrings/VAR_-STAR-MAX-TRIALS-STAR-.txt[]
 712 ================================
 713
 714 [[OP_GEN-INTEGER]]
 715 [[OP_GEN-FLOAT]]
 716 === GEN-INTEGER / GEN-FLOAT ===
 717
 718 ================================
 719 ----
 720 (gen-integer &key MIN MAX)
 721 ----
 722
 723 include::docstrings/OP_GEN-INTEGER.txt[]
 724 ================================
 725
 726 ================================
 727 ----
 728 (gen-float &key BOUND TYPE MIN MAX)
 729 ----
 730
 731 include::docstrings/OP_GEN-FLOAT.txt[]
 732 ================================
 733
 734 [[OP_GEN-CHARACTER]]
 735 [[OP_GEN-STRING]]
 736 === GEN-CHARACTER / GEN-STRING ===
 737
 738 ================================
 739 ----
 740 (gen-character &key CODE-LIMIT CODE ALPHANUMERICP)
 741 ----
 742
 743 include::docstrings/OP_GEN-CHARACTER.txt[]
 744 ================================
 745
 746 ================================
 747 ----
 748 (gen-string &key LENGTH ELEMENTS)
 749 ----
 750
 751 include::docstrings/OP_GEN-STRING.txt[]
 752 ================================
 753
 754 [[OP_GEN-BUFFER]]
 755 === GEN-BUFFER ===
 756
 757 ================================
 758 ----
 759 (gen-buffer &key LENGTH ELEMENTS ELEMENT-TYPE)
 760 ----
 761
 762 include::docstrings/OP_GEN-STRING.txt[]
 763 ================================
 764
 765 [[OP_GEN-LIST]]
 766 [[OP_GEN-TREE]]
 767 === GEN-LIST / GEN-TREE ===
 768
 769 ================================
 770 ----
 771 (gen-list &key LENGTH ELEMENTS)
 772 ----
 773
 774 include::docstrings/OP_GEN-LIST.txt[]
 775 ================================
 776
 777 ================================
 778
 779 ----
 780 (gen-tree &key SIZE ELEMENTS)
 781 ----
 782
 783 include::docstrings/OP_GEN-TREE.txt[]
 784 ================================
 785
 786 [[OP_GEN-ONE-ELEMENT]]
 787 === GEN-ONE-ELEMENT ===
 788
 789 ================================
 790 ----
 791 (gen-one-element &rest ELEMENTS)
 792 ----
 793
 794 include::docstrings/OP_GEN-ONE-ELEMENT.txt[]
 795 ================================
 796
 797
 798
 799 ////////////////////////////////
 800
 801 ////////////////////////////////