org.jwalk.core
Class TestSequence

java.lang.Object
  extended by org.jwalk.core.TestSequence

public class TestSequence
extends java.lang.Object

TestSequence represents a constructor and method invocation sequence. Each TestSequence starts with a CreateTestCase invoking a Constructor, or an EnumTestCase declaring an enumerated constant, followed by zero or more InvokeTestCases, each invoking one of the test class's Methods. Each TestSequence is a unique invocation sequence, created by a JWalker to explore some aspect of the test class's behaviour.

A TestSequence is created from scratch, or by copying and extending an existing TestSequence. Each TestSequence is then executed once, which creates an instance of the test class, known as the target, and drives this object through its paces. Once the TestSequence has been executed, it is possible to determine if it executed normally, raised an exception; and whether it changed the state of the target, or returned to a previously-visited state. If the TestSequence is then judged by an Oracle, it is possible to determine whether the TestSequence was passed or failed, with reference to the expected test outcome.

Version:
1.0
Author:
Anthony Simons

Constructor Summary
TestSequence()
          Creates a new empty TestSequence.
TestSequence(TestSequence prefix)
          Creates a true copy of the prefix TestSequence.
 
Method Summary
 void add(TestCase testCase)
          Adds a TestCase to the end of this TestSequence.
 java.lang.Object execute(ObjectGenerator generator)
          Executes this TestSequence and returns the result.
 java.lang.String getLongKey()
          Returns a unique long indexing key for this TestSequence.
 java.lang.reflect.Member getOperation()
          Returns the last operation executed in this TestSequence.
 Outcome getOutcome()
          Returns the test outcome, as judged by an Oracle.
 java.lang.Object getResult()
          Returns the result of this TestSequence.
 java.lang.Class<?> getReturnType()
          Returns the expected type of the last operation in this TestSequence.
 java.util.List<TestCase> getSequence()
          Returns the TestCases making up this TestSequence.
 java.lang.String getShortKey()
          Returns a short indexing key for this TestSequence.
 java.lang.Object getTarget()
          Returns the target object in its final state.
 boolean hasExecuted()
          Reports whether this TestSequence has been executed.
 boolean hasFailed()
          Reports whether this TestSequence has been failed.
 boolean hasPassed()
          Reports whether this TestSequence has been passed.
 boolean hasSucceeded()
          Reports whether this TestSequence executed normally.
 boolean hasTerminated()
          Reports whether this TestSequence terminated with an exception.
 boolean isConfirmed()
          Reports whether this TestSequence has been manually confirmed.
 boolean isCorrect()
          Reports whether this TestSequence is automatically correct.
 boolean isIncorrect()
          Reports whether this TestSequence is automatically incorrect.
 boolean isReentrant()
          Reports whether this TestSequence re-entered a visited state.
 boolean isRejected()
          Reports whether this TestSequence has been manually rejected.
 boolean isUnchanged()
          Reports whether this TestSequence ended with no state change.
 boolean isValidated()
          Reports whether this TestSequence has been passed or failed.
 java.lang.String oracleResult()
          Returns the oracle value for the result of this TestSequence.
 void setOutcome(Outcome outcome)
          Sets the test outcome, as judged by an Oracle.
 int size()
          Returns the size of this TestSequence.
 java.lang.String toString()
          Returns a formatted representation of this TestSequence.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

TestSequence

public TestSequence()
Creates a new empty TestSequence. This is used when a new TestSequence is first created. Creates a TestSequence with the initial capacity for one TestCase.


TestSequence

public TestSequence(TestSequence prefix)
Creates a true copy of the prefix TestSequence. This is used when this TestSequence is about to be extended in the next test cycle. Creates a TestSequence with the capacity for one more TestCase. Copying a TestSequence clones each TestCase, such that the same return type, parameter types and operations are preserved, but the values assigned to these are not copied, but will be generated again when this TestSequence is executed.

Parameters:
prefix - the prefix TestSequence.
Method Detail

add

public void add(TestCase testCase)
Adds a TestCase to the end of this TestSequence. Adds the given testCase to the end of this TestSequence. The first TestCase in a TestSequence must always be CreateTestCase (invoking a Constructor) or an EnumTestCase (naming an Enum constant). Each following TestCase is expected to be an InvokeTestCase (invoking a Method). JWalkers observe this rule internally. Failure to do so would cause test execution to behave unpredictably.

Parameters:
testCase - the new TestCase to add.

size

public int size()
Returns the size of this TestSequence. This is the number of TestCases making up the sequence.

Returns:
the size of this TestSequence.

getSequence

public java.util.List<TestCase> getSequence()
Returns the TestCases making up this TestSequence.

Returns:
the list of TestCases.

getOperation

public java.lang.reflect.Member getOperation()
Returns the last operation executed in this TestSequence. If there are no TestCases in this TestSequence, returns null. Otherwise, returns the last Constructor or Method that was being exercised, or a Field if the TestCase referred to an enumerated constant. This method is used when determining the algebraic category of operations.

Returns:
the last operation in this TestSequence, or null.

getReturnType

public java.lang.Class<?> getReturnType()
Returns the expected type of the last operation in this TestSequence. If there are no TestCases in this TestSequence, returns null. Otherwise returns the expected type of the result. Note that this may not be the same as the actual type. This is used by the Oracle to validate void methods quickly.

Returns:
the return-type of the last operation or constant.

getTarget

public java.lang.Object getTarget()
Returns the target object in its final state. Only valid after this TestSequence has been executed.

Returns:
the target object.

getResult

public java.lang.Object getResult()
Returns the result of this TestSequence. Only valid after this TestSequence has been executed.

Returns:
the result object.

oracleResult

public java.lang.String oracleResult()
Returns the oracle value for the result of this TestSequence. This is a unique encoding of the result as a String, which allows different objects to be compared across test runs. Only valid after this TestSequence has been executed.

Returns:
the oracle value for the result.

execute

public java.lang.Object execute(ObjectGenerator generator)
                         throws GeneratorException,
                                ExecutionException
Executes this TestSequence and returns the result. Executing the first TestCase initialises the target object. Executing all TestCases (re-)sets the result object. Any exceptional behaviour terminates the execution of the sequence immediately. The result may be an object, a wrapped value, null, an exception, or void.

Parameters:
generator - the ObjectGenerator used to synthesise the test inputs.
Returns:
the result of executing this TestSequence.
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, due to access or security restrictions, or some other unexpected failure.

getOutcome

public Outcome getOutcome()
Returns the test outcome, as judged by an Oracle. The outcome is one of the values of the enumerated type Outcome: {UNKNOWN, CONFIRMED, REJECTED, CORRECT, INCORRECT}. UNKNOWN means that this TestSequence was not judged by an Oracle. CONFIRMED or REJECTED means that the Oracle consulted the human tester, who manually confirmed or rejected the test outcome. CORRECT or INCORRECT means that the Oracle was able to determine the test outcome automatically.

Returns:
the judgement of the Oracle.

setOutcome

public void setOutcome(Outcome outcome)
Sets the test outcome, as judged by an Oracle. The outcome is one of the values of the enumerated type Outcome: {UNKNOWN, CONFIRMED, REJECTED, CORRECT, INCORRECT}. UNKNOWN means that this TestSequence was not judged by an Oracle. CONFIRMED or REJECTED means that the Oracle consulted the human tester, who manually confirmed or rejected the test outcome. CORRECT or INCORRECT means that the Oracle was able to determine the test outcome automatically.

Parameters:
outcome - the judgement of the Oracle.

hasExecuted

public boolean hasExecuted()
Reports whether this TestSequence has been executed. Used to determine whether the tester aborted a test cycle.


hasSucceeded

public boolean hasSucceeded()
Reports whether this TestSequence executed normally. This can be asked whether or not the TestSequence was judged by an Oracle. Only valid after this TestSequence has been executed.

Returns:
true if the last TestCase executed normally.

hasTerminated

public boolean hasTerminated()
Reports whether this TestSequence terminated with an exception. This can be asked whether or not the TestSequence was judged by an Oracle. Only valid after this TestSequence has been executed.

Returns:
true if the last TestCase raised an exception.

isUnchanged

public boolean isUnchanged()
Reports whether this TestSequence ended with no state change. True, if the last TestCase ended in the same state as the immediately preceding TestCase. False, if the two states are different, or there are fewer than two TestCases in the TestSequence. Only valid after this TestSequence has been executed.

Returns:
true if the last TestCase failed to modify state.

isReentrant

public boolean isReentrant()
Reports whether this TestSequence re-entered a visited state. True, if the last TestCase ended in the same state as some earlier TestCase in the TestSequence. False, if there are no matching earlier states, or there are fewer than two TestCases in this TestSequence. Note that if isUnchanged() returns true, isReentrant() will also return true. Only valid after this TestSequence has been executed.

Returns:
true if the last TestCase revisited an old state.

hasPassed

public boolean hasPassed()
Reports whether this TestSequence has been passed. Only valid after this TestSequence has been executed and judged by an Oracle.

Returns:
true if the test outcome is CORRECT or CONFIRMED.

hasFailed

public boolean hasFailed()
Reports whether this TestSequence has been failed. Only valid after this TestSequence has been executed and judged by an Oracle.

Returns:
true if the test outcome is INCORRECT or REJECTED.

isConfirmed

public boolean isConfirmed()
Reports whether this TestSequence has been manually confirmed. Only valid after this TestSequence has been executed and judged by an Oracle.

Returns:
true if the test outcome is CONFIRMED.

isRejected

public boolean isRejected()
Reports whether this TestSequence has been manually rejected. Only valid after this TestSequence has been executed and judged by an Oracle.

Returns:
true if the test outcome is REJECTED.

isCorrect

public boolean isCorrect()
Reports whether this TestSequence is automatically correct. Only valid after this TestSequence has been executed and judged by an Oracle.

Returns:
true if the test outcome is CORRECT.

isIncorrect

public boolean isIncorrect()
Reports whether this TestSequence is automatically incorrect. Only valid after this TestSequence has been executed and judged by an Oracle.

Returns:
true if the test outcome is INCORRECT.

isValidated

public boolean isValidated()
Reports whether this TestSequence has been passed or failed. May be invoked to determine whether the result of this TestSequence has been judged by an Oracle. Only valid after this TestSequence has been executed.

Returns:
true if the test outcome is not UNKNOWN.

getLongKey

public java.lang.String getLongKey()
Returns a unique long indexing key for this TestSequence. The long key is used to index the result of this TestSequence in an Oracle. The long key is based on the complete sequence of method invocations and input argument values. Only valid after this TestSequence has been executed.


getShortKey

public java.lang.String getShortKey()
Returns a short indexing key for this TestSequence. The short key is used to predict the outcome of this TestSequence in an Oracle. The short key eliminates observer-methods from the prefix, then prunes back to the shortest prefix sequence reaching the same final state. This short prefix, extended with the last method, should have the same effect as the full sequence (if supplied with the same arguments). Only valid after this TestSequence has been executed.


toString

public java.lang.String toString()
Returns a formatted representation of this TestSequence. This is used when displaying this TestSequence in a CycleReport. The displayed format is similar to the programming language instructions making up the TestSequence, with one instruction per line of output. The final line displays the result of the sequence after an arrow. Note that there is no final newline. Only valid after this TestSequence has been executed.

Overrides:
toString in class java.lang.Object
Returns:
a formatted representation of this TestSequence.