Package randoop.sequence

Class ExecutableSequence

  • public class ExecutableSequence
extends Object
    An ExecutableSequence wraps a Sequence with functionality for executing the sequence, via methods execute(ExecutionVisitor, TestCheckGenerator) and execute(ExecutionVisitor, TestCheckGenerator, boolean). It also lets the client add Checks that check expected behaviors of the execution.

    An ExecutableSequence augments a sequence with three additional pieces of data:

    • Execution results. An ExecutableSequence can be executed, and the results of the execution (meaning the objects created during execution, and any exceptions thrown) are made available to clients or execution visitors to inspect.
    • Checks. A check is an object representing an expected runtime behavior of the sequence. Clients can add checks to specific indices of the sequence. For example, a client might add a NotNull check to the ith index of a sequence to signify that the value returned by the statement at index i should not be null.
    • Check evaluation results. Corresponding to every check is a boolean value that represents whether the check passed or failed during the last execution of the sequence.

    An ExecutableSequence only directly manages the execution results. Other data, including checks and check evaluation results, are added or removed by the client of the ExecutableSequence. One way of doing this is by implementing an ExecutionVisitor and passing it as an argument to the execute method.

    • Field Detail

      • sequence

        public Sequence sequence
        The underlying sequence.

      • checks

        private TestChecks<?> checks
        The checks for the last statement in this sequence.

      • executionResults

        private transient Execution executionResults
        Contains the runtime objects created and exceptions thrown (if any) during execution of this sequence. Invariant: sequence.size() == executionResults.size(). Transient because it can contain arbitrary objects that may not be serializable.

      • gentimeNanos

        public long gentimeNanos
        How long it took to generate this sequence in nanoseconds, excluding execution time. Must be directly set by the generator that creates this object. No code in this class sets its value.

      • exectime

        public long exectime
        How long it took to execute this sequence in nanoseconds. Is -1 until the sequence completes execution.

      • hasNullInput

        private boolean hasNullInput
        Flag to record whether execution of sequence has a null input.

        TODO: This is wonky, it really belongs to execution.

      • output_buffer

        private static ByteArrayOutputStream output_buffer
        Captures output from the executed sequence.

      • componentSequences

        public List<Sequence> componentSequences
        The subsequences that were concatenated to create this sequence.

    • Constructor Detail

      • ExecutableSequence

        public ExecutableSequence​(Sequence sequence)
        Create an executable sequence that executes the given sequence.
        Parameters:
        sequence - the underlying sequence for this executable sequence

    • Method Detail

      • reset

        private void reset()
        Reset this object to its initial state.

      • toCodeLines

        private List<String> toCodeLines()
        Return this sequence as code. Similar to Sequence.toCodeString() except includes the checks.

        If for a given statement there is a check of type ExceptionCheck, that check's pre-statement code is printed immediately before the statement, and its post-statement code is printed immediately after the statement.

        Returns:
        the sequence as a string

      • toCodeString

        public String toCodeString()
        Return this sequence as code. Similar to Sequence.toCodeString() except includes the checks.

        If for a given statement there is a check of type ExceptionCheck, that check's pre-statement code is printed immediately before the statement, and its post-statement code is printed immediately after the statement.

        Returns:
        the sequence as a string

      • statementToCodeString

        public String statementToCodeString​(int i)
        Return the code representation of the i'th statement.
        Parameters:
        i - the statement index
        Returns:
        the string representation of the statement

      • execute

        private void execute​(ExecutionVisitor visitor,
                     TestCheckGenerator gen,
                     boolean ignoreException)
        Execute this sequence, invoking the given visitor as the execution unfolds. For example, the visitor may decorate the sequence with Checks about the execution.

        This method operates as follows:

        • Clear execution results and call visitor.initialize(this).
        • For each statement in the sequence:
          • call visitor.visitBefore(this, i)
          • execute the i-th statement, using reflection
          • call visitor.visitAfter(this, i)
        • For the last statement, check its specifications (pre-, post-, and throws-conditions).
        Execution stops if one of the following conditions holds:
        • All statements in the sequences have been executed.
        • A pre-condition for the final statement fails
        • A statement's execution results in an exception and ignoreException==false.
        • A null input value is implicitly passed to the statement (i.e., not via explicit declaration like x = null)
        • After executing the i-th statement and calling the visitor's visitAfter method, a ContractViolation check is present at index i.

        After invoking this method, the client can query the outcome of executing each statement via the method getResult(int).

        Parameters:
        visitor - the ExecutionVisitor
        gen - the initial check generator, which this augments then uses
        ignoreException - if true, ignore exceptions thrown before the last statement
        Throws:
        Error - if execution of the sequence throws an exception and ignoreException==false

      • getRuntimeValuesForVars

        public static Object[] getRuntimeValuesForVars​(List<Variable> vars,
                                               Execution execution)
        Returns the values for the given variables in the Execution object. The variables are Variable objects in the Sequence of this ExecutableSequence object.
        Parameters:
        vars - a list of Variable objects
        execution - the object representing outcome of executing this sequence
        Returns:
        array of values corresponding to variables

      • getResult

        public ExecutionOutcome getResult​(int index)
        This method is typically used by ExecutionVisitors.

        The result of executing the index-th element of the sequence.

        Parameters:
        index - the statement index
        Returns:
        the outcome of the statement at index

      • getChecks

        public TestChecks<?> getChecks()
        Return the set of test checks for the most recent execution.
        Returns:
        the TestChecks generated from the most recent execution

      • getValue

        private Object getValue​(int index)
        The result of executing the index-th element of the sequence.
        Parameters:
        index - which element to obtain
        Returns:
        the result of executing the index-th element of the sequence, if that element's execution completed normally

      • getLastStatementValues

        public List<ReferenceValue> getLastStatementValues()
        Returns the list of (reference type) values created and used by the last statement of this sequence. Null output values are not included.
        Returns:
        the list of values created and used by the last statement of this sequence

      • addReferenceValue

        private void addReferenceValue​(Variable variable,
                               Object value,
                               Set<ReferenceValue> refValues)
        If the variable has a non-String reference type, add its value to the set and also add a mapping to variableMap.
        Parameters:
        variable - the variable to use as a value in variableMap
        value - the Java value to use as a key in variableMap
        refValues - the set of all reference values; is side-effected by this method

      • getAllValues

        public List<ReferenceValue> getAllValues()
        Returns all values computed in the sequence.
        Returns:
        the list of values computed in the sequence

      • getVariables

        public List<Variable> getVariables​(Object value)
        Returns the set of variables that have the given value in the outcome of executing this sequence.
        Parameters:
        value - the value
        Returns:
        the set of variables that have the given value, or null if none

      • getVariable

        public Variable getVariable​(Object value)
        Returns some variable that has the given value in the outcome of executing this sequence.
        Parameters:
        value - the value
        Returns:
        a variable that has the given value

      • isNormalExecution

        private boolean isNormalExecution​(int i)
        This method is typically used by ExecutionVisitors.
        Parameters:
        i - the statement index to test for normal execution
        Returns:
        true if execution of the i-th statement terminated normally

      • getNonNormalExecutionIndex

        public int getNonNormalExecutionIndex()

      • isNormalExecution

        public boolean isNormalExecution()

      • getExceptionIndex

        private int getExceptionIndex​(Class<?> exceptionClass)
        Returns the index in the sequence at which an exception of the given class (or a class compatible with it) was thrown. If no such exception, returns -1.
        Parameters:
        exceptionClass - the exception thrown
        Returns:
        the index in the sequence at which an exception of the given class (or a class compatible with it) was thrown. If no such exception, returns -1

      • throwsException

        public boolean throwsException​(Class<?> exceptionClass)
        Return true if an exception of the given class (or a class compatible with it) was thrown during this sequence's execution.
        Parameters:
        exceptionClass - the exception class
        Returns:
        true if an exception compatible with the given class was thrown during this sequence's execution

      • hasNonExecutedStatements

        public boolean hasNonExecutedStatements()
        Returns whether the sequence contains a non-executed statement. That happens if some statement before the last one throws an exception.
        Returns:
        true if this sequence has non-executed statements, false otherwise

      • getNonExecutedIndex

        public int getNonExecutedIndex()
        Returns the index i for a non-executed statement, or -1 if there is no such index. Note that a statement is considered executed even if it throws an exception.
        Returns:
        the index of a non-executed statement in this sequence

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object

      • hasNullInput

        public boolean hasNullInput()
        Indicates whether the executed sequence has any null input values.
        Returns:
        true if there is a null input value in this sequence, false otherwise

      • hasFailure

        public boolean hasFailure()
        Indicate whether checks are failing or passing.
        Returns:
        true if checks are all failing, or false if all passing

      • hasInvalidBehavior

        public boolean hasInvalidBehavior()
        Indicate whether there are any invalid checks.
        Returns:
        true if the test checks have been set and are for invalid behavior, false otherwise

      • addCoveredClass

        public void addCoveredClass​(Class<?> c)
        Adds a covered class to the most recent execution results of this sequence.
        Parameters:
        c - the class covered by the execution of this sequence

      • coversClass

        public boolean coversClass​(Class<?> c)
        Indicates whether the given class is covered by the most recent execution of this sequence.
        Parameters:
        c - the class to be covered
        Returns:
        true if the class is covered by the sequence, false otherwise

      • getOperation

        public TypedOperation getOperation()
        Return the operation from which this sequence was generated -- the operation of the last statement of this sequence.
        Returns:
        the operation of the last statement of this sequence

      • size

        public int size()
        Return the number of statements in this sequence.
        Returns:
        the number of statements in this sequence