Tests and Documentation
Factor handbook ยป Guided tour of Factor

Next:The Object System

This is a good time to start writing some unit tests. You can create a skeleton with
"github.tutorial" scaffold-tests

You will find a generated file under work/github/tutorial/tutorial-tests.factor, that you can open with "github.tutorial" edit-tests. Notice the line
USING: tools.test github.tutorial ;

that imports the unit testing module as well as your own. We will only test the public prime? function.

Tests are written using the unit-test word, which expects two quotations: the first one containing the expected outputs, and the second one containing the words to run in order to get that output. Add these lines to github.tutorial-tests:
{ t } [ 2 prime? ] unit-test { t } [ 13 prime? ] unit-test { t } [ 29 prime? ] unit-test { f } [ 15 prime? ] unit-test { f } [ 377 prime? ] unit-test { f } [ 1 prime? ] unit-test { t } [ 20750750228539 prime? ] unit-test

You can now run the tests with "github.tutorial" test. You will see that we have actually made a mistake, and pressing F3 will show more details. It seems that our assertions fails for 2.

In fact, if you manually try to run our functions for 2, you will see that our definition of [2..b] returns { 2 } for 2 sqrt, due to the fact that the square root of two is less than two, so we get a descending interval. Try making a fix so that the tests now pass.

There are a few more words to test errors and inference of stack effects. Using unit-test suffices for now, but later on you may want to check the main documentation on Unit testing.

We can also add some documentation to our vocabulary. Autogenerated documentation is always available for user-defined words (even in the listener), but we can write some useful comments manually, or even add custom articles that will appear in the online help. Predictably, we start with "github.tutorial" scaffold-docs and "github.tutorial" edit-docs.

The generated file work/github/tutorial-docs.factor imports help.markup and help.syntax. These two vocabularies define words to generate documentation. The actual help page is generated by the HELP: parsing word.

The arguments to HELP: are nested array of the form { $directive content... }. In particular, you see here the directives $values and $description, but a few more exist, such as $errors, $examples and $see-also.

Notice that the type of the output ? has been inferred to be boolean. Change the first lines to look like
USING: help.markup help.syntax kernel math ; IN: github.tutorial HELP: prime? { $values { "n" fixnum } { "?" boolean } } { $description "Tests if n is prime. n is assumed to be a positive integer." } ;

and refresh the github.tutorial vocabulary. If you now look at the help for prime?, for instance with \ prime? help, you will see the updated documentation.

You can also render the directives in the listener for quicker feedback. For instance, try writing
{ $values { "n" integer } { "?" boolean } } print-content

The help markup contains a lot of possible directives, and you can use them to write stand-alone articles in the help system. Have a look at some more with "element-types" help.