Fuzzing
Fuzzing is part of the testing package and of the go test command since Go 1.18, so a project needs no tool outside the toolchain: a function whose name starts with Fuzz, a few seeds, and one invariant the fuzzer checks for every input it generates. The fuzzer is coverage-guided, which means it keeps the inputs that reach new code and mutates from there.
The target and the invariant
The function under test reverses a string. The byte version below is correct for ASCII and wrong for anything else: it moves the bytes of a multi-byte character apart, and the result is not valid UTF-8. The test that comes with it passes, because it only uses English.
package reverse
// Reverse returns s with its bytes in the opposite order.
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)
}
The fuzz target names the bug as a property instead of an example: whatever the input, the result of Reverse must be valid UTF-8. The second check, reversing twice, has a meaning only for input that is valid UTF-8, because the reverse of an invalid byte sequence is allowed to lose the bytes that were never characters.
package reverse
import (
"testing"
"unicode/utf8"
)
func FuzzReverse(f *testing.F) {
f.Add("Hello, world")
f.Add("")
f.Fuzz(func(t *testing.T, s string) {
rev := Reverse(s)
if !utf8.ValidString(rev) {
t.Errorf("Reverse(%q) = %q, which is not valid UTF-8", s, rev)
}
if utf8.ValidString(s) {
if again := Reverse(rev); again != s {
t.Errorf("Reverse(Reverse(%q)) = %q", s, again)
}
}
})
}
f.Add seeds the corpus with values worth starting from, and the empty string is one of them. go test without -fuzz runs the seeds as ordinary subtests, so a fuzz target is also a regression test and belongs in the usual run.
The first fuzz run
-fuzztime stops the run after the given time, and the fuzzer works from a pool of processes on every CPU. The bug is found before the first second is over:
go test -fuzz=FuzzReverse -fuzztime=2s ./reverse
fuzz: elapsed: 0s, gathering baseline coverage: 0/2 completed
fuzz: elapsed: 0s, gathering baseline coverage: 2/2 completed, now fuzzing with 4 workers
fuzz: minimizing 47-byte failing input file
fuzz: elapsed: 0s, minimizing
--- FAIL: FuzzReverse (0.02s)
--- FAIL: FuzzReverse (0.00s)
fuzz_test.go:14: Reverse("\xc0") = "\xc0", which is not valid UTF-8
Failing input written to testdata/fuzz/FuzzReverse/e386ddb8ccb05b77
To re-run:
go test -run=FuzzReverse/e386ddb8ccb05b77
FAIL
exit status 1
FAIL example.com/text/reverse 0.023s
One byte, 0xC0, is enough: it is the start byte of a two-byte sequence that never arrives, so it is not a character, and the byte reversal keeps it in a place where it still is not one. The fuzzer shrank the failing input to the smallest version before it stopped, which is why the message shows a one-byte string and not the forty-seven bytes it started from.
The crasher and the replay
The failing input is written to testdata/fuzz/FuzzReverse under a hash of its content, and it is now part of the package. The file is two lines of Go syntax:
cat reverse/testdata/fuzz/FuzzReverse/e386ddb8ccb05b77
go test fuzz v1
string("\xc0")
The first line is the format version and the second is the value with its type, which is how a fuzz corpus file describes a string, a slice of bytes, or a number without ambiguity. Running the target without -fuzz replays it as a subtest named after the file:
go test -run=FuzzReverse/e386ddb8ccb05b77 -v ./reverse
=== RUN FuzzReverse
=== RUN FuzzReverse/e386ddb8ccb05b77
fuzz_test.go:14: Reverse("\xc0") = "\xc0", which is not valid UTF-8
--- FAIL: FuzzReverse (0.00s)
--- FAIL: FuzzReverse/e386ddb8ccb05b77 (0.00s)
FAIL
FAIL example.com/text/reverse 0.006s
FAIL
That is the whole regression story: the file is committed with the fix, the ordinary go test ./... keeps checking it, and a future change that reintroduces the bug fails in a second with the exact input.
The fix
Reversing runes instead of bytes makes every result valid UTF-8, because invalid input bytes become U+FFFD on the way in. The contract now says so, and the double-reverse check stays behind the guard for valid input, where it is true.
package reverse
// Reverse returns s with its runes in the opposite order. Bytes that are not
// valid UTF-8 become U+FFFD, so the result is always valid UTF-8.
func Reverse(s string) string {
r := []rune(s)
for i, j := 0, len(r)-1; i < j; i, j = i+1, j-1 {
r[i], r[j] = r[j], r[i]
}
return string(r)
}
go test -fuzz=FuzzReverse -fuzztime=2s ./reverse
fuzz: elapsed: 0s, gathering baseline coverage: 0/5 completed
fuzz: elapsed: 0s, gathering baseline coverage: 5/5 completed, now fuzzing with 4 workers
fuzz: elapsed: 3s, execs: 38999 (13000/sec), new interesting: 22 (total: 27)
fuzz: elapsed: 3s, execs: 38999 (0/sec), new interesting: 22 (total: 27)
PASS
ok example.com/text/reverse 3.029s
The run reports the inputs it executed, the ones that reached new code and the total corpus. The numbers depend on the machine and on the run; what matters is the shape: tens of thousands of executions in seconds, and a corpus that grows only when an input teaches the fuzzer something. Five baseline entries this time, because the corpus now holds the two seeds, the crasher and the interesting inputs the build cache kept from the previous run.
The corpus and the cost
Three places hold inputs. The seeds in f.Add are in the source. The files in testdata/fuzz/FuzzTarget are committed and replay on every plain go test. The rest lives in the build cache and is not part of the repository; go clean -fuzzcache drops it.
A fuzz target is worth its cost where the input space is larger than the examples a person thinks of: parsers, decoders, validators, anything that reads a length or an escaping rule. It is a poor fit for code whose input is an interface or a struct with invariants, where a table already covers the cases, and it cannot check speed or memory, which is the next page.
The lesson that builds a fuzz target for a real parser is native fuzzing, and Capstone 1 fuzzes a JSON reader in table tests and fuzzing.
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