Testing

For quite some time it is a good practice to write test cases for software for and during the development. With them a developer can be sure that the words do what they are supposed to do. Forth has a long tradition in this area starting with the ANSI standard from 1994. John Hayes wrote a tester and defined a test case synatx which got into widespead use since then.

Amforth has adapted its code with the file lib/ans94/tester-amforth.frt. The changes from the original are rather minor: Turn all keywords into lowercase.

Prepare for Tests

The tester requires only marker which is defined in file:lib/ans94/core/marker.frt. There are no further dependencies.

Using Test Cases

The tester uses 4 words:

TESTING add your comment here

is a “talking comment” to make the output somehow look nice.

t{

starts a new test. Prepare the stack and call your function, then

->

indicates that the test code is complete. Add the remaining stack after this word.

}t

completes the test by comparing the stack with the expected stack. If everything is well, the ok prompt will appear.

A test summary is not printed, but that could

Write a file with your new library function, e.g.

\ function.frt
\ define some new function
: plus  + ;

Then write the test cases, e.g.

\ function-test.frt

\ load the tester from lib/ans94/tester
#include tester-amforth.frt

\ load the code under test
#include function.frt

\ run the tests
TESTING the tester -----------------------------------------

t{ 1 1 +    -> 2 }t
t{ 1 1 plus -> 2 }t
t{ 1 1 plus -> 3 }t \ incorrect
t{ 1 2 plus -> 3 }t \ tester contiues
t{ $FFFF 1 plus -> 0 }t
t{ 1 2 3 4 plus -> 1 2 7 }t

Now load the file function-test.frt to the controller and watch the show.

TESTING the tester -----------------------------------------
 ok
> t{ 1 1 +    -> 2 }t
 ok
> t{ 1 1 plus -> 2 }t
 ok
> t{ 1 1 plus -> 3 }t
INCORRECT RESULT: t{ 1 1 plus -> 3 }t
 ok
> t{ 1 2 plus -> 3 }t
 ok
> t{ $FFFF 1 plus -> 0 }t
 ok

With the command -ans-tester everythings gets unloaded and is ready for the next run.

Acknowlegment

This recipe is based upon an email from Erich Wälde on the amforth-devel mailing list.