Package edu.berkeley.cs.jqf.junit5

Annotation Type FuzzTest

@Target(METHOD) @Retention(RUNTIME) @TestTemplate @ExtendWith(JQFTestExtension.class) public @interface FuzzTest
Marks a method as a JQF/Zest fuzz-test entry point for JUnit 5 (Jupiter).

A @FuzzTest method is a TestTemplate run by the standard junit-jupiter-engine through JQFTestExtension. It has two modes, selected at run time:

  • Regression (the default for a plain mvn test): the method is replayed, once per saved input, against the corpus from a previous fuzzing run plus any seed files plus one empty input. This is bounded and fast, and runs under the normal Jupiter lifecycle.
  • Fuzzing (when -Djqf.fuzz=true or the JQF_FUZZ environment variable is set, or a repro() input is given): a full coverage-guided Zest campaign drives the method, and the first failing input fails the test.

The argument generator is not fixed: it is discovered through ServiceLoader from the ArgumentsGeneratorFactory providers on the test classpath (for example jqf-generator-quickcheck), or chosen per test with arguments(). If no provider is found, the test fails fast with a message naming a provider to add.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    Class<? extends ArgumentsGeneratorFactory>
    arguments
    The argument-generator provider for this test.
    String
    maxDuration
    The maximum wall-clock duration of a fuzzing campaign, for example "30s", "10m", "2h" or "1d"; a bare number is read as seconds.
    long
    maxTrials
    The maximum number of trials in a fuzzing campaign.
    String
    repro
    A path to an input file or directory to replay instead of fuzzing, mirroring @Fuzz(repro = ...).
    String
    seeds
    A path to a file or directory of seed inputs used by the regression run, in addition to the saved corpus and the empty input.

  • Element Details

    • maxDuration

      String maxDuration
      The maximum wall-clock duration of a fuzzing campaign, for example "30s", "10m", "2h" or "1d"; a bare number is read as seconds. Empty means no time limit from the annotation. Overridden by the jqf.fuzz.duration system property.
      Returns:
      the campaign duration specification, or an empty string
      Default:
      ""

    • maxTrials

      long maxTrials
      The maximum number of trials in a fuzzing campaign. 0 means no trial limit from the annotation (the campaign is then bounded by duration). Overridden by the jqf.fuzz.trials system property.
      Returns:
      the trial limit, or 0 for the default
      Default:
      0L

    • repro

      String repro
      A path to an input file or directory to replay instead of fuzzing, mirroring @Fuzz(repro = ...). When set, the test runs in fuzzing mode against exactly these inputs. Overridden by the jqf.repro system property.
      Returns:
      the replay path, or an empty string
      Default:
      ""

    • seeds

      String seeds
      A path to a file or directory of seed inputs used by the regression run, in addition to the saved corpus and the empty input.
      Returns:
      the seed path, or an empty string
      Default:
      ""

    • arguments

      Class<? extends ArgumentsGeneratorFactory> arguments
      The argument-generator provider for this test. The default, ArgumentsGeneratorFactory itself, is a marker meaning "discover the provider through ServiceLoader". Set it to a concrete factory (with a public no-argument constructor) to choose one explicitly.
      Returns:
      the generator factory class, or the marker default
      Default:
      edu.berkeley.cs.jqf.fuzz.spi.ArgumentsGeneratorFactory.class