Testing ChoiceScript

ChoiceScript has unit tests, written using the Dojo Objective Harness (DOH). You can run them with test.bat, or using the ant script with ant unittest. You can see the unit tests in tests/choiecescript/tests.

ChoiceScript also provides an “autotest” tool that you can use to verify that your scene is free of bugs. It won’t catch all logical problems ("hey, this should be *if (wounds < 5), not *if (wounds > 5)), but it will catch lots of common errors— incorrect indentation, undefined (or misspelled) variables or labels, dead code that can’t be reached regardless of variable settings and choices, and so forth. That’s particularly important because just running the interpreter won’t catch everything— if you introduce a bug in choice B of the first choice, the interpreter won’t see it if you pick choice A or choice C while manually testing. Just because you ran through your scene once or twice without an error message doesn’t mean that there isn’t a lurking bug.

The downside is that the current version of the autotester isn’t very user-friendly. You’ll have to be comfortable running programs from the command line.

To run the autotester, open a command shell and change directories until you’re in the top ChoiceScript directory. (It might be named something like dfabulich-choicescript-…)

On Windows, you can run it with autotest.bat, like:

autotest blahblah

On the Mac, you can run it via the ant script, like:

ant autotest -Dvig=blahblah

Where blablah is the name of the vignette you created. (You can also try running the autotester on one of our provided scenes, like startup.)

Don’t put .txt after the name of the vignette. The autotester adds it automatically, and will look for a non-existent file name blahblah.txt.txt if you put blahblah.txt as the name of the vignetted to be tested.

If it spits out a ton of line numbers with numbers next to them and ends with BUILD SUCCESSFUL, your vignette passed the autotest. If it gives you an error message, it’s trying to tell you what’s wrong with your vignette. Unfortunately, that can be pretty hard to interpret— improving the quality of the error messages is on our to-do list.

The autotest tool attempts to pursue every code path, including both sides of every “if” statement (even if not both sides are true). The object is to catch indentation errors, invalid lines of code, and *goto statements with non-existent labels.

The output is a list of lines and the number of times those lines were tested. It will also flag non-blank non-comment lines that were not tested. These lines are “UNCOVERED.” If the autotester is doing its job, those uncovered lines are unreachable; this is probably a mistake in your scene.