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.
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.
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 -----------------------------------------
> t{ 1 1 +    -> 2 }t
> t{ 1 1 plus -> 2 }t
> t{ 1 1 plus -> 3 }t
INCORRECT RESULT: t{ 1 1 plus -> 3 }t
> t{ 1 2 plus -> 3 }t
> t{ $FFFF 1 plus -> 0 }t

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


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