Package 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, ObserverEqValue, PrimValue, SizeToArrayLength, ToStringReturnsNormally
public abstract class ObjectContract extends 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 Details

    • ObjectContract

      public ObjectContract()

  • Method Details

    • 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(Object... objects) throws 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:
      Throwable - if an exception is thrown in evaluation

    • toCommentString

      public abstract 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 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 String get_observer_str()
      Returns a string describing the observer.
      Returns:
      a string description of the contract

    • checkContract

      public final Check checkContract(ExecutableSequence eseq, 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, 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 String toStringHandleExceptions(Object o)