Skip to content
Tutorials Center
My learning

Topics

Go Reference Β· Logging, Flags and Testing

Go fuzzing with testing.F

Concept guide to Go fuzz testing: FuzzXxx functions, seed corpus, f.Add and f.Fuzz, supported argument types, go test -fuzz, the testdata corpus and writing properties.

Fuzzing means testing a function with automatically generated inputs, looking for crashes and violated properties. Go has built-in, coverage-guided fuzzing since Go 1.18. You write a fuzz target, FuzzXxx(f *testing.F), that gives the engine a few seed inputs and a function that checks a property. The engine then mutates the seeds, keeps inputs that reach new code, and reports the smallest failing input it finds.

A fuzz target does not say what the answer is for one input. It states something that must be true for all inputs: "decoding what I encoded gives the original", "this parser never panics", "reversing twice gives the same string".

Go
func FuzzReverse(f *testing.F) {
	f.Add("hello")                 // seed corpus
	f.Add("")
	f.Fuzz(func(t *testing.T, s string) {
		if Reverse(Reverse(s)) != s {
			t.Errorf("round trip failed for %q", s)
		}
	})
}
// go test -fuzz=FuzzReverse -fuzztime=30s

Try it

The site runs a single main.go, so the real fuzz engine (go test -fuzz) is not available. These examples show the idea with plain code: the properties a fuzz target would check, first on seeds, then with a tiny seeded mutator.

Go The properties and the seed corpus

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go A miniature mutation fuzzer

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Go
func FuzzXxx(f *testing.F)

func (f *F) Add(args ...any)
func (f *F) Fuzz(ff any) // ff: func(*testing.T, T1, T2, ...)
Rule Description
Function Named FuzzXxx, one parameter *testing.F, in a _test.go file. At most one f.Fuzz call per target.
f.Add(...) Adds a seed. Argument types must match the parameters of the function given to f.Fuzz, in order.
Fuzz arguments After *testing.T: string, []byte, bool, byte, rune, float32, float64, int, int8..int64, uint, uint8..uint64.
Corpus Seeds from f.Add plus files in testdata/fuzz/FuzzXxx/. A plain go test runs all of them as normal tests.

A failing input is saved automatically as a file such as testdata/fuzz/FuzzReverse/3f1a..., in the format:

TEXT
go test fuzz v1
string("\x91")

Commit that file: from then on go test replays it as a regression test.

Usage notes

  • Fuzzing is opt-in. go test alone only runs the corpus. go test -fuzz=FuzzReverse fuzzes one target (the pattern must match exactly one) until you stop it, or for -fuzztime=30s or -fuzztime=1000x.
  • Good properties: round trips (encode then decode), idempotence (f(f(x)) == f(x)), comparing a fast version with a simple reference, "never panics", invariants (output sorted, valid UTF-8, length preserved).
  • Do not compare with a copy of the implementation. A check that repeats the code under test only finds crashes.
  • Keep targets fast and deterministic. No network, no clock, no global state, no randomness; the engine runs the function millions of times, possibly in parallel.
  • Minimization. On failure the engine shrinks the input. Disable with -fuzzminimizetime=0 if shrinking is slow.
  • Fuzz cache. Interesting inputs found during a run live in the build cache directory (go env GOCACHE), not in your repository. Only failures are written to testdata.
  • Where it shines: parsers, decoders, formatters, anything that handles untrusted bytes.
  • Not supported everywhere. Coverage instrumentation works on a limited set of platforms (amd64, arm64 and a few more).