Fuzz Testing

Instructions for AI coding agents on automating fuzz test creation using consistent software testing patterns in this Go project.

• 1. Benefits
• 2. Principles
• 2.1. FIRST
• 3. Patterns
• 3.1. Coverage-Guided Fuzzing
• 3.2. Corpus-Driven Fuzzing
• 3.3. Property-Based Testing
• 3.4. Boundary Value Fuzzing
• 3.5. Crash Detection
• 4. Workflow
• 5. Commands
• 6. Style Guide
• 7. Template
• 7.1. Multi-Parameter Functions
• 7.2. Single-Parameter Functions
• 8. References

1. Benefits

• Coverage-Guided Exploration

> Go's native fuzzing engine uses code coverage instrumentation to automatically guide input generation toward unexplored code paths, maximizing bug discovery without manual intervention.

• Automated Input Generation

> Fuzz testing automatically generates random inputs to discover edge cases and unexpected behaviors that manual testing might miss.

• Security Vulnerability Discovery

> Helps identify security vulnerabilities, crashes, and undefined behaviors by testing with malformed, unexpected, or extreme inputs.

• Continuous Testing

> Fuzz tests can run continuously to explore the input space over time, discovering new edge cases as the corpus grows.

• Regression Prevention

> Once a crash or bug is found, the input is saved in the corpus to prevent regression in future test runs.

2. Principles

2.1. FIRST

The FIRST principles for fuzz testing focus on creating effective and discoverable tests.

• Fast

> Fuzz tests should use efficient seed corpus and focused fuzz targets to maximize coverage discovery within practical time constraints during CI.

• Independent

> Each fuzz test should be self-contained and test a single function or behavior independently from other fuzz tests.

• Repeatable

> Fuzz tests with a fixed corpus should produce deterministic results, ensuring that discovered crashes are reproducible and regression corpus inputs are stable.

• Self-Validating

> Fuzz tests should clearly detect and report panics, invariant violations, and unexpected behaviors without requiring manual inspection.

• Timely

> Fuzz tests should be introduced alongside unit tests for functions that accept external inputs or perform calculations with boundary conditions.

3. Patterns

3.1. Coverage-Guided Fuzzing

Coverage-Guided Fuzzing is the primary fuzzing technique used by Go's native fuzzing engine. It automatically instruments code to track coverage and guides input generation toward unexplored code paths, maximizing code exploration and bug discovery.

3.2. Corpus-Driven Fuzzing

Corpus-Driven Fuzzing is a software testing technique that uses a collection of seed inputs (corpus) as the starting point for generating new test inputs through mutation.

3.3. Property-Based Testing

Property-Based Testing is a testing approach that verifies invariants and properties that should hold true for all inputs, rather than testing specific input-output pairs.

3.4. Boundary Value Fuzzing

Boundary Value Fuzzing focuses on testing edge cases and boundary conditions with randomly generated inputs around critical thresholds.

3.5. Crash Detection

Crash Detection is the process of identifying inputs that cause panics, runtime errors, or undefined behavior in the code under test.

4. Workflow

1. Identify

Identify functions in pkg/ or internal/ that accept external inputs, perform calculations, or have edge cases worth fuzzing (e.g., pkg/<package>/<file>.go).

1. Add/Create

Create fuzz tests in the same package (e.g., pkg/<package>/<file>_test.go).

1. Fuzz Test Coverage Requirements

Focus on functions that:

• Accept numeric inputs (integers, floats)
• Perform mathematical operations (division, multiplication)
• Have boundary conditions (min/max values, zero checks)
• Return errors for invalid inputs
• Use generics or type constraints

1. Apply Templates

Structure all fuzz tests using the template pattern.

1. Seed Corpus

Optionally provide seed inputs in testdata/fuzz/<FuzzTestName>/ directory to guide fuzzing toward interesting inputs.

5. Commands

| Command | Description | | -------------------------------------- | -------------------------------------------- | | make go-test-fuzz | Execute fuzz tests for a specified duration | | ls -la testdata/fuzz/<FuzzTestName>/ | Inspect the seed corpus and generated inputs |

6. Style Guide

• Test Framework

> Use the standard Go testing package with testing.F for fuzz tests. Go's fuzzing engine automatically uses coverage-guided fuzzing to explore code paths.

• Coverage-Guided Behavior

> The fuzzing engine tracks code coverage during execution and prioritizes inputs that explore new code paths. No manual configuration is required - coverage guidance is automatic.

• Include Imports

> Include testing and any packages needed for the function under test.

• Fuzz Function Naming

> Name fuzz functions with the Fuzz prefix followed by the function name (e.g., FuzzPercent for testing Percent()).

• Seed Corpus

> Use f.Add() to provide seed inputs that cover important edge cases and known valid/invalid inputs. The fuzzer will mutate these seeds while maximizing coverage.

• Fuzz Target

> The fuzz target function receives *testing.T and randomly generated inputs. It should: > - Validate inputs before calling the function under test (skip invalid inputs with t.Skip() if necessary) > - Call the function with fuzzed inputs > - Assert invariants and properties that must always hold true > - Not crash or panic for any input

• Error Handling

> Fuzz tests should verify that functions handle errors gracefully without panicking.

• Assertions

> Use explicit checks with t.Errorf() or t.Fatalf() to report violations of expected properties.

7. Template

Use this template for new fuzz test functions. Replace placeholders with actual values and adjust as needed for the use case.

7.1. Multi-Parameter Functions

For functions with multiple parameters, use a struct array to define test cases.

go
func Fuzz<FunctionName>(f *testing.F) {
	// Seed corpus with edge cases using testcases array
	testcases := []struct {
		param1 <type>
		param2 <type>
		// Add more parameters as needed
	}{
		{<value1>, <value2>}, // description of test case
		{<value1>, <value2>}, // description of test case
		// Add more test cases
	}
	for _, tc := range testcases {
		f.Add(tc.param1, tc.param2) // Use f.Add to provide a seed corpus
	}

	f.Fuzz(func(t *testing.T, param1 <type>, param2 <type>) {
		// Arrange
		// Optional: skip invalid inputs or prepare test conditions
		// Example: if input < 0 { t.Skip("negative inputs not interesting") }

		// Act
		got, err := <Function>(param1, param2)

		// Assert
		// Verify properties that should always hold true
		// Example 1: Function should never panic
		// Example 2: If no error, result should meet certain properties
		// Example 3: If error, result should be in expected error state

		if err != nil {
			// Verify error cases
			// Example: if got != 0 { t.Errorf("expected zero result on error, got %v", got) }
		} else {
			// Verify success cases and invariants
			// Example: if got < 0 { t.Errorf("result should be non-negative, got %v", got) }
		}
	})
}

7.2. Single-Parameter Functions

For functions with a single parameter, use a slice array to define test cases.

go
func Fuzz<FunctionName>(f *testing.F) {
	// Seed corpus with edge cases using testcases array
	testcases := []<type>{
		<value1>, // description
		<value2>, // description
		// Add more test cases
	}
	for _, tc := range testcases {
		f.Add(tc) // Use f.Add to provide a seed corpus
	}

	f.Fuzz(func(t *testing.T, param <type>) {
		// Arrange
		// Optional: skip invalid inputs or prepare test conditions

		// Act
		got, err := <Function>(param)

		// Assert
		// Verify properties and invariants
		if err != nil {
			// Verify error cases
		} else {
			// Verify success cases
		}
	})
}

8. References

• Go Fuzzing documentation.
• Go testing.F package documentation.