org.jwalk
Class Settings
java.lang.Object
org.jwalk.Settings
public class Settings
- extends java.lang.Object
Settings is the API through which client programs set up the various
test parameters for a JWalker. The only obligatory parameter to set is
the testClass. Client programs may supply this directly as
a class-object, or specify where to find it in the filesystem. The
remaining parameters have suitable default values, but may be set to
different values using this API.
Key test parameters include the test strategy, which
determines whether test sequences explore all method protocols, all
algebraic constructions, or all high-level states and transitions; the
test modality, which determines whether the test class is
inspected, exercised or validated (the latter creates an oracle); and
the testDepth, which bounds the maximum length of
test sequences.
Other parameters which customise the behaviour of the tools include
the probeDepth, which controls how far to probe into
an object's state space during analysis; the treeDepth,
which determines whether object states are compared in a shallow, or deeper
way; the test convention, which determines how much of the
standard behaviour of class Object is to be tested; and the ability to
add custom generator classes, which synthesise test inputs
in a different way from the default generators.
Finally, the directories in which the test class, custom generators, and
oracle files are to be found or placed may be specified.
- Version:
- 1.0
- Author:
- Anthony Simons
|
Constructor Summary |
Settings()
Creates a standard collection of Settings. |
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Settings
public Settings()
- Creates a standard collection of Settings. The minimum intervention
required is for the tester to provide the test class. Other settings
are initialised to suitable default values. The default test strategy
and modality are algebraic exploration. The default convention is not
to include Object's methods. The default probe depth is 12 and the
default test depth is 3. The default object tree-depth for state
comparison is 0 (shallow state). Several custom generators are always
loaded by default, including: StringGenerator, InterfaceGenerator,
EnumGenerator and PlatformGenerator.
getTestDepth
public int getTestDepth()
- Returns the maximum depth to which paths are explored during testing.
This controls how many test cycles are performed in a given test
series. By default, this has the value 3.
- Returns:
- the test path depth.
getProbeDepth
public int getProbeDepth()
- Returns the maximum depth to which paths are explored during analysis.
This controls how deeply an initial analysis probes into an object's
algebra or state space, seeking to discover new concrete states.
- Returns:
- the probe path depth. By default, this has the value 12.
getTreeDepth
public int getTreeDepth()
- Returns the depth to which object state is inspected. This controls
whether object states are compared in a shallow, medium or deep way.
By default, this has the value zero, meaning that object states are
compared in a shallow way (pair-wise comparing their attributes,
references and primitive array elements). Certain test strategies
identify when an object returns to a previously-visited state, in
order to prune redundant test sequences.
- Returns:
- the object state inspection depth.
getStrategy
public Strategy getStrategy()
- Returns the test strategy, one of {PROTOCOL, ALGEBRA, STATES}.
This controls whether we explore all method protocols, all algebraic
constructions, or the abstract design-state space. The PROTOCOL
strategy generates test sequences corresponding to every possible
interleaved ordering of the test class's constructors and methods.
The ALGEBRA strategy generates test sequences correspondng to every
novel algebraic construction, that is, which drive the test object
into novel concrete states (this is the default setting). The
STATES strategy generates test sequences corresponding to the state
cover, transition cover, and n-switch cover, which drive the test
object through all of its high-level states and transitions.
- Returns:
- the test strategy
getModality
public Modality getModality()
- Returns the test modality, one of {INSPECT, EXPLORE, VALIDATE}. This
controls whether we stop after an initial analysis of the test class;
or explore all of the test sequences determined by the current test
strategy, or validate all of these test sequences interactively,
creating an oracle to store key test results. By default, this has
the setting: EXPLORE.
- Returns:
- the test modality
getConvention
public Convention getConvention()
- Returns the test convention, one of {STANDARD, CUSTOM, COMPLETE}. This
controls how many of the built-in methods of class Object are included
in generated test sequences. The default setting is STANDARD, which
excludes all of class Object's built-in methods. CUSTOM includes the
four methods
equals(), hashCode(),
toString() and getClass(). COMPLETE includes all
of class Object's built-in methods.
- Returns:
- the test convention.
getTestClassDirectory
public java.io.File getTestClassDirectory()
- Returns the directory in which the test class is to be found. By
default this is the current working directory. The test class must
be accessible from this directory, meaning that either the class file
is contained in this directory, or the root of the package containing
the test class is in this directory.
- Returns:
- the test class directory.
getGeneratorDirectory
public java.io.File getGeneratorDirectory()
- Returns the directory in which any custom generators are to be found.
By default this is the same as the test class directory. Any custom
generator class files must be accessible from this directory, meaning
that either they are contained in this directory, or the root of the
package that contains the generators is in this directory.
- Returns:
- the custom generator directory.
getOracleDirectory
public java.io.File getOracleDirectory()
- Returns the directory in which test oracles are written and read.
By default this is the same as the test class directory. If the
validation strategy is selected, the JWalker will look for an oracle
data file in this directory. If no such oracle data file exists, a
new oracle data file will be created and stored here.
- Returns:
- the test oracle directory.
getTestClass
public java.lang.Class<?> getTestClass()
- Returns the current test class. This is the class whose behaviour
will be inspected, exercised or validated by the JWalker. This is
the only test parameter that must always be supplied by the tester.
- Returns:
- the test class
getCustomGenerators
public java.util.List<java.lang.Class<CustomGenerator>> getCustomGenerators()
- Returns the list of custom generators. The tester may have
supplied one or more custom generator classes, to be used by a
JWalker to synthesise test inputs. If so, the JWalker will load
the custom generators using this method. By default, this method
returns an empty list.
- Returns:
- the custom generators, possibly an empty list.
setTestDepth
public void setTestDepth(int depth)
- Sets the maximum depth to which paths are explored during testing.
This controls how many test cycles are performed in a given test
series. The supplied depth is typically a small positive integer
and cannot be less than zero (which is the default minimum value).
A depth of zero will initialise the test object (possibly in each
of its states) and higher values will exercise method sequences
up to that length (possibly starting from each state).
- Parameters:
depth - the test path depth to set.
setProbeDepth
public void setProbeDepth(int depth)
- Sets the maximum depth to which paths are explored during analysis.
This controls how deeply an initial analysis probes into an object's
algebra or state space, seeking to discover new concrete states.
This cannot be less than zero (the default minimum value). For the
greatest efficiency, set this to just above the longest path that
reaches the test object's furthest state. Setting this limit too high
will slow down performance dramatically during inspections, with a risk
of running out of memory. Also, it is advisable to set this parameter
to low values, or zero, if probing the test class would cause many
destructive actions to occur (such as creating or deleting files).
- Parameters:
depth - the maximum path depth to set.
setTreeDepth
public void setTreeDepth(int depth)
- Sets the depth to which object state is inspected. This controls
whether object states are compared in a shallow, medium or deep way.
By default, this has the value zero, meaning that object states are
compared in a shallow way (pair-wise comparing their attributes,
references and primitive array elements). A setting of one means
that all objects directly reachable from the test object will also
compare their states, recursively. A setting of two means that all
reachable objects in chains of length two will be compared. The
smallest setting that covers all the meaningful concrete states of
the test object is best, and will result in the greatest pruning of
redundant test sequences.
- Parameters:
depth - the depth of object state exploration to set.
setStrategy
public void setStrategy(Strategy strategy)
- Sets the test strategy to use when executing a JWalker. This is an
enumerated Strategy, one of {PROTOCOL, ALGEBRA, STATES}. It controls
whether the JWalker explores all method protocols, all algebraic
constructions, or the abstract design-state space. The PROTOCOL
strategy generates test sequences corresponding to every possible
interleaved ordering of the test class's constructors and methods.
The ALGEBRA strategy generates test sequences correspondng to every
novel algebraic construction, that is, which drive the test object
into novel concrete states (this is the default setting). The
STATES strategy generates test sequences corresponding to the state
cover, transition cover, and n-switch cover, which drive the test
object through all of its high-level states and transitions.
- Parameters:
strategy - the test strategy to set.
setModality
public void setModality(Modality mode)
- Sets the test modality to use when executing a JWalker. This is an
enumerated Modality, one of {INSPECT, EXPLORE, VALIDATE}. It controls
whether the JWalker stops after an initial analysis of the test class;
or explores all of the test sequences determined by the current test
strategy, or validates all of these test sequences interactively,
creating an oracle to store key test results. By default, this has
the setting: EXPLORE.
- Parameters:
mode - the test modality to set.
setConvention
public void setConvention(Convention convention)
- Sets the test convention to use when executing a JWalker. This is an
enumerated Convention, one of {STANDARD, CUSTOM, COMPLETE}. It controls
how many of the built-in methods of class Object are included in the
generated test sequences. The default setting is STANDARD, which
excludes all of class Object's built-in methods. CUSTOM includes the
four methods
equals(), hashCode(),
toString() and getClass(). COMPLETE includes all
of class Object's built-in methods.
- Parameters:
convention - the test protocol to set.
setTestClassDirectory
public void setTestClassDirectory(java.io.File directory)
- Changes the default test class directory. Causes the current
ClassLoader to become invalid.
- Parameters:
directory - the test class directory to set.
setGeneratorDirectory
public void setGeneratorDirectory(java.io.File directory)
- Changes the default custom generator directory. Causes the
current ClassLoader to become invalid.
- Parameters:
directory - the custom generator directory to set.
setOracleDirectory
public void setOracleDirectory(java.io.File directory)
- Changes the default test oracle directory.
- Parameters:
directory - the test oracle directory to set.
setTestClass
public void setTestClass(java.lang.Class<?> testClass)
- Sets the test class directly. Assumes that the environment has
obtained the test class by some other means. Client programs may
reset the test class multiple times within the same Java runtime,
if this is desired.
- Parameters:
testClass - the testClass to set
setTestClass
public void setTestClass(java.lang.String name)
throws LoaderException
- Sets the test class by its name. The name is either the simple, or
package-qualified name of the test class. Assumes that this class may
be found in the test class directory, by default the current directory.
A new ClassLoader is used each time, so that the test class may be
reloaded multiple times within the current Java runtime, for example
after it has been edited and recompiled in response to detected faults.
A bespoke dynamic subclass of URLClassLoader is created, which can
distinguish between the test class and other classes on which the test
class depends. Only the test class is reloaded; and all other classes
are loaded by the same loader used for custom Generators.
- Parameters:
name - the name of the test class to load.
- Throws:
LoaderException, - if the named class does not exist, or if it was
accessed incorrectly, without using its package-qualified name.
LoaderException
addCustomGenerator
public void addCustomGenerator(java.lang.Class<CustomGenerator> generator)
- Adds a custom Generator class to the set of custom generators.
A Generator is an object which synthesises inputs for the methods
of the test class. JWalkers use a standard set of generators, which
synthesise test inputs in predictable ways. The tester may supply
one or more custom Generators, to take control of how test inputs are
generated for certain types of method argument. Typically, a custom
Generator synthesises values of one, or a few, argument types. This
method uploads the class-object for a custom generator. It assumes
that the environment has obtained the generator class by some means.
- Parameters:
generator - the custom generator to add.
addCustomGenerator
public void addCustomGenerator(java.lang.String name)
throws LoaderException
- Adds a custom Generator by its name. The name is either the simple,
or package-qualified name of the Generator class. Assumes that the
Generator class may be found in the custom generator directory, by
default the current directory. Generators may be loaded once into
each Java runtime and are not reloaded if changed. This is because
JWalkers make assumptions about the Generator interface and the
other classes to which generators may refer.
- Parameters:
name - the name of the custom generator to add.
- Throws:
LoaderException, - if the named generator class does not exist,
or if it was accessed incorrectly, without using its package-qualified
name, or if the loaded class was not in fact a generator.
LoaderException
removeCustomGenerator
public void removeCustomGenerator(java.lang.Class<CustomGenerator> generator)
- Removes a custom Generator from the set of custom generators. If
the generator is present in the list of custom generators, it is
removed; otherwise no action is taken.
- Parameters:
generator - the custom generator to remove.
removeCustomGenerator
public void removeCustomGenerator(java.lang.String name)
- Removes a custom Generator by its name. If a generator exists with the
given name in the list of custom generators, it is removed; otherwise
no action is taken.
- Parameters:
name - the name of the custom generator to remove.