Package edu.berkeley.cs.jqf.fuzz.repro

Class ReproGuidance

  • All Implemented Interfaces:
    Guidance
    Direct Known Subclasses:
    DiffFuzzReproGuidance
    public class ReproGuidance
extends Object
implements Guidance
    A front-end that provides a specified set of inputs for test case reproduction, This class enables reproduction of a test case with an input file generated by a guided fuzzing front-end such as AFL.
    Author:
    Rohan Padhye

    • Constructor Detail

      • ReproGuidance

        public ReproGuidance​(File[] inputFiles,
                     File traceDir)
              throws IOException
        Constructs an instance of ReproGuidance with a list of input files to replay and a directory where the trace events may be logged.
        Parameters:
        inputFiles - a list of input files
        traceDir - an optional directory, which if non-null will be the destination for log files containing event traces
        Throws:
        IOException

      • ReproGuidance

        public ReproGuidance​(File inputFile,
                     File traceDir)
              throws IOException
        Constructs an instance of ReproGuidance with a single input file or with a directory of input files to replay, and a directory where the trace events may be logged.
        Parameters:
        inputFile - an input file or directory of input files
        traceDir - an optional directory, which if non-null will be the destination for log files containing event traces
        Throws:
        FileNotFoundException - if `inputFile` is not a valid file or directory
        IOException

    • Method Detail

      • setStopOnFailure

        public void setStopOnFailure​(boolean value)
        Configure whether the repro execution should stop as soon as the first failure is encountered.
        Parameters:
        value - whether to stop the repro on failure

      • getInput

        public InputStream getInput()
        Returns an input stream corresponding to the next input file.
        Specified by:
        getInput in interface Guidance
        Returns:
        an input stream corresponding to the next input file

      • hasInput

        public boolean hasInput()
        Returns true if there are more input files to replay.
        Specified by:
        hasInput in interface Guidance
        Returns:
        true if there are more input files to replay

      • observeGeneratedArgs

        public void observeGeneratedArgs​(Object[] args)
        Description copied from interface: Guidance
        Callback for observing actual arguments passed to the test method.

        This method is invoked exactly once after each call to Guidance.getInput(). The arguments to this callback are the structured inputs that are produced by junit-quickcheck generators, which in turn decode the bytes produced by Guidance.getInput().

        This method is useful for logging the generated args or for calculating the size of the generated args. The default implementation does nothing.

        Specified by:
        observeGeneratedArgs in interface Guidance
        Parameters:
        args - an array of arguments that will be passed to the test method; the size of this array is equal to the number of formal parameters to the test method

      • handleResult

        public void handleResult​(Result result,
                         Throwable error)
        Logs the end of run in the log files, if any.
        Specified by:
        handleResult in interface Guidance
        Parameters:
        result - the result of the fuzzing trial
        error - the error thrown during the trial, or null

      • generateCallBack

        public Consumer<TraceEvent> generateCallBack​(Thread thread)
        Returns a callback that can log trace events or code coverage info.

        If the system property jqf.repro.logUniqueBranches was set to true, then the callback collects coverage info into the set branchesCoveredInCurrentRun, which can be accessed using getBranchesCovered().

        Otherwise, if the traceDir was non-null during the construction of this Guidance instance, then one log file per thread of execution is created in this directory. The callbacks generated by this method write trace event descriptions in sequence to their own thread's log files.

        If neither of the above are true, the returned callback simply updates a total coverage map (see getCoverage().

        Specified by:
        generateCallBack in interface Guidance
        Parameters:
        thread - the thread whose events to handle
        Returns:
        a callback to log code coverage or execution traces

      • getCoverage

        public Coverage getCoverage()
        Returns a reference to the coverage statistics.
        Returns:
        a reference to the coverage statistics

      • getBranchesCovered

        public Set<String> getBranchesCovered()
        Retyrns the set of branches covered by this repro.

        This set will only be non-empty if the system property jqf.repro.logUniqueBranches was set to true before the guidance instance was constructed.

        The format of each element in this set is a custom format that strives to be both human and machine readable.

        A branch is only logged for inputs that execute successfully. In particular, branches are not recorded for failing runs or for runs that violate assumptions.

        Returns:
        the set of branches covered by this repro

      • jacocoCheckpoint

        public void jacocoCheckpoint​(File classFile,
                             File csvDir)