Component bsls_preconditions [Package bsls]

Provide macros for use in fuzz testing narrow contract functions. More...

Namespaces
namespace	bsls

---

Detailed Description

Outline

• Purpose
• Classes
• Macros
• Description
  • Usage

Purpose:

Provide macros for use in fuzz testing narrow contract functions.

Classes:

bsls::PreconditionsHandler

for begin/end callback management functions

Macros:

BSLS_PRECONDITIONS_BEGIN	mark the start of function preconditions
BSLS_PRECONDITIONS_END	mark the end of function preconditions

See also:

Component bsls_fuzztest

Description:

This component provides macros, BSLS_PRECONDITIONS_BEGIN and BSLS_PRECONDITIONS_END, to facilitate fuzz testing narrow contract functions. When fuzz testing is not enabled, the macros expand to nothing. When fuzz testing is enabled, the macros invoke a dynamic handler function via bsls::PreconditionsHandler.

BSLS_PRECONDITIONS_BEGIN is used as a marker to identify where precondition checks are begun, while BSLS_PRECONDITIONS_END is used as a marker to identify where precondition checks are complete. These macros should always be used as a pair, and always at the very beginning of a function, surrounding the function preconditions.

Usage:

Since the macros contained in this component are intended to be used in conjunction with the macros defined in bsls_fuzztest, this test driver contains only the simplest USAGE EXAMPLE. See the USAGE EXAMPLE in bsls_fuzztest for a fuller treatment.

The following example shows the use of BSLS_PRECONDITIONS_BEGIN and BSLS_PRECONDITIONS_END in the definition of a narrow contract function. These macros are to be placed around the function precondition checks, immediately before and after.

  double mySqrt(double x)
      // Return the square root of the specified 'x'.  The behavior is
      // undefined unless 'x >= 0'.
  {
      BSLS_PRECONDITIONS_BEGIN();
      BSLS_ASSERT(0 <= x);
      BSLS_PRECONDITIONS_END();
      return sqrt(x);
  }

In a fuzz-enabled build, we would invoke this function inside the fuzz loop with BSLS_FUZZTEST_EVALUATE.