Native fuzzing
A fuzz test is a test function with a seed corpus and an invariant: the runner calls it with its seeds, then with generated inputs, and reports the first input that breaks the invariant. Go has the fuzzer in the toolchain, so a package needs no dependency to use it. The table test lesson chose the inputs by hand; a fuzzer chooses them for you.
A Fuzz function
func FuzzXxx(f *testing.F) is the required signature. f.Add registers seed values, and f.Fuzz takes a function whose arguments are the types of the seeds; the runner generates values of exactly those types. The body asserts an invariant that must hold for every input, not a list of expected outputs, because the fuzzer will produce inputs nobody wrote down.
package text
import (
"testing"
"unicode/utf8"
)
func Reverse(s string) string {
b := []byte(s)
for i, j := 0, len(b)-1; i < j; i, j = i+1, j-1 {
b[i], b[j] = b[j], b[i]
}
return string(b)
}
func FuzzReverse(f *testing.F) {
f.Add("hello")
f.Add("world")
f.Fuzz(func(t *testing.T, s string) {
rev := Reverse(s)
if !utf8.ValidString(rev) {
t.Fatalf("Reverse(%q) = %q is not valid UTF-8", s, rev)
}
})
}
go test -v -run FuzzReverse .
=== RUN FuzzReverse
=== RUN FuzzReverse/seed#0
=== RUN FuzzReverse/seed#1
--- PASS: FuzzReverse (0.00s)
--- PASS: FuzzReverse/seed#0 (0.00s)
--- PASS: FuzzReverse/seed#1 (0.00s)
PASS
ok example.com/text 0.006s
With -run the runner executes the seeds only, which is what a normal go test does to every fuzz function, and both passed. A plain run is therefore cheap and reproducible; the generation starts only when -fuzz names the target, so a suite does not become slow because it contains a fuzzer.
A saved input that fails
When the fuzzer finds an input that breaks the invariant, it writes it under testdata/fuzz/FuzzXxx/ and the next plain run replays it. The file is part of the repository: it turns a random discovery into a deterministic test case that a reviewer can read. Here the corpus holds a non-ASCII string, and the byte-wise reverse splits its encoding:
package text
import (
"testing"
"unicode/utf8"
)
func Reverse(s string) string {
b := []byte(s)
for i, j := 0, len(b)-1; i < j; i, j = i+1, j-1 {
b[i], b[j] = b[j], b[i]
}
return string(b)
}
func FuzzReverse(f *testing.F) {
f.Add("hello")
f.Add("world")
f.Fuzz(func(t *testing.T, s string) {
rev := Reverse(s)
if !utf8.ValidString(rev) {
t.Fatalf("Reverse(%q) = %q is not valid UTF-8", s, rev)
}
})
}
go test -v -run FuzzReverse .
=== RUN FuzzReverse
=== RUN FuzzReverse/seed#0
=== RUN FuzzReverse/seed#1
=== RUN FuzzReverse/utf8
reverse_test.go:22: Reverse("héllo") = "oll\xa9\xc3h" is not valid UTF-8
--- FAIL: FuzzReverse (0.00s)
--- PASS: FuzzReverse/seed#0 (0.00s)
--- PASS: FuzzReverse/seed#1 (0.00s)
--- FAIL: FuzzReverse/utf8 (0.00s)
FAIL
FAIL example.com/text 0.005s
FAIL
The failing case is reported with the exact input and the two strings, and the seed still passed, so the report points at the corpus entry and not at the seeds. The file itself is plain text:
cat testdata/fuzz/FuzzReverse/utf8
go test fuzz v1
string("héllo")
The first line is the format version and the second is the value in Go syntax. The repair is to reverse runes instead of bytes, and the corpus entry then passes without being deleted: it becomes the regression test for the bug the fuzzer found.
Running the fuzzer
go test -fuzz=FuzzReverse -fuzztime=30s generates inputs for thirty seconds and keeps the first failure; without -fuzztime it runs until interrupted. By default the fuzzer uses every core it can, and -parallel caps that. A generated run prints a progress line with the number of executions and the inputs it covered, which is why a fuzz session is not a page of fixed output and this course shows the deterministic replay instead.
Exercises
- Fix Reverse to work on runes and run the corpus again. Does the saved entry still fail, and what does that tell you about the corpus?
- Write a fuzz target for a parser of your own and add three seeds, including an empty string and one invalid input. Which invariant can you check without knowing the answer?
- Run the fuzzer for thirty seconds on the fixed version and add any new corpus entry it writes. Should the entry be committed if it passes?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What signature must a fuzz test have?
Answer
func FuzzXxx(f *testing.F)
The fuzzer takes *testing.F and the function name starts with Fuzz.
-
What does f.Add do?
Answer
Registers a seed value for the corpus
Seeds run on every go test; generation starts only with -fuzz.
-
What does a fuzz function assert?
Answer
An invariant that must hold for every input
The generator produces inputs the author never wrote down.
-
Where does a crashing input get saved?
Answer
testdata/fuzz/FuzzXxx/ in the package
The entry is committed and replayed by later plain runs.
-
What does go test -run FuzzXxx do?
Answer
Runs the seeds and the saved corpus, without generating
-run matches the name; -fuzz is what turns on generation.
-
What does -fuzztime=30s limit?
Answer
How long the fuzzer generates inputs
Without it the fuzzer runs until it is interrupted.
-
Why does the byte-wise reverse fail on héllo?
Answer
It splits the two-byte é, so the result is not valid UTF-8
Reversing bytes is not reversing runes, and the fuzzer found the difference.
-
Should a passing corpus entry be committed?
Answer
Yes, it is a regression test for a case that was once interesting
The corpus is code: it records inputs the project cares about.
-
What does the first line of a corpus file contain?
Answer
The format version, go test fuzz v1
The rest of the file is the value in Go syntax.
-
Why is a fuzzer useful for a parser?
Answer
It finds inputs a hand-written table would never try
A fuzzer explores the input space; the invariant is still the author's job.
The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev