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".
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.
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.
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
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:
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 testalone only runs the corpus.go test -fuzz=FuzzReversefuzzes one target (the pattern must match exactly one) until you stop it, or for-fuzztime=30sor-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=0if 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 totestdata. - 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).
Related
- testing, testing.T
- unicode/utf8 and string type
- Tutorial: Benchmarks and fuzzing