org.jwalk.core
Class Oracle

java.lang.Object
  org.jwalk.core.Oracle

public class Oracle
extends java.lang.Object

Oracle is the test oracle used to store and predict test outcomes. An Oracle is a data structure that maps from executed TestSequences to known test Outcomes. When a JWalker's test modality is set to VALIDATE, this causes an Oracle to be created for the current test class. Each executed TestSequence is compared against known sequences in the Oracle and, if the outcome can be predicted from existing information, the test is passed or failed automatically, otherwise the user is asked to confirm or reject the novel outcome, which is then added to the Oracle.

Oracles are saved in plain text files with the extension ".jwk", containing lists of key test sequences. A block of correct sequences appears first, followed by a blank line separator, then a block of incorrect sequences (if any). Each sequence consists of an encoded string, representing the actual invocation and arguments used, then the equals-sign, then the corresponding result. Deleting single lines from an Oracle data file is the chief way of causing JWalkers to "forget" certain learned outcomes altogether; whereas re-validating a test class is the chief way to re-train the Oracle, in the light of modifications made to the test class.

Version:

1.0

Author:

Anthony Simons

Field Summary

protected java.util.Map<java.lang.String,java.lang.String>	correct The collection of known correct test results, indexed by long key.
protected java.util.Map<java.lang.String,java.lang.String>	incorrect The collection of known incorrect test results, indexed by long key.
protected JWalker	walker The JWalker which requested this Oracle.

Constructor Summary

Oracle(JWalker walker)
Creates an Oracle for a particular JWalker.

Method Summary

boolean	close() Closes this Oracle, saving its test data.
boolean	open() Opens this Oracle, reading its test data.
Outcome	validate(TestSequence sequence) Validate a TestSequence from information known to this Oracle.

Methods inherited from class java.lang.Object

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

Field Detail

walker

protected JWalker walker

The JWalker which requested this Oracle. This Oracle must be able to discover the Oracle directory from the JWalker's Settings.

correct

protected java.util.Map<java.lang.String,java.lang.String> correct

The collection of known correct test results, indexed by long key.

incorrect

protected java.util.Map<java.lang.String,java.lang.String> incorrect

The collection of known incorrect test results, indexed by long key.

Constructor Detail

Oracle

public Oracle(JWalker walker)

Creates an Oracle for a particular JWalker. This Oracle inspects the Settings of the JWalker.

Parameters:

walker - the JWalker for whom this Oracle was created.

Method Detail

open

public boolean open()

Opens this Oracle, reading its test data. For a given test class named "TestClass", attempts to open a data file called "TestClass.jwk" in the oracle directory specified by settings.getOracleDirectory(). If no such data file can be found, assumes that this is a new Oracle and no result data yet exists. The only exception to this is where a new test class has a tested superclass, for which a data file can be found. In this case, the superclass's data file is used as the starting point.

Returns:

true if opening succeeded and data was read.

close

public boolean close()

Closes this Oracle, saving its test data. For a given test class named "TestClass", attempts to open a data file called "TestClass.jwk" in the oracle directory specified by settings.getOracleDirectory(). Writes the data file in the following format: all the correct test sequences, followed by a blank line, followed by all the incorrect test sequences. Each sequence consists of a long key representing the method invocation sequence, an equals sign "=", and the result of that sequence.

Returns:

true if closing succeeded and data was written.

validate

public Outcome validate(TestSequence sequence)

Validate a TestSequence from information known to this Oracle. This Oracle may pass or fail the TestSequence automatically, or ask the tester to confirm or reject the TestSequence. The TestSequence must have been executed, prior to validation.

Parameters:

sequence - the TestSequence to validate.

Returns:

a Outcome from {UNKNOWN, CONFIRMED, REJECTED, CORRECT, INCORRECT}.