org.jwalk.core
Class ProtocolWalker

java.lang.Object
  org.jwalk.JWalker
      org.jwalk.core.ClassInspector
          org.jwalk.core.ProtocolWalker

All Implemented Interfaces:

java.lang.Runnable

Direct Known Subclasses:

AlgebraWalker, StateSpaceWalker

public class ProtocolWalker
extends ClassInspector

ProtocolWalker exercises all the method protocols of a test class. A ProtocolWalker explores all possible permutations of the test class's public methods. It constructs test sequences, starting with all of the test class's public constructors, then extends these with all possible interleaved orderings of the test class's public methods.

Version:

1.0

Author:

Anthony Simons

Field Summary

protected Oracle	oracle The test oracle used to store and predict test outcomes.
protected SummaryReport	summary The test summary report that is published when testing is finished.

Fields inherited from class org.jwalk.core.ClassInspector

constants, constructors, methods, testClass

Fields inherited from class org.jwalk.JWalker

channels, settings

Constructor Summary

ProtocolWalker(Settings settings, Channels channels)
Creates a ProtocolWalker, using the settings and channels.

Method Summary

protected void	ensureExecutable() Checks that the test class may indeed be executed.
void	execute() Executes this ProtocolWalker test strategy according to the settings.
protected void	executeTestCycle(java.util.List<TestSequence> testSet, int cycle) Executes a test set for a given test cycle and reports the results.
protected void	executeTestSeries() Executes a series of test cycles on paths of increasing length.
protected java.util.List<TestSequence>	firstCycle() Creates the first test set, consisting of singleton TestSequences made from each of the public Constructors (or enumerated constants) of the test class.
protected boolean	isPrunable(TestSequence sequence) Reports whether a given TestSequence may be pruned.
protected ObjectGenerator	makeGenerator() Factory method to produce a suitably customised ObjectGenerator.
protected java.util.List<TestSequence>	nextCycle(java.util.List<TestSequence> oldCycle) Creates a subsequent test set, consisting of TestSequences from the previous cycle which have been extended with every Method in the test class's public interface.

Methods inherited from class org.jwalk.core.ClassInspector

classIsAbstract, classIsEnum, classIsInterface, classNotPublic, countActiveEdges, countConstants, countConstructors, countMethods, countPermutations, getConstants, getConstructors, getMethods, getTestClass, inspectProtocols

Methods inherited from class org.jwalk.JWalker

getChannels, getSettings, outOfMemory, run, userAborted

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

oracle

protected Oracle oracle

The test oracle used to store and predict test outcomes. The oracle is not used in the TestModes INSPECT and EXPLORE, but is used in the Modality VALIDATE.

summary

protected SummaryReport summary

The test summary report that is published when testing is finished. This SummaryReport gathers statistical data from each individual CycleReport published during testing.

Constructor Detail

ProtocolWalker

public ProtocolWalker(Settings settings,
                      Channels channels)

Creates a ProtocolWalker, using the settings and channels.

Parameters:

settings - the test parameter settings to use.

channels - the call-back channels to report on.

Method Detail

isPrunable

protected boolean isPrunable(TestSequence sequence)

Reports whether a given TestSequence may be pruned. By default, any TestSequence which terminated with an Exception may be pruned before the next test cycle, since such a sequence would always fail at the same place. This reduces the branching factor, as method paths are explored. It is also assumed that exceptions are only raised at the leaves of the method path tree; and any exceptions raised earlier are an indication that the tested software is behaving randomly.

Parameters:

sequence - the TestSequence being evaluated.

Returns:

true if the TestSequence terminated with an Exception.

makeGenerator

protected ObjectGenerator makeGenerator()
                                 throws PermissionException

Factory method to produce a suitably customised ObjectGenerator. Creates a standard ObjectGenerator, but then adds to it as many custom generators as were loaded into the settings. Attempts to create an instance of each custom generator class, and adds each one as a delegate of the main ObjectGenerator. If any of the custom generators cannot be instantiated, raises a PermissionException.

Returns:

the customised ObjectGenerator.

Throws:

PermissionException - if any custom generator could not be instantiated, either for reasons of security, or visibility, or because it was abstract, or an interface.

ensureExecutable

protected void ensureExecutable()
                         throws PermissionException

Checks that the test class may indeed be executed. If the test class cannot be executed, raises a PermissionException. This method is called at the start of every dynamic analysis, whether this is at the start of a probing cycle, or a main test cycle.

Throws:

PermissionException - if the loaded test class could not be instantiated, either for reasons of security, or visibility, or because it was abstract, or an interface.

firstCycle

protected java.util.List<TestSequence> firstCycle()

Creates the first test set, consisting of singleton TestSequences made from each of the public Constructors (or enumerated constants) of the test class. The returned test set is a list of TestSequences, where each sequence contains a single TestCase, either a CreateTestCase for a class with constructors, or an EnumTestCase for an enumerated type.

Returns:

a List of initial TestSequences.

nextCycle

protected java.util.List<TestSequence> nextCycle(java.util.List<TestSequence> oldCycle)

Creates a subsequent test set, consisting of TestSequences from the previous cycle which have been extended with every Method in the test class's public interface. In ProtocolWalker, old TestSequences which terminated in an Exception are pruned and all other paths are extended.

Parameters:

oldCycle - the test set from the previous cycle.

Returns:

the new List of TestSequences.

executeTestCycle

protected void executeTestCycle(java.util.List<TestSequence> testSet,
                                int cycle)
                         throws PermissionException,
                                GeneratorException,
                                ExecutionException

Executes a test set for a given test cycle and reports the results.

Parameters:

testSet - the test set for the current test cycle.

cycle - the current test cycle number, 0..n.

Throws:

GeneratorException - if any constructor or method argument value could not be synthesised. A CustomGenerator must be provided that is capable of synthesising values of the argument type.

ExecutionException - if any constructor or method could not be invoked, for reasons of visibility, security or bad arguments, or if it is detected that a constructor or method behaves randomly.

PermissionException - if the loaded test class, or any custom generator, could not be instantiated, either for reasons of security, or visibility, or because it was abstract, or an interface.

executeTestSeries

protected void executeTestSeries()
                          throws PermissionException,
                                 GeneratorException,
                                 ExecutionException

Executes a series of test cycles on paths of increasing length. Executes a series of test cycles, starting with test paths of length 0 (invoking all the test class's constructors) and continuing with longer test paths in subsequent cycles, up to the maximum requested test path depth. At the end of the series, dispatches a SummaryReport to the registered listeners. May also read from, and write to an Oracle, if the settings requested validation of the results.

Throws:

GeneratorException - if any constructor or method argument value could not be synthesised. A CustomGenerator must be provided that is capable of synthesising values of the argument type.

ExecutionException - if any constructor or method could not be invoked, for reasons of visibility, security or bad arguments, or if it is detected that a constructor or method behaves randomly.

PermissionException - if the loaded test class, or any custom generator, could not be instantiated, either for reasons of security, or visibility, or because it was abstract, or an interface.

execute

public void execute()
             throws PermissionException,
                    GeneratorException,
                    ExecutionException

Executes this ProtocolWalker test strategy according to the settings. If the Modality is INSPECT, extracts the public constructor and method interface of the test class. If the Modality is EXPLORE, also explores all interleaved method permutations to the requested test path depth. If the Modality is VALIDATE, also validates the outcomes of every test using an Oracle.

Overrides:

execute in class ClassInspector

Throws:

GeneratorException - if any constructor or method argument value could not be synthesised. A CustomGenerator must be provided that is capable of synthesising values of the argument type.

ExecutionException - if any constructor or method could not be invoked, for reasons of visibility, security or bad arguments, or if it is detected that a constructor or method behaves randomly.

PermissionException - if the loaded test class, or any custom generator, could not be instantiated, either for reasons of security, or visibility, or because it was abstract, or an interface.