JWalk
JWalk Utility Guide

The command-line version of JWalk allows you to do all the same things you can with the standalone 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.

The only difference is that all input and output is on the command-line, in a console window.  The command-line processor reads all the test settings that you supply to the tool.

Run JWalk Utility

In the command console, go to the root directory in which you installed the unbundled JWalk download.  The package tree structure for your compiled Java test classes should also be directly under this root directory.

In the console window, type:

java org.jwalk.tool.JWalkUtility <test-class> [<other-args>]

This will launch JWalk Utility with the given test-class and further test settings supplied in other-args.  The only compulsory argument is the pathname of the test-class.  

The optional arguments follow after the test-class on the same command-line, separated by a space, and may be supplied in any order.  If none are supplied, the tool uses default settings.

Pick the Other Arguments

The optional command-line arguments are lowercase symbols and digits, and include:

Test Strategy, one of:

• protocol - exercise all method protocols,

• algebra - exercise all algebraic constructions (default),

• states - exercise all states and transitions.

Test Modality, one of:

• inspect - just inspect the test class's interface,

• explore - also exercise specified test sequences (default),

• validate - also validate the results of the tests.

Test Depth, in one of the formats:

• t0..tn - the maximum length of test sequences (default t3).

• 0..n - means the same as t0..tn

Probe Depth, in the format:

• p0..pn - the maximum length of probes (default p12).

State Depth, in the format:

• s0..sn - the maximum comparison tree-depth (default s0).

Convention, one of:

• standard - ignore Object's methods

• custom - include some of Object's methods

• complete - include all of Object's methods

Generator, the name of a custom generator, which:

• must have a name ending in Generator

• if unqualified, names a class in the current working directory

• if package-qualified, names a class in a package under the working directory, or known on the CLASSPATH

See how to Customise JWalk for more on custom generators.

Default Exploration

JWalk exploring all method protocols of a Wallet

Standard Exploration

By supplying further arguments, we can alter the test parameters, for example to test the state-space of the specimen ReservableBook provided:

java org.jwalk.tool.JWalkUtility org.jwalk.test.ReservableBook states t4 

This will explore all high-level states and transitions of a ReservableBook to a test depth of 4.  The output will contain:

• Protocol Report - describing the ReservableBook's public interface;

• State Space Report - identifying the four states:  Default, OnLoan, Reserved, Reserved&OnLoan;

• Test Cycle Reports - for each of the four states, detailing the results of executing constructors and sequences of methods, up to a maximum length of 4.

• Summary Report - detailing the total number of test sequences, which were normal,which raised exceptions and which were pruned.

Explicit Validation

The following example validates all algebraic constructions of the Stack class to a test depth 3:

java org.jwalk.tool.JWalkUtility org.jwalk.test.Stack validate t3

Assuming no previous oracle exists, the tool will present queries to the tester interactively, to confirm certain test outcomes:

Stack target = new Stack();
  target.isEmpty();
  ==> true

Confirm? (y|n|q): 

The tester should then enter a single character at the keyboard:  y = yes, to confirm a correct outcome (the right response in this case);  n = no, to confirm an incorrect outcome; and q = quit, to abort the current test series.

At the end of the final test cycle, the tool will notify the tester about the creation of the oracle file:

The oracle file `Stack.jwk' was written to:
/java/jwalk/root/

OK? (y): 

The tester need only enter y or just hit carriage return to acknowledge.

Custom Exploration