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 that a human will be using 5am (as
 339 opposed to a continuous integration bot) they'll want to run the tests
 340 and immediately see the results with detailed failure info, this can
 341 be 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 One common problem when writing tests is determining what data to test
 402 with. We often know the kids of values we'll generally be passing to a
 403 function, and that usually leads us to some edge cases (empty lists,
 404 zeros, etc.) however it is often very hard to guess, ahead of time,
 405 all the different values we'll be passing to our code and it's
 406 especially hard to know kinds of values we haven't forseen.
 407
 408 Quickcheck-ing is one way to find edge cases we hadn't thought
 409 about. When quickcheck-ing we don't have a list of inputs and outputs,
 410 we just have a class of values (generated randomly at run time) and a
 411 property of our code that we know should always hold.
 412
 413 For example, if we had a function which reverses a list, we'll
 414 probably start with some sample data, either copies of the actual data
 415 we want to sort, or whatever comes to mind while implementing the
 416 function itself. But can we trust our selves to forsee all the
 417 different data we're going to sort? Probably not, but we do know some
 418 things about this function which, no matter what the input is, must
 419 always be true. For example, given a list sorting function, we know
 420 that:
 421
 422 --------------------------------
 423 (equalp the-list (reverse (reverse the-list)))
 424 --------------------------------
 425
 426 and
 427
 428 --------------------------------
 429 (equalp (length the-list) (length (reverse the-list)))
 430 --------------------------------
 431
 432 and
 433
 434 --------------------------------
 435 (equalp the-list (intersection the-list (reverse the-list)))
 436 --------------------------------
 437
 438 Given these three conditions we can ask five am to generate random
 439 lists and test that, for whatever inputs, these conditions hold:
 440
 441 --------------------------------
 442 (for-all ((the-list (gen-list :length (gen-integer :min 0 :max 37)
 443                               :elements (gen-integer :min -10 :max 10))))
 444   (is (equalp a (reverse (reverse the-list))))
 445   (is (= (length the-list) (length (reverse the-list))))
 446   (is (equalp the-list (intersection the-list (reverse the-list)))))
 447 --------------------------------
 448
 449 The xref:OP_FOR-ALL[`for-all`] macro is the main driver behind
 450 fiveam's random testing functionality. It will execute its body a
 451 certian number of time (`*num-trials*` times) generating new data each
 452 time.
 453
 454 The generators themselves are functions, usually lambdas, which, when
 455 called, produce a fresh datum. The standard generators included in
 456 fivame have been written in a way that's its easy to combine them. For
 457 examples the gen-list function, which returns a list generator, takes
 458 as its :length parameter and integer generator, which is what the
 459 gen-integer function returns.
 460
 461 Sometime though it's not enough to generate values independantly,
 462 sometimes we want, for example, two numbers where one is less than the
 463 other. Let's say we were testing a simple max function, we could start
 464 out with this:
 465
 466 --------------------------------
 467 (for-all ((a (gen-integer))
 468           (b (gen-integer)))
 469   (is-true (if (= a (max a b))
 470                (<= a b)
 471                (<= b a))))
 472 --------------------------------
 473
 474 Which works, but it might be cleaner to generate two randowm numbers
 475 and require that one be less than the other:
 476
 477 --------------------------------
 478 (for-all ((a (gen-integer))
 479           (b (gen-integer) (<= a b)))
 480   (is (= b (max a b))))
 481 --------------------------------
 482
 483 We've added a guard condition to the values of B requiring that they
 484 be `<=` the values o A. `for-all` will call simply keep trying to
 485 produce random values of A and B until this condition is meet, and
 486 only when it is will the body be run.
 487
 488 [NOTE]
 489 Since this could loop an arbitrary number of times, especially if the
 490 guard condition is impossible to meet, the variable `*max-trials*`
 491 determins the maximum number of times for-all will try to run its
 492 body, unless the*num-trials* limit is hit first. By default
 493 *max-trials* is 100 times greater than *num-trials*.
 494
 495 == Fixtures ==
 496
 497 Fixtures are, much like macros, ways to hide common code so that the
 498 essential functionality we're trying to test is easier to see. Unlike
 499 normal macros fixtures are not allowed to inspect the source code of
 500 their arguments, all they can really do is wrap one form (or multiple
 501 forms in a progn) in something else.
 502
 503 [NOTE]
 504 Fixtures exist for the common case where we want to bind some
 505 variables to some mock (or test) values and run our test in this
 506 state. If anything more complicated than this is neccessary just use a
 507 normal macro.
 508
 509 Fixtures are defined via the `def-fixture` macro and used either with
 510 `with-fixture` directory or, more commonly, using the `:fixture`
 511 argument to `def-test` or `def-suite`. A common example of a fixture
 512 would be this:
 513
 514 --------------------------------
 515 (def-fixture mock-db ()
 516   (let ((*database* (make-instance 'mock-db))
 517         (*connection* (make-instance 'mock-connection)))
 518     (unwind-protect
 519         (&body) <1>
 520       (mock-close-connection *connection*))))
 521
 522 (with-fixture mock-db ()
 523   (is-true (database-p *database*)))
 524
 525 <1> This is a local macro named 5AM:&BODY (the user of def-fixture can
 526 not change this name)
 527
 528 --------------------------------
 529
 530 The body of the `def-fixture` has one local function (actually a local
 531 macro) called `&body` which will expand into whatever the body passed
 532 to `with-fixture` is. `def-fixture` also has an argument list, but
 533 there are two things to note: 1) in practice it's rarely used; 2)
 534 these are arguments will be bound to values (like defun) and not
 535 source code (like defmacro).
 536
 537 [[API_REFERENCE]]
 538 == API Reference ==
 539
 540 [[OP_DEF-TEST]]
 541 === DEF-TEST ===
 542
 543 ================================
 544 --------------------------------
 545 (def-test NAME (&key DEPENDS-ON SUITE FIXTURE COMPILE-AT PROFILE) &body BODY)
 546 --------------------------------
 547
 548 include::docstrings/OP_DEF-TEST.txt[]
 549 ================================
 550
 551 [[OP_DEF-SUITE]]
 552 === DEF-SUITE ===
 553
 554 ================================
 555 ----
 556 (def-suite NAME &key DESCRIPTION IN FIXTURE)
 557 ----
 558
 559 include::docstrings/OP_DEF-SUITE.txt[]
 560 ================================
 561
 562 [[OP_IN-SUITE]]
 563 [[OP_IN-SUITE-STAR-]]
 564 === IN-SUITE ===
 565
 566 ================================
 567 ----
 568 (in-suite NAME)
 569 ----
 570
 571 include::docstrings/OP_IN-SUITE.txt[]
 572 ================================
 573
 574 [[OP_IS]]
 575 === IS ===
 576
 577 ================================
 578 ----
 579 (is (PREDICATE EXPECTED ACTUAL) &rest REASON-ARGS)
 580
 581 (is (PREDICATE ACTUAL) &rest REASON-ARGS)
 582 ----
 583
 584 include::docstrings/OP_IS.txt[]
 585 ================================
 586
 587 [[OP_IS-TRUE]]
 588 [[OP_IS-FALSE]]
 589 === IS-TRUE / IS-FALSE / IS-EVERY ===
 590
 591 ================================
 592 ----
 593 (is-true CONDITION &rest reason)
 594 ----
 595
 596 include::docstrings/OP_IS-TRUE.txt[]
 597 ================================
 598
 599 ================================
 600 ----
 601 (is-false CONDITION &rest reason)
 602 ----
 603
 604 include::docstrings/OP_IS-FALSE.txt[]
 605 ================================
 606
 607 ////////////////////////////////
 608 //// the actual doc string of talks about functionality i don't want
 609 //// to publises (since it's just weird). se we use our own here
 610 ////////////////////////////////
 611 ================================
 612 ----
 613 (is-every predicate &rest (EXPECTED ACTUAL &rest REASON))
 614 ----
 615
 616 Designed for those cases where you have a large set of expected/actual
 617 pairs that must be compared using the same predicate function.
 618
 619 Expands into:
 620
 621 ----
 622 (progn
 623   (is (,PREDICATE ,EXPECTED ,ACTUAL) ,@REASON)
 624   ...
 625 ----
 626
 627 for each argument.
 628 ================================
 629
 630 [[OP_SIGNALS]]
 631 [[OP_FINISHES]]
 632 === SIGNALS / FINISHES ===
 633
 634 ================================
 635 ----
 636 (signals CONDITION &body body)
 637 ----
 638
 639 include::docstrings/OP_SIGNALS.txt[]
 640 ================================
 641
 642 ================================
 643 ----
 644 (finishes &body body)
 645 ----
 646
 647 include::docstrings/OP_FINISHES.txt[]
 648 ================================
 649
 650 [[OP_PASS]]
 651 [[OP_FAIL]]
 652 [[OP_SKIP]]
 653 === PASS / FAIL / SKIP ===
 654
 655 ================================
 656 ----
 657 (skip &rest REASON-ARGS)
 658 ----
 659
 660 include::docstrings/OP_SKIP.txt[]
 661 ================================
 662
 663 ================================
 664 ----
 665 (pass &rest REASON-ARGS)
 666 ----
 667
 668 include::docstrings/OP_PASS.txt[]
 669 ================================
 670
 671 ================================
 672 ----
 673 (fail &rest REASON-ARGS)
 674 ----
 675
 676 include::docstrings/OP_FAIL.txt[]
 677 ================================
 678
 679 [[OP_-EPOINT-]]
 680 [[OP_-EPOINT--EPOINT-]]
 681 [[OP_-EPOINT--EPOINT--EPOINT-]]
 682
 683 [[OP_RUN-EPOINT-]]
 684 [[OP_EXPLAIN-EPOINT-]]
 685 [[OP_DEBUG-EPOINT-]]
 686 === RUN! / EXPLAIN! / DEBUG! ===
 687
 688 ================================
 689 ----
 690 (run! &optional TEST-NAME)
 691 ----
 692
 693 include::docstrings/OP_RUN-EPOINT-.txt[]
 694 ================================
 695
 696 ================================
 697 ----
 698 (explain! RESULT-LIST)
 699 ----
 700
 701 include::docstrings/OP_EXPLAIN-EPOINT-.txt[]
 702 ================================
 703
 704 ================================
 705 ----
 706 (debug! TEST-NAME)
 707 ----
 708
 709 include::docstrings/OP_DEBUG-EPOINT-.txt[]
 710 ================================
 711
 712 [[OP_RUN]]
 713 === RUN ===
 714
 715 ================================
 716 ----
 717 (run TEST-SPEC)
 718 ----
 719
 720 include::docstrings/OP_RUN.txt[]
 721 ================================
 722
 723 [[OP_DEF-FIXTURE]]
 724 === DEF-FIXTURE ===
 725
 726 ================================
 727 ----
 728 (def-fixture (NAME (&rest ARGS) &body BODY)
 729 ----
 730
 731 include::docstrings/OP_DEF-FIXTURE.txt[]
 732 ================================
 733
 734 [[OP_WITH-FIXTURE]]
 735 === WITH-FIXTURE ===
 736
 737 ================================
 738 ----
 739 (with-fixture NAME (&rest ARGS) &body BODY)
 740 ----
 741
 742 include::docstrings/OP_WITH-FIXTURE.txt[]
 743 ================================
 744
 745 [[OP_FOR-ALL]]
 746 === FOR-ALL ===
 747
 748 ================================
 749 --------------------------------
 750 (for-all (&rest (NAME VALUE &optional GUARD))
 751   &body body)
 752 --------------------------------
 753
 754 include::docstrings/OP_FOR-ALL.txt[]
 755 ================================
 756
 757 [[VAR_-STAR-NUM-TRIALS-STAR-]]
 758 [[VAR_-STAR-MAX-TRIALS-STAR-]]
 759 === \*NUM-TRIALS* / \*MAX-TRIALS* ===
 760
 761 ================================
 762 ----
 763 *num-trials*
 764 ----
 765
 766 include::docstrings/VAR_-STAR-NUM-TRIALS-STAR-.txt[]
 767 ================================
 768
 769 ================================
 770 ----
 771 *max-trials*
 772 ----
 773
 774 include::docstrings/VAR_-STAR-MAX-TRIALS-STAR-.txt[]
 775 ================================
 776
 777 [[OP_GEN-INTEGER]]
 778 [[OP_GEN-FLOAT]]
 779 === GEN-INTEGER / GEN-FLOAT ===
 780
 781 ================================
 782 ----
 783 (gen-integer &key MIN MAX)
 784 ----
 785
 786 include::docstrings/OP_GEN-INTEGER.txt[]
 787 ================================
 788
 789 ================================
 790 ----
 791 (gen-float &key BOUND TYPE MIN MAX)
 792 ----
 793
 794 include::docstrings/OP_GEN-FLOAT.txt[]
 795 ================================
 796
 797 [[OP_GEN-CHARACTER]]
 798 [[OP_GEN-STRING]]
 799 === GEN-CHARACTER / GEN-STRING ===
 800
 801 ================================
 802 ----
 803 (gen-character &key CODE-LIMIT CODE ALPHANUMERICP)
 804 ----
 805
 806 include::docstrings/OP_GEN-CHARACTER.txt[]
 807 ================================
 808
 809 ================================
 810 ----
 811 (gen-string &key LENGTH ELEMENTS)
 812 ----
 813
 814 include::docstrings/OP_GEN-STRING.txt[]
 815 ================================
 816
 817 [[OP_GEN-BUFFER]]
 818 === GEN-BUFFER ===
 819
 820 ================================
 821 ----
 822 (gen-buffer &key LENGTH ELEMENTS ELEMENT-TYPE)
 823 ----
 824
 825 include::docstrings/OP_GEN-STRING.txt[]
 826 ================================
 827
 828 [[OP_GEN-LIST]]
 829 [[OP_GEN-TREE]]
 830 === GEN-LIST / GEN-TREE ===
 831
 832 ================================
 833 ----
 834 (gen-list &key LENGTH ELEMENTS)
 835 ----
 836
 837 include::docstrings/OP_GEN-LIST.txt[]
 838 ================================
 839
 840 ================================
 841
 842 ----
 843 (gen-tree &key SIZE ELEMENTS)
 844 ----
 845
 846 include::docstrings/OP_GEN-TREE.txt[]
 847 ================================
 848
 849 [[OP_GEN-ONE-ELEMENT]]
 850 === GEN-ONE-ELEMENT ===
 851
 852 ================================
 853 ----
 854 (gen-one-element &rest ELEMENTS)
 855 ----
 856
 857 include::docstrings/OP_GEN-ONE-ELEMENT.txt[]
 858 ================================
 859
 860
 861
 862 ////////////////////////////////
 863
 864 ////////////////////////////////