Main Menu

SWELL - User Guide

This brief User Guide introduces the available resources, and explains how they
can be used to run the examples described or to run your own SWELL scripts.

Prerequisites

Apart from the contents of the
SWELL.zip file, you should get the latest
Abbot Java GUI Test Framework download, and have a 6.0+ JRE installed.
The software in SWELL.zip is mostly written in Scala,
but you do not need a Scala installation to use SWELL as described here.

SWELL "Hello world"

All of our examples will target VisualLangLab
(a convenient Swing application that is also used by SWELL as its
parser-generator).
So, if you are not at all familiar with VisualLangLab, take a quick look at the
Grammar without Tears article.
The following code is a SWELL script for testing two of VisualLangLab's
built-in sample grammars: ArithExpr and SimpleJSON.

The colored (blue, cyan, and red) lines are the structuring constructs. Every SWELL script
contains a single test suite delimited by a test header and trailer
(the blue lines).
The header and trailer include the suite's name
(SampleGrammars), which exists for documentation purposes only.
The header and trailer can both be optionally followed by
one or more SWELL statements that are executed at
the start and end of the suite respectively.

A suite contains one or more
tests, each starting with a test header (the red lines).
Each test header (the red lines) includes the test's name
(ArithExpr, SimpleJSON, etc.) and a string containing
a more verbose description of the test. Each test-header is followed by one
or more SWELL statements that are executed as
part of the test. Like JUnit (and other test frameworks) SWELL also has
ways of reporting the outcome of a test (e.g. the fail the test ...
in these examples).

Optional before and after sections (headed by the cyan lines)
list actions to be performed before and after each test respectively.

Figure-1 below shows this script in action.
It loads the two sample grammars one by one, provides grammar-specific test input for each
(in the Parser Test Input area),
runs the parser and verifies that the expected output appears
(in the Parser Log area) within one second.
A failure is reported if the verification fails.

Running your own SWELL Tests

obtain the latest VisualLangLab all-inclusive jar file
VLLS-All.jar,
and and place it in the swell directory

modify the launch.bat or launch script (depending on your host OS) to
add directories and jar/zip files of the system-under-test to the classpath. Save the modified
launcher script with a different name (e.g. launch-test.bat or launch-test)

using a text editor program, create one or more SWELL script files (equivalent to
the test-SampleGrammars.txt file). Use the
SWELL Language Manual for help with SWELL statements

run the test by using the new launcher script using the OS-specific directions provided
in the previous section. For example, if a new SWELL script file is named
edit-rates.txt, you can start it by entering the command
"launch-test edit-rates.txt"

Users should be aware that the parser's error-reporting capability is currently rudimentary,
and the error messages are sometimes not very helpful. However we expect to improve this aspect
progressively.