randoop.contract

Class ObjectContract

java.lang.Object

randoop.contract.ObjectContract

Direct Known Subclasses:

CheckRepContract, CompareToAntiSymmetric, CompareToEquals, CompareToReflexive, CompareToReturnsNormally, CompareToSubs, CompareToTransitive, EnumValue, EqualsHashcode, EqualsReflexive, EqualsReturnsNormally, EqualsSymmetric, EqualsToNullRetFalse, EqualsTransitive, HashCodeReturnsNormally, IsNotNull, IsNull, ObserverEqArray, ObserverEqValue, PrimValue, SizeToArrayLength, ToStringReturnsNormally

public abstract class ObjectContract
extends java.lang.Object

An object contract represents a property that must hold of any object of a given class. It is used as part of the oracle (assertion) for a unit test: the oracle expects that every object contract holds. Any sequence of method calls that leads to a failing contract is outputted by Randoop as an error-revealing test case.

Implementing classes provide two key pieces functionality:

• A method evaluate(java.lang.Object...)(Object... objects) that determines if the given object(s) satisfy the property.
• A method toCodeString()() that emits Java code that can be inserted into a unit test to check for the given property.

See the various implementing classes for examples (for an example, see EqualsReflexive).

Constructor Summary

Constructors

Constructor and Description
ObjectContract()

Method Summary

Modifier and Type	Method and Description
Check	checkContract(ExecutableSequence eseq, java.lang.Object[] values) Checks a contract on a particular array of values.
abstract boolean	evaluate(java.lang.Object... objects) Evaluates the contract on the given values.
(package private) ObjectCheck	failedContract(ExecutableSequence eseq, java.lang.Object[] values) Return an ObjectCheck indicating that a contract failed.
abstract java.lang.String	get_observer_str() Returns a string describing the observer.
abstract int	getArity() The number of values that this contract is over.
abstract TypeTuple	getInputTypes() Returns the input types for this contract.
abstract java.lang.String	toCodeString() A string that can be used as Java source code and will result in the expression being evaluated.
abstract java.lang.String	toCommentString() A string that will be inserted as a comment in the test before the code corresponding to this contract.
(package private) static java.lang.String	toStringHandleExceptions(java.lang.Object o)

Methods inherited from class java.lang.Object

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

Constructor Detail

ObjectContract

public ObjectContract()

Method Detail

getArity

public abstract int getArity()

The number of values that this contract is over.

Returns:

the number of arguments to the contract

getInputTypes

public abstract TypeTuple getInputTypes()

Returns the input types for this contract.

Returns:

the input types for this contract

evaluate

public abstract boolean evaluate(java.lang.Object... objects)
                          throws java.lang.Throwable

Evaluates the contract on the given values. Returns false if the contract was violated. Returns true if the contract was satisfied or was not applicable.

When calling this method during execution of a test, Randoop guarantees that objects does not contain any null objects, and that objects.length == getArity().

Parameters:

objects - the actual parameters to this contract

Returns:

false if the contract is violated, true otherwise

Throws:

java.lang.Throwable - if an exception is thrown in evaluation

toCommentString

public abstract java.lang.String toCommentString()

A string that will be inserted as a comment in the test before the code corresponding to this contract. Occurrences of variables x0, x1, x2, etc. in the string will be replaced by actual values.

Returns:

the comment string representation of this contract

toCodeString

public abstract java.lang.String toCodeString()

A string that can be used as Java source code and will result in the expression being evaluated.

The N-th object that participates in the contract check should be referred to as "xN" (for N one of 0, ... , 9). For example, if the expression of arity 2 represents a call of the equals method between two objects, the code should be something like assert x0.equals(x1);".

The string does not contain a trailing newline. When there is a leading comment, it should start with a newline.

Returns:

the code string representation of this contract; must be non-null

get_observer_str

public abstract java.lang.String get_observer_str()

Returns a string describing the observer.

Returns:

a string description of the contract

checkContract

public final Check checkContract(ExecutableSequence eseq,
                                 java.lang.Object[] values)

Checks a contract on a particular array of values.

Parameters:

eseq - the executable sequence that is the source of values for checking contracts

values - the input values

Returns:

a ObjectCheck if the contract fails, an InvalidExceptionCheck if the contract throws an exception indicating that the sequence is invalid, null otherwise

failedContract

ObjectCheck failedContract(ExecutableSequence eseq,
                           java.lang.Object[] values)

Return an ObjectCheck indicating that a contract failed.

Parameters:

eseq - the sequence for which a contract failed

values - the input values

Returns:

an ObjectCheck indicating that a contract failed

toStringHandleExceptions

static java.lang.String toStringHandleExceptions(java.lang.Object o)