org.jwalk.core
Class TestSequence
java.lang.Object
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
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 |
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.
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.