JWalk
JWalk Tester Guide

JWalking is a fast and effective way to do Java unit testing.  All you need is a compiled Java class to test, and some indication of what test strategy to follow.  All testing is performed internally within the JWalk tool.  You may:

• inspect the test class's public interface, 

• explore its algebraic structure or state-space,

• exercise test sequences to explore its behaviour,

•  train a test oracle to pass or fail tests automatically.

Once a test oracle has been trained, retesting is fully automatic.  When the test class is modified, the oracle can be retrained in a short time.

The important thing is that JWalk determines the right method sequences that need to be tested, and explores the test class completely, to bounded depths.

Start JWalk

In your Linux, Windows or Mac file explorer, navigate to the root directory where you installed JWalk.  You should see the JWalk icon for the executable JAR-file.  Double-click on this JWalk icon.  

You should see the JWalk Tester GUI appear, with a splash screen welcome message.  

The JWalk splash screen on startup

Load the Test Class

In the Test Class panel, make sure that the Location is pointing to the root binary folder for the compiled class files that you want to test. This may be called C:/Eclipse/MyProject/bin in Eclipse.

In the Test Class panel, then select the Java package tree leading to the class you want to test. Make sure that the Name only refers to the full package-qualified name of the test class.

Launch the Configuration dialog in the Custom Settings panel, and decide where you wish to save any oracle files.  By default, this is the same directory as the Location root folder.

Pick the Test Settings

In the Test Settings panel, the Strategy options are:

• PROTOCOL to exercise all method protocols - this interleaves all public methods in all possible ways (costly);

• ALGEBRA (the default) to exercise all algebraic constructions - puts the test class into all of its low-level states and observes every method in each state;

• STATES to exercise all high-level states and transitions - puts the test class into each of its high-level states and observes method sequences in each state.

In the Test Settings panel, the Modality options are:

• INSPECT analyse the test class's public method API; and then optionally its algebraic structure, or its high-level state space (depending on the chosen Strategy);

• EXPLORE (the default) also execute a chosen test suite according to the chosen Strategy and Depth;

• VALIDATE also create a test Oracle, in which you will be asked to confirm selected test outcomes; a pop-up dialog will appear for each test sequence and result to be confirmed.

In the Test Settings panel, the Test Depth sets the maximum test sequence length, ranging from 0-20 (default value 3).

For test classes with very large APIs, start low and increase as time and memory permit.  Depths of 6-7 are reachable in a class with 10 public methods. Under some test settings, you may explore all possible tests.

Run JWalk

JWalk exploring all high-level states of a Stack

View the Results

In the large Results tabbed pane, you may view the results of a test run. Click on the appropriate tab to see the following:

• Protocol Analysis to see the public constructors and methods of the test class, or the public constants and methods of an enumerated type;

• Algebraic Analysis (only in the ALGEBRA Strategy) to see the primitive, transformer and observer operations of the test class. Primitives visit a new state. Transformers revisit an old state. Observers just inspect state.

• State Space Analysis (only in the STATE Strategy) to see the high-level states that were detected, based on Boolean state-predicate methods of the test class, and the shortest test sequences to reach each state.

• Test Cycle #0 to see the results of executing all constructors or enumerating all constants, with an analysis of a normal or exceptional result;

• Test Cycle #1 to see the results of executing all constructors and method sequences of length 1, with a further analysis of whether the state was unchanged;

• Test Cycle #N to see the results of executing all constructors and method sequences of length N, with a further analysis of whether a state was re-entered;

• Test Summary to see how many tests executed nominally or raised exceptions; how many tests were passed or failed; how many redundant tests were discarded; how many useful tests were picked from the total sequence permutations.

User Interaction

During execution of JWalk, the tester will be asked to interact with the tool, especially when building an oracle in the VALIDATE Modality.   Different dialogs that may pop up include:

• JWalk Query - asks the tester to confirm or reject the outcome of a selected test sequence;

• JWalk Notice - reports that JWalk has taken some action that requires the tester's acknowledgement;

• JWalk Warning - reports that JWalk has encountered some limit that requires an acknowledgement;

• JWalk Error - reports that some human error or system fault was detected that requires an acknowledgement.

Custom Settings

Launch the Configuration dialog in the Custom Settings panel to review rarely-changed configuration options.

• Test Oracle - allows the tester to select a specific directory in which JWalk oracle files will be stored.

• Test Convention - allows the tester to choose how many of the root class Object's inherited methods to interleave in tests:

  1. • STANDARD - exclude all of Object's methods;

     • CUSTOM - include only some of Object's methods;

     • COMPLETE - include all of Object's methods.

• Probe Depth - sets how long probing test sequences need to be to analyse the algebraic properties of the test class (default 12).

• State Depth - sets how to compare object states;  0 is shallow equality, 1 is deep equality (tree depth 1), etc. (default 0).

Uploading a custom RedirectInGenerator to JWalk