Skip to main content

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.

Suite SampleGrammars begins with
 - Launch vll.gui.VllGui.main()
 - Wait for frame "VisualLangLab/S"
 - clearLogButton is the button with ToolTipText = "Clear log"
 - parseInputButton is the button with ToolTipText = "Parse input"
 - parserInputArea is the 3rd textcomponent
 - logTextPane is the 4th textcomponent
Before each test 
 - clear text in ${logTextPane}
 - clear text in ${parserInputArea}
After each test 
 - delay 500 ms
Test ArithExpr "Check ArithExpr" is
 - select "Help" -> "Sample grammars" -> "ArithExpr" from the menubar
 - Wait for frame "VisualLangLab sample.*"
 - delay 1 second
 - click the "OK" button of the "VisualLangLab sample.*" dialog
 - key "3 * 5" into ${parserInputArea}
 - click ${parseInputButton}
 - fail the test with message "Bad parse result" unless ${logTextPane} contains 
       "Array(Array(Pair(0, 3), List(Pair(0, Pair(0, 5)))), List())" within 1 s
Test SimpleJSON "Check SimpleJSON" is
 - select "Help" -> "Sample grammars" -> "SimpleJSON" from the menubar
 - Wait for frame "VisualLangLab sample.*"
 - delay 1 second
 - click the "OK" button of the "VisualLangLab sample.*" dialog
 - key "{\"name\":\"Centurion\"}" into ${parserInputArea}
 - click ${parseInputButton}
 - fail the test with message "Bad parse result" unless ${logTextPane} contains 
     "Pair(0, Array({, List(Array(\"name\", :, Pair(2, \"Centurion\"))), }))" 
     within 2 seconds
Suite SampleGrammars ends with
 - pause "We're done! Please click the \"OK\" button to exit."

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.

SWELL in action!
Figure 1. SWELL in action!

Running the Examples below has instructions on how to run this script. Most readers should have no problem deciphering this SWELL script, but if you need help use the SWELL Language Manual below.

Running the Examples

To run the examples shown, proceed as follows (this runs the Hello world script above):

  • download the SWELL.zip file, and unzip the contents into a directory (called swell)
  • obtain the latest download from the Abbot Java GUI Test Framework, and copy all its jar files into the swell directory
  • obtain the latest VisualLangLab all-inclusive jar file VLLS-All.jar, and and place it in the swell directory
  • on Windows: open a CMD window, cd into the swell directory, and run the command "launch.bat test-SampleGrammars.txt"
  • on Linux/Mac OS/*NIX: at a shell prompt, cd into the swell directory, and run the command "chmod +x launch". Then run the command "launch test-SampleGrammars.txt"
  • after completion of the OS-specific actions described in the previous two points, there is a delay of 10-30 seconds before any activity is visible. Do not touch the mouse till the end of the tests
  • at the end of the test, a dialog is displayed (as in Figure-1 above), click the "OK" button to exit the test environment
  • a detailed test log can be found in the file named test-SampleGrammars.log

Running your own SWELL Tests

To create a new SWELL test script proceed as follows:

  • download SWELL.zip and unzip into the swell directory. Add jar files from the Abbot Java GUI Test Framework as described above
  • 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.

 
 
Close
loading
Please Confirm
Close