FuzzTest Documentation

FuzzTest allows you to move from specific unit tests to property-based testing. Instead of providing a single input/output pair, you define a property function that takes parameters and asserts that certain properties hold true for any valid input within specified domains.

To implement this:

1. Define a function (the property function) that accepts the parameters you want to fuzz.
2. Use the FUZZ_TEST macro to instantiate the test.
3. Use .WithDomains(...) to specify the input domains for each parameter using domain specifiers like Arbitrary<T>() or InRegexp(string).

void ParsesIntCorrectly(int number, const std::string& suffix) {
  const std::string input = absl::StrCat(number, suffix);
  const std::optional<int> output = ParseLeadingDigits(input);
  EXPECT_THAT(output, Optional(Eq(number)));
}
FUZZ_TEST(ParseLeadingDigitsTest, ParsesIntCorrectly)
  .WithDomains(/*number=*/Arbitrary<int>(), /*suffix=*/InRegexp("^\D.*"));

Because FUZZ_TEST expands into a global variable, initializing seeds with other global objects can lead to the static initialization order fiasco. To prevent this, use a seed provider instead of a raw list of values.

A seed provider is an invocable (lambda, function pointer, or member function) that returns a std::vector<std::tuple<Args...>>, where Args... matches the property function's parameters. FuzzTest calls this provider at runtime, ensuring safe initialization.

Using a Lambda as a Seed Provider

FUZZ_TEST(MyApiTestSuite, CallingMyApiNeverCrashes)
  .WithSeeds([]() -> std::vector<std::tuple<int, std::string>> {
    return {{5, "Foo"}, {10, "Bar"}};
  });

Using a Test Fixture Member Function

If using FUZZ_TEST_F, the seed provider can be a pointer to a non-const member function of your fixture class.

class MyFuzzTest {
 public:
  void CallingMyApiNeverCrashes(int x, const std::string& s);
  std::vector<std::tuple<int, std::string>> seeds() { return seeds_; }
 private:
  std::vector<std::tuple<int, std::string>> seeds_ = {{5, "Foo"}, {10, "Bar"}};
};

FUZZ_TEST_F(MyFuzzTest, CallingMyApiNeverCrashes)
  .WithSeeds(&MyFuzzTest::seeds);

In some cases, the value_type (the output) is not the most efficient way to represent or mutate the internal state. For example, when fuzzing strings generated by a regular expression, it is more efficient to mutate a DFA path (corpus_type) than to mutate the resulting std::string (value_type).

To implement a custom corpus_type, follow these steps:

1. Define using value_type = ....
2. Set static constexpr bool has_custom_corpus_type = true;.
3. Define using corpus_type = ....
4. Implement corpus_type Init(absl::BitGenRef prng).
5. Implement void Mutate(corpus_type& val, absl::BitGenRef prng, bool only_shrink).
6. Implement value_type GetValue(const corpus_type& value) const to convert the internal state back to the output type.

class RegexDomain {
 public:
  using value_type = std::string;
  static constexpr bool has_custom_corpus_type = true;
  using corpus_type = DFAPath;

  MyVectorDomain(std::string regex) : dfa_(DFA::Parse(regex)) {}

  corpus_type Init(absl::BitGenRef prng) {
    return dfa_.Generate(prng);
  }

  void Mutate(corpus_type& val, absl::BitGenRef prng, bool only_shrink) {
    dfa_.Mutate(prng, val);
  }

  value_type GetValue(const corpus_type& value) const {
    static_assert(has_custom_corpus_type);
    return dfa_.ToString(value);
  }

 private:
  DFA dfa_;
};

You can reuse existing GoogleTest fixtures (classes derived from ::testing::Test) in FuzzTest by using adapters. You must choose between two different instantiation semantics depending on whether your fixture is mutable or expensive to set up.

Semantics 1: Per-iteration instantiation

Use fuzztest::PerIterationFixtureAdapter<Fixture> when the fixture is mutable. This follows the standard GoogleTest invariant where a fresh fixture object is used for every test run (in this case, every fuzz iteration). This prevents state leakage between iterations.

Semantics 2: Per-fuzz-test instantiation

Use fuzztest::PerFuzzTestFixtureAdapter<Fixture> when the fixture is expensive to set up but immutable (or easily resettable). This instantiates the fixture once per fuzz test, reusing the same object across all iterations to maximize performance.

// Example: Per-iteration semantics for a mutable fixture
class SumVecFuzzTest : public fuzztest::PerIterationFixtureAdapter<SumVecTest> {
 public:
  void SumsLastEntry(int last_entry) {
    int previous_sum = SumVec(vec_);
    vec_.push_back(last_entry);
    EXPECT_EQ(SumVec(vec_), previous_sum + last_entry);
  }
};
FUZZ_TEST_F(SumVecFuzzTest, SumsLastEntry);

// Example: Per-fuzz-test semantics for an expensive, immutable fixture
class EchoServerFuzzTest
    : public fuzztest::PerFuzzTestFixtureAdapter<EchoServerTest> {
 public:
  void ReturnsTheSameString(const std::string& request) {
    std::string response;
    SendRequest("localhost:9999", request, &response);
    EXPECT_EQ(response, request);
  }
};
FUZZ_TEST_F(EchoServerFuzzTest, ReturnsTheSameString);

Understanding the core concepts of Centipede:

• Fuzzing engine (fuzzer): Orchestrates execution and produces an infinite stream of inputs.
• Fuzz target: A binary or library that consumes bytes and produces coverage data.
• Input: A sequence of bytes (arbitrary or structured).
• Feature: A number representing unique target behavior (e.g., a specific basic block execution).
• Feature set: The set of features observed during a specific input's execution.
• Coverage: Information about target behavior, usually represented as a feature set.
• Mutator: A function that produces small random mutations of an input.
• Executor: A function that feeds input to a target and retrieves coverage.
• Centipede runner: A library that implements the executor interface, allowing targets to be run by Centipede and collect sancov coverage.
• Corpus: A set of inputs.
• Distillation: Selecting a subset of a corpus that maintains the same coverage features.
• Shard: A file representing a subset of the corpus and its associated feature sets.
• Job: A single fuzzer process that writes to one shard and may read multiple shards.
• Workdir (WD): The directory containing fuzzer data.