Component bslim_fuzzutil [Package bslim]

Provide fuzz test utilities for basic types. More...

Namespaces
namespace	bslim

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Consuming Integers in a Range to Pass to an Interface

Purpose:

Provide fuzz test utilities for basic types.

Classes:

bslim::FuzzUtil

functions to create basic types from fuzz data

See also:

Component bslim_fuzzdataview

Description:

This component provides a namespace, bslim::FuzzUtil, containing functions that create fundamental and standard library types from fuzz data provided by a fuzz harness (e.g., libFuzzer).

See {http://bburl/BDEFuzzTesting} for details on how to build and run with fuzz testing enabled.

Usage:

This section illustrates intended use of this component.

Example 1: Consuming Integers in a Range to Pass to an Interface:

Suppose we wish to fuzz test a function with preconditions.

First, we define the TradingInterfaceUnderTest struct:

  struct TradingInterfaceUnderTest {
      // This utility class provides sample functionality to demonstrate how
      // fuzz data might be used.

      // CLASS METHODS
      static int numEarningsAnnouncements(int year, int month)
          // Return a value containing the number of earnings announcements
          // in the specified 'year' and 'month'.  The behavior is undefined
          // unless '1950 < year < 2030' and 'month' is in '[1 .. 12]'.  Note
          // that the values here are arbitrary, and in the real-world this
          // data would be obtained from a database or an API.
      {
          BSLS_ASSERT(1950 <  year  && year  < 2030);
          BSLS_ASSERT(   1 <= month && month <=  12);

          if (2020 < year && 6 < month) {
              return 11;                                            // RETURN
          }
          return 6;
      }
  };

Then, we need a block of raw bytes. This would normally come from a fuzz harness (e.g., the LLVMFuzzerTestOneInput entry point function from libFuzzer). Since libFuzzer is not available here, we initialize a myFuzzData array that we will use instead.

  const bsl::uint8_t  myFuzzData[] = {0x43, 0x19, 0x0D, 0x44, 0x37, 0x0D,
                                      0x38, 0x5E, 0x9B, 0xAA, 0xF3, 0xDA};

Next, we create a FuzzDataView to wrap the raw bytes.

  bslim::FuzzDataView fdv(myFuzzData, sizeof myFuzzData);

Now, we pass this FuzzDataView to FuzzUtil to generate values within the permissible range of the function under test:

  int month = bslim::FuzzUtil::consumeNumberInRange<int>(&fdv,    1,   12);
  int year  = bslim::FuzzUtil::consumeNumberInRange<int>(&fdv, 1951, 2029);
  assert(   1 <= month && month <=   12);
  assert(1951 <= year  && year  <= 2029);

Finally, we can use these int values to pass to a function that returns the number of earnings announcements scheduled in a given month.

  int numEarnings =
      TradingInterfaceUnderTest::numEarningsAnnouncements(year, month);
  (void) numEarnings;