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

Class ReproGuidance

java.lang.Object
edu.berkeley.cs.jqf.fuzz.repro.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 Details

    • 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 Details

    • 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

    • observeGuidance

      public String observeGuidance()
      Description copied from interface: Guidance

      This method is only invoked during optional observability logging to provide the type of guidance used for input generation.

      Specified by:
      observeGuidance in interface Guidance

    • 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)