---

6.2.1 Guile Test Case Reference

Guile Internal Record: <test-case> ¶

This type represents a test case.

It encapsulates micro_benchmark_test_case underneath and a reference to the suite to controls its lifetime. Note that this name is not exported by the module, but objects of this type are returned by the following function.

Guile Constructor: add-test! suite name #:key test direct dimensions skip-iterations min-iterations max-iterations min-sample-iterations max-sample-iterations max-time set-up tear-down ¶

Preconditions:

1. suite was returned by make-suite.
2. (string? name) is #t.
3. If #:set-up is provided, (set-up <state-object>) is a valid call. If it isn’t provided, the value returned by the default set-up function is (get-sizes <state-object>).
4. If #:tear-down is provided, (tear-down <state-object> (set-up <state-object>)) is a valid call.
5. If #:direct is provided and it isn’t #f, (apply test <state-object2> (set-up <state-object1>)), being test the value provided through #:test, must be a valid call.
6. If #:direct is not provided or it is #f, (apply test (set-up <state-object>)), being test the value provided through #:test, is a valid call.
7. If #:dimensions is provided, its value is a list of lists of non-negative integers.
8. If #:skip-iterations!, #:min-iterations, #:max-iterations, #:min-sample-iterations or #:max-sample-iterations is provided, its value is a non-negative integer.
9. If #:max-time is provided, its value is either a non-negative integer or a pair of non-negative integers.

Effects:

1. Register on suite the provided test definition and constraints as name.

Postconditions:

1. The predicate test-case? returns #t on the returned value.
2. The registered test is prepared to be executed by suite.
3. If #:dimensions was provided, the returned test has the value provided as size its constraints.
4. If #:skip-iterations! was provided, the returned test will perform this number of of iterations before start taking measurements.
5. If #:min-iterations or #:max-iterations was provided, the returned test will perform a number of iterations in the range [min, max], being min the value provided to #:min-iterations or zero, and max. the value provided to #:max-iterations or an implementation upper limit.
6. If #:min-sample-iterations or #:max-sample-iterations was provided, the returned test will perform number of iterations per measurement sample in the range [min, max], being min the value provided to #:min-sample-iterations or zero, and max. the value provided to #:max-sample-iterations or an implementation upper limit.
7. If #:max-time was provided, its value will be used as the time limit of the registered test.

Guile Predicate: test-case? object ¶

Preconditions:

1. None.

Effects:

1. Check if object type is <test-case>.

Postconditions:

1. The value returned is #t if object is of type <test-case>.

Guile Function: test-set-constraints! test #:key skip-iterations! min-iterations max-iterations min-sample-iterations max-sample-iterations ¶

Preconditions:

1. test was returned by add-test!.
2. If #:skip-iterations!, #:min-iterations, #:max-iterations, #:min-sample-iterations or #:max-sample-iterations is provided, its value is a non-negative integer.

Effects:

1. If #:skip-iterations! was provided, any previous value of iterations to skip stops taking effect.
2. If #:min-iterations or #:max-iterations was provided, any previous iteration limit value stops taking effect.
3. If #:min-sample-iterations or #:max-sample-iterations was provided, any previous sample iteration limit value stops taking effect.

Postconditions:

1. If #:skip-iterations! was provided, this will be number of iterations performed on the test code represented by test before taking measurements.
2. If #:min-iterations or #:max-iterations was provided, the number of iterations performed by test will be [min, max], being min the value provided to #:min-iterations or zero, and max. the value provided to #:max-iterations or an implementation upper limit.
3. If #:min-sample-iterations or #:max-sample-iterations was provided, the number of iterations per measurement sample performed by test will be [min, max], being min the value provided to #:min-sample-iterations or zero, and max. the value provided to #:max-sample-iterations or an implementation upper limit.

Guile Function: test-add-dimension! test dim ¶

Preconditions:

1. test was returned by add-test!.
2. dim is a list of non-negative integers.

Effects:

1. Add a new dimension to test with dim as its space of values.

Postconditions:

1. test has another dimension added to its constraints.

Guile Function: test-dimensions test ¶

Preconditions:

1. test was returned by add-test!.

Effects:

1. None.

Postconditions:

1. The value returned is the, possibly empty, list of dimensions provided for test.

Guile Function: test-skip-iterations! test iterations ¶

Preconditions:

1. test was returned by add-test!.

Effects:

1. Any previous value of iterations to skip stops taking effect.

Postconditions:

1. test will perform iterations before taking measurements.

Guile Function: test-iterations-to-skip test ¶

Preconditions:

1. test was returned by add-test!.

Effects:

1. None.

Postconditions:

1. The number of iterations that test will perform iterations before taking measurements.

Guile Function: test-limit-iterations! test #:key min max ¶

Preconditions:

1. test was returned by add-test!.
2. If #:min or #:max is provided, its value must be a non-negative integer.

Effects:

1. Any previous iteration limit stops taking effect.

Postconditions:

1. The number of iterations performed by test will be [min, max], being min the value provided to #:min or zero, and max. the value provided to #:max or an implementation upper limit.

Guile Function: test-min-iterations test ¶

Preconditions:

1. test was returned by add-test!.

Effects:

1. None.

Postconditions:

1. The minimum number of iterations that test will perform iterations taking measurements.

Guile Function: test-max-iterations test ¶

Preconditions:

1. test was returned by add-test!.

Effects:

1. None.

Postconditions:

1. The maximum number of iterations that test will perform iterations taking measurements, or zero if no such limit has been provided by the user.

Guile Function: test-limit-samples! test #:key min max ¶

Preconditions:

1. test was returned by add-test!.
2. If #:min or #:max is provided, its value must be a non-negative integer.

Effects:

1. Any previous sample iteration limit stops taking effect.

Postconditions:

1. The number of iterations per measurement sample performed by test will be [min, max], being min the value provided to #:min or zero, and max. the value provided to #:max or an implementation upper limit.

Guile Function: test-max-sample-iterations test ¶

Preconditions:

1. test was returned by add-test!.

Effects:

1. None.

Postconditions:

1. The maximum number of iterations per measurement sample that test will perform iterations, or zero if no such limit has been provided by the user.

Guile Function: test-min-sample-iterations test ¶

Preconditions:

1. test was returned by add-test!.

Effects:

1. None.

Postconditions:

1. The minimum number of iterations per measurement sample that test will perform iterations, or zero if no such limit has been provided by the user.

Guile Function: test-set-max-time! test time ¶

Preconditions:

1. test was returned by add-test!.
2. time is a positive integer or a pair of non-negative integers.

Effects:

1. Any previous time limit value stops taking effect.
2. If time is a pair, use its car value as the number of seconds of the time limit and its cdr value as the number of milliseconds.
3. Otherwise, use time as the number of seconds.

Postconditions:

1. The time limit provided will be used for test execution.

Guile Function: test-max-time! test ¶

Preconditions:

1. test was returned by add-test!.

Effects:

1. None.

Postconditions:

1. The returned value is a pair whose contents are the number of seconds and the number of milliseconds stored as time limit for test.

The following function does not return a <test-case> object. The tests registered by this function are executed by the main function (see Guile Utilities Reference.)

Guile Function: register-test! name #:key test direct dimensions skip-iterations min-iterations max-iterations min-sample-iterations max-sample-iterations set-up tear-down max-time ¶

Preconditions:

1. (string? name) is #t.
2. If #:set-up is provided, (set-up <state-object>) is a valid call. If it isn’t provided, the value returned by the default set-up function is (get-sizes <state-object>).
3. If #:tear-down is provided, (tear-down <state-object> (set-up <state-object>)) is a valid call.
4. If #:direct is provided and it isn’t #f, (apply test <state-object2> (set-up <state-object1>)), being test the value provided through #:test, must be a valid call.
5. If #:direct is not provided or it is #f, (apply test (set-up <state-object>)), being test the value provided through #:test, is a valid call.
6. If #:dimensions is provided, it must be a list of lists of non-negative integers.
7. If #:skip-iterations!, #:min-iterations, #:max-iterations, #:min-sample-iterations or #:max-sample-iterations is provided, the value provided is non-negative integers.
8. If #:max-time is provided, its value is either a non-negative integer or a pair of non-negative integers.

Effects:

1. Register the provided test definition and constraints as name.

Postconditions:

1. The registered test is prepared to be executed by main.