The framework provides these libraries:
Entire Framework
(require (lib "framework.ss" "framework"))
This library provides all of the definitions and syntax described in this manual.
(require (lib "framework-sig.ss" "framework"))
This library provides the signature definitions:
framework^, and
framework-class^.
The framework^ signature cotains all of the
names of the procedures described in this manual, except
those that begin with test: and
gui-utils:. The framework-class^
signature contains all of the classes defined in this
manual.
(require (lib "framework-unit.ss" "framework"))
This library provides one
unit/sigs, section 33.3 in PLT MzScheme: Language Manual:
framework@. It exports the signature
framework^. It imports the mred^ signature.
(require (lib "macro.ss" "framework"))
This defines the mixin macro. See section 3.2 for more information.
Test Suite Engine
(require (lib "test.ss" "framework"))
This library provides all of the definitions beginning with
test: described in this manual.
GUI Utilities
(require (lib "gui-utils.ss" "framework"))
This libraries provides all of the definitions beginning
with gui-utils: described in this manual.
The framework relies heavily on mixins. A mixin is a class
parameterization modeled on a paper published by Flatt, Felleisen, and
Krishnamurthi, available at
http://www.cs.rice.edu/CS/PLT/Publications/#ffk-pldi97.
The implementation of these mixins in MzScheme is with the combination of
lambda and class. The framework provides a macro to simplify
the checking and implementation of these mixins. It's syntax is very
similar to the syntax for class*, section 3 in PLT MzScheme: Language Manual. The shape of
a mixin is:
(mixin (interface-expr ...) (interface-expr ...) instance-variable-clause ...)
This macro expands into a procedure that accepts a class. The argument passed to
this procedure must match the interfaces of the first interface-exprs
expressions. The procedure returns a class that is derived from its
argument. This result class must match the interfaces specified in the
second interface-exprs section; it has clauses specified by
instance-variable-clauses. The syntax of the initialization-variables and
instance-variable-clause are exactly the same as class*/names, section 3.3 in PLT MzScheme: Language Manual.
The mixin macro does some checking to be sure that variables that the
instance-variable-clauses refer to in their super class are in the
interfaces. That checking and the checking that the input class matches the
declared interfaces aside, the mixin macro's expansion is something
like this:
(mixin (i<%> ...) (j<%> ...) clause ...) = (lambda (%) (class* % (j<%> ...) clause ...))
The mixin macro is provided by
(require (lib "macro.ss" "framework"))
The framework's contract.ss library defines new forms of expression that specify contracts and new forms of expression that attach contracts to values.
This section describes two classes of contracts: contracts for functions (described in section 3.3.1) and contracts for flat values (described in section 3.3.2). A contract for a flat value is merely a predicate that accepts the value and returns a boolean indicating if the contract holds. In addition, this section describes are two forms for establishing a contract on a value (described in section 3.3.3).
This subsection describes helper functions for building contracts on flat values, i. e., predicates.
union accepts any number of
predicates and at most one function contract and returns
a contract that corresponds to the union of them all.
and/f accepts a list of predicates and
returns a predicate that is the conjunction of those
predicates.
or/f accepts a list of predicates and
returns a predicate that is the disjuction of those
predicates.
>=/c accepts a number and
returns a predicate that requires the input to be a number
and greater than or equal to the original input.
<=/c accepts a number and
returns a predicate that requires the input to be a number
and less than or equal to the original input.
>/c accepts a number and
returns a predicate that requires the input to be a number
and greater than the original input.
</c accepts a number and
returns a predicate that requires the input to be a number
and less than the original input.
natural-number? returns
#t if the input is a natural number and
#f otherwise.
false? returns true if the input
is #f.
printable? returns #t
for any value that can be written out and read back in.
symbols accepts any number of
symbols and returns a predicate that checks for those
symbols.
is-a?/c accepts a class or
interface and returns a predicate that checks if objects are
subclasses of the class or implement the interface.
implementation?/c
accepts an interface and returns a predicate that checks if
classes are implement the given interface.
subclass?/c accepts a class
and returns a predicate that checks if classes are
subclasses of the original class.
listof accepts a predicate and
returns a predicate that checks for lists whose elements
match the original predicate.
vectorof accepts a predicate and
returns a predicate that checks for vectors whose elements
match the original predicate.
cons/p accepts two predicates
and returns a predicate that checks for cons cells whose
car and cdr correspond to cons/p's two arguments.
list/p accepts an arbitrary
number of arguments and returns a predicate that checks for
lists whose length is the same as the number of arguments to
list/p and whose elements match those arguments.
mixin-contract is a
contract that matches mixins. It is a function
contract. It guarantees that the input to the function is
a class and the result of the function is a subclass of
the input.
make-mixin-contract
is a function that constructs mixins contracts. It accepts
any number of classes and interfaces and returns a
function contract. The function contract guarantees that
the input to the function implements the interfaces and is
derived from the classes and that the result of the
function is a subclass of the input.
This section describes the contract constructors for function contracts. This is their shape:
expr ::== ... | (case-> arrow-contract-expr ...) | arrow-contract-expr arrow-contract-expr ::== | (-> expr ... expr) | (-> expr ... any) | (->* (expr ...) expr (expr ...)) | (->* (expr ...) (expr ...)) | (->d expr ... expr) | (->*d (expr ...) expr) | (->*d (expr ...) expr expr) | (opt-> (expr ...) (expr ...) expr) | (opt->* (expr ...) (expr ...) (expr ...))
The -> contract is for functions that accept a
fixed number of arguments and return a single result. The
last argument to -> is the contract on the result
of the function and the other arguments are the contracts on
the arguments to the function. Each of the arguments to
-> must be another contract expression or a
predicate. For example, this expression:
(integer? boolean? . -> . integer?)
is a contract on functions of two arguments. The first must
be an integer and the second a boolean and the function must
return an integer. (This example uses
MzScheme's infix notation, section 14.3 in PLT MzScheme: Language Manual
so that the -> appears in a suggestive place).
If any is used as the last argument to ->,
no contract checking is performed on the result of the
function, and tail-recursion is preserved.
The ->* expression is for functions that return
multiple results and/or have rest arguments. If two
arguments are supplied, the first is the contracts on the
arguments to the function and the second is the contract on
the results of the function. If three arguments are
supplied, the first argument contains the contracts on the
arguments to the function (excluding the rest argument), the
second contains the contract on the rest argument to the
function and the final argument is the contracts on the
results of the function.
The ->d and ->*d contract constructors are
like their d-less counterparts, except that the
result portion is a function that accepts the original
arguments to the function and returns the range contracts.
The range contract function for ->*d must return
multiple values: one for each result of the original
function.
As an example, this is the contract for sqrt
(number?. ->d . (lambda (in) (lambda (out) (and (number?out) (abs (- (* out out) in) 0.01)))))
It says that the input must be a number and that the
difference between the square of the result and the original
number is less than 0.01.
The case-> expression constructs a contract for
case-lambda function. It's arguments must all be function
contracts, built by one of ->, ->d,
->*, or ->*d.
The opt-> expression constructs a contract for an
opt-lambda function. The first arguments are the
required parameters, the second arguments are the optional
parameters and the final argument is the result. Each
opt-> expression expands into case->.
The opt->* expression constructs a contract for an
opt-lambda function. The only difference between
opt-> and opt->* is that multiple return
values are permitted with opt->* and they are
specified in the last clause of an opt->*
expression.
There are two special forms that add contract
specifications, provide/contract and
contract. A provide/contract form
has this shape:
(provide/contract (id expr) ...)
and can only appear at the top-level of a
module, section 5 in PLT MzScheme: Language Manual. As with
provide, each identifier is provided from the
module. In addition, clients of the module must live up to
the contract specified by expr.
The contract special form is the primitive
mechanism for attaching a contract to a value. Its purpose
is as a target for the expansion of some higher-level
contract specifying form.
The contract form has this shape:
(contract expr to-protect-expr positive-blame negative-blame contract-source)
The contract expression adds the contract specified
by the first argument to the value in the second argument.
The result of a contract expression is the result
of the to-protect-expr expression, but with the
contract specified by contract-expr enforced on
to-protect-expr. The expressions
positive-blame and negative-blame must be
symbols indicating how to assign blame for positive and
negative positions of the contract specified by
contract-expr. Finally, contract-source,
if specified, indicates where the contract was assumed. If
absent, it defaults to the source location of the
contract expression.
The procedure contract? returns #t if its
argument was constructed with one of the arrow constructors
described earlier in this section, or if its argument is a
procedure of arity 1.
-> ->d ->* ->*d case->
The framework provides several new primitive functions that simulate user actions, which may be used to test applications. You use these primitives and combine them just as regular MzScheme functions. For example,
(begin
(test:keystroke #\A)
(test:menu-select "File" "Save"))
sends a keystroke event to the window with the keyboard focus and invokes the callback function for the ``Save'' menu item from the ``File'' menu. This has the same effect as if the user typed the key ``A'', pulled down the ``File'' menu and selected ``Save''.
It is possible to load this portion of the framework without loading the rest of the framework. See the libraries section for more details.
Currently, the test engine has primitives for pushing buttons, setting check-boxes and choices, sending keystrokes, selecting menu items and clicking the mouse. Many functions that are also useful in application testing, such as traversing a tree of panels, getting the text from a canvas, determining if a window is shown, and so on, exist in MrEd.
Here is an example program that enters a factorial procedure and computes (fact 4). To run this program, start DrScheme, click on the ``Console'' button, load this program and run (go). Then bring the DrScheme window to the front and click the mouse in the DrScheme window.
(define go
(lambda ()
(sleep 3)
(test:new-window (get-panel '(0 0 0 1))) ; definitions canvas
(test:menu-select "Edit" "Select All")
(test:menu-select "Edit" "Delete")
(type-line "(define fact")
(type-line "(lambda (n)")
(type-line "(if (zero? n)")
(type-line "1")
(type-line "(* n (fact (sub1 n))))))")
(test:button-push (get-panel '(0 0 0 0 5 0))) ; check-syntax button
(test:button-push (get-panel '(0 0 0 0 5 3))) ; execute button
(sleep 3)
(type-line "(fact 4)")
(sleep 1)
(printf "Test complete. Pending actions: ~s~n"
(test:number-pending-actions))))
(define type-line
(lambda (str)
(for-each test:keystroke (string->list str))
(test:keystroke #\return)))
(define get-panel
(lambda (path)
(let loop ([path path]
[panel (send (test:get-active-frame) get-top-panel)])
(if (null? path)
panel
(loop (cdr path)
(list-ref (ivar panel children) (car path)))))))
The actions associated with a testing primitive may not have finished when the primitive returns to its caller. Some actions may yield control before they can complete. For example, selecting ``Save As...'' from the ``File'' menu opens a dialog box and will not complete until the ``OK'' or ``Cancel'' button is pushed.
However, all testing functions wait at least a minimum interval
before returning to give the action a chance to finish.
This interval controls the speed at which the test suite runs,
and gives some slack time for events to complete.
The default interval is 100 milliseconds. The interval can be queried
or set with test:run-interval.
A primitive action will not return until the run-interval has
expired and the action has finished, raised an error, or yielded.
The number of incomplete actions is given by
test:number-pending-actions.
Note: Once a primitive action is started, it is not possible to undo it or kill its remaining effect. Thus, it is not possible to write a utility that flushes the incomplete actions and resets number-pending-actions to zero.
However, actions which do not complete right away often provide a way to cancel themselves. For example, many dialog boxes have a ``Cancel'' button which will terminate the action with no further effect. But this is accomplished by sending an additional action (the button push), not by undoing the original action.
Errors in the primitive actions (which necessarily run in the handler thread) are caught and reraised in the calling thread.
However, the primitive actions can only guarantee that the action has started, and they may return before the action has completed. As a consequence, an action may raise an error long after the function that started it has returned. In this case, the error is saved and reraised at the first opportunity (the next primitive action).
The test engine keeps a buffer for one error, saving only the first error. Any subsequent errors are discarded. Reraising an error empties the buffer, allowing the next error to be saved.
The function
test:reraise-error
reraises any pending errors.
Active Frame
The Self Test primitive actions all implicitly apply to the top-most (active) frame.
Thread Issues
The code started by the primitive actions must run in the handler thread of the eventspace where the event takes place. As a result, the test suite that invokes the primitive actions must not run in that handler thread (or else some actions will deadlock). See the eventspace section for more info.
Window Manager (Unix only)
In order for the Self Tester to work correctly, the window manager must set the keyboard focus to follow the active frame. This is the default behavior in Microsoft Windows and MacOS, but not in X windows.
In X windows, you must explicitly tell your window manager to set the keyboard focus to the top-most frame, regardless of the position of the actual mouse. Some window managers may not implement such functionality. You can obtain such an effect in Fvwm and Fvwm95 by using the option:
Style "*" ClickToFocus