Your Go service parses HTTP headers, protobuf payloads, YAML manifests, or images from strangers on the internet. One malformed byte sequence can panic the handler, blow the memory limit, or quietly corrupt a downstream write. Unit tests won’t save you — you can’t enumerate the inputs you never imagined.

Fuzzing can. The problem is that Go has three overlapping tools with confusingly similar names, and picking the wrong one wastes weeks: native testing.F fuzzing (in the standard library since Go 1.18), go-fuzz (Dmitry Vyukov’s coverage-guided pioneer), and gofuzz (Google’s random struct generator — which, despite the name, is not a fuzzer at all).

This guide sorts them out with working code, real repository data pulled today, and the traps that cost teams days.

TL;DR — Quick Verdict

Use native testing.F in 2026. It ships with the toolchain, needs zero extra binaries, keeps regression inputs in testdata/fuzz/ where code review can see them, and runs in CI with the same go test you already have.

  • Need to fuzz a large legacy codebase on old Go versions (< 1.18) or need multi-process throughput on huge state machines? Reach for go-fuzz, but accept that it is frozen and module support is quirky.
  • Need realistic structs to feed a fuzzer or a property test? That is gofuzz — a data generator, not a coverage-guided engine. It complements native fuzzing, it does not replace it.

If you take one thing away: gofuzz and native fuzzing are teammates. go-fuzz is the retired veteran.

How the Three Tools Compare

DimensionNative testing.Fgo-fuzz (dvyukov)gofuzz (google)
What it isCoverage-guided fuzzer in go testCoverage-guided fuzzer (external binary)Random value generator for Go types
GitHub starsPart of golang/go4,8451,493
Last repo pushActive (go toolchain)Sep 24, 2024Nov 7, 2022
Requires extra binaryNogo-fuzz, go-fuzz-buildNo
Corpus locationtestdata/fuzz/FuzzX/ (committable)$workdir/corpus (not committable by default)N/A — generated in-memory
Input typesstring, []byte, ints, floats, boolSingle Fuzz(data []byte) intAny struct via reflection
Coverage feedbackYes, compiler-instrumentedYes, via go-fuzz-buildNo
Crash minimizationAutomaticAutomatic (crashers/ + minimize)N/A
Runs in plain go testYesNoYes (as a helper)
Best fit95% of teamsLegacy / high-throughput campaignsTest fixtures, property tests

The star counts and push dates above were fetched from GitHub at publish time, not remembered — that matters because go-fuzz has had no commits since September 2024, which is the single most important fact for your adoption decision.

Scenario Decision Matrix

Your situationPickWhy
New service, Go ≥ 1.18, want fuzzing in CI todayNative testing.FZero deps, corpus lives in the repo, go test integration
Parser with a hand-built seed corpus in another formatNative testing.F + f.Add loop over seedsSeeds convert trivially from []byte
Stuck on Go 1.17 or a fork without fuzzinggo-fuzzThe only coverage-guided option there
Need 8 parallel workers hammering a stateful target for daysgo-fuzz (-procs, -workers)Mature long-run tuning knobs
Need a random Config struct with 40 fieldsgofuzzReflection fills nested structs, maps, interfaces
Writing table tests and want varied but valid inputsgofuzzGenerates real values, not byte soup
Wrapping a C library via cgoEither native or go-fuzzBoth instrument Go code; cgo paths need manual checks

Native Go Fuzzing — the Default Choice

Native fuzzing lives in testing. You write a FuzzXxx function that receives *testing.F, seed a few inputs with f.Add, then call f.Fuzz with a typed callback:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
package header

import "testing"

func FuzzParseHeader(f *testing.F) {
	// Seed corpus: valid, empty and deliberately hostile inputs.
	f.Add("Content-Length: 42\r\n")
	f.Add("")
	f.Add("X:\x00\xff\r\n\r\n")

	f.Fuzz(func(t *testing.T, raw string) {
		h, err := ParseHeader(raw)
		if err != nil {
			if h != nil {
				t.Fatalf("non-nil header with error: %v", err)
			}
			return
		}
		// Round-trip property: anything we can parse we must re-serialize.
		if _, err := SerializeHeader(h); err != nil {
			t.Fatalf("parse ok but serialize failed: %v", err)
		}
	})
}

Run it for 90 seconds:

1
go test -run=^$ -fuzz=FuzzParseHeader -fuzztime=90s ./internal/header

Two things happen. First, the fuzzer mutates seeds and keeps any input that reaches new coverage. Second, when it panics it writes a minimized reproducer into testdata/fuzz/FuzzParseHeader/<hash>:

1
2
3
4
5
go test ./internal/header
--- FAIL: FuzzParseHeader (0.01s)
    --- FAIL: FuzzParseHeader (0.00s)
        header_test.go:22: non-nil header with error: unexpected EOF
    Failing input written to testdata/fuzz/FuzzParseHeader/8b1a2c3d9e4f5a60

That file is plain text, diffable, and committed like any other test fixture. From then on go test ./... re-runs it as a normal regression test — this is the killer feature. Fuzzing findings become permanent unit tests for free, with no infrastructure to maintain.

Hard limits to know: f.Fuzz only accepts string, []byte, bool, and sized int/float types. No structs, no pointers, no slices of structs. One fuzz target per invocation, and the default wall clock is 10 seconds if you forget -fuzztime.

go-fuzz — the Veteran You Inherit, Not Adopt

Before Go 1.18, go-fuzz was the answer. It still works, and on huge campaigns its multi-process model is genuinely fast. The interface is a single function returning an int priority:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
//go:build gofuzz

package png

import (
	"bytes"
	"image/png"
)

func Fuzz(data []byte) int {
	img, err := png.Decode(bytes.NewReader(data))
	if err != nil {
		if img != nil {
			panic("img != nil on error")
		}
		return 0
	}
	var w bytes.Buffer
	if err := png.Encode(&w, img); err != nil {
		panic(err)
	}
	return 1 // lexically valid input, raise its priority
}

Build an instrumented package and run it:

1
2
3
4
5
go install github.com/dvyukov/go-fuzz/go-fuzz@latest
go install github.com/dvyukov/go-fuzz/go-fuzz-build@latest

go-fuzz-build            # produces png-fuzz.zip in the package dir
go-fuzz -bin=./png-fuzz.zip -workdir=./fuzz-out -procs=4

The return value is the API: 1 means “this input parsed cleanly, mutate around it”, -1 means “never add to corpus”, 0 means neutral. Crashers land in ./fuzz-out/crashers/ with a .output and .quoted companion file.

go-fuzz corpus and crash artifacts in the official project material

Why it is a liability in 2026: the repository has not been pushed to since September 2024, module support is documented as “preliminary” with GO111MODULE=off as the suggested workaround, and the //go:build gofuzz tag plus a separate Fuzz([]byte) int signature means every finding needs a hand-written bridge before it can live in your normal test suite. You also cannot run it on a main package, and the corpus directory is not something reviewers will happily approve in a pull request.

Keep it if you already have campaigns running. Do not start a new project on it.

gofuzz — the Misunderstood One

github.com/google/gofuzz has “fuzz” in the name and no fuzzing engine inside. It is a reflection-based random value generator: give it a pointer and it fills every field with plausible random data, recursing into nested structs, maps, slices and interfaces.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import (
	"testing"

	"github.com/google/gofuzz"
)

type RetryPolicy struct {
	MaxAttempts int
	BackoffMs   []int
	Labels      map[string]string
	Jitter      *float64
}

func TestRetryPolicyInvariants(t *testing.T) {
	f := fuzz.New().NilChance(0.1).NumElements(1, 4)
	for i := 0; i < 500; i++ {
		var p RetryPolicy
		f.Fuzz(&p)
		if got := len(p.BackoffMs); got > 0 && p.MaxAttempts == 0 {
			t.Fatalf("policy has backoff but no attempts: %+v", p)
		}
	}
}

That test explores 500 realistic shapes in milliseconds without a single byte-level mutation. This is where gofuzz shines: generating valid-ish domain objects to test invariants, defaults, serialization round-trips, and API handlers. It pairs naturally with native fuzzing — use gofuzz to build seeds, and testing.F to mutate the serialized form of those seeds.

What it cannot do: coverage feedback, crash minimization, or corpus persistence. Treat it as a fixture factory, not a security tool.

Running Fuzzing in CI Without Melting Your Runners

Fuzzing is unbounded by design, so CI must bound it explicitly. A 60-second smoke run on every pull request plus a longer nightly campaign is the pattern that survives contact with real teams:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
name: fuzz
on:
  pull_request:
  schedule:
    - cron: "0 3 * * *"

jobs:
  fuzz:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        target: [FuzzParseHeader, FuzzParseChunked, FuzzParseCookie]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: "stable"
      - name: Fuzz ${{ matrix.target }}
        run: |
          go test -run=^$ -fuzz='^${{ matrix.target }}$' \
            -fuzztime=${{ github.event_name == 'schedule' && '15m' || '60s' }} \
            ./internal/...
      - name: Upload crashers
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: fuzz-crashers-${{ matrix.target }}
          path: internal/**/testdata/fuzz/**

Two details that matter more than they look:

  1. -run=^$ prevents the fuzz corpus from also running as ordinary tests in the same invocation, which otherwise doubles wall time.
  2. Upload the testdata/fuzz diff on failure, not just the log. The failing input file is the actual deliverable — it becomes the regression test you commit.

Pitfalls and Migration Notes

  • Don’t commit the whole corpus. Native fuzzing writes interesting inputs to $GOCACHE/fuzz; only testdata/fuzz/ is meant for the repository. Committing cache output bloats the repo with thousands of files that reviewers will reject.
  • f.Fuzz closures must be deterministic and fast. Logging, network calls, or time.Now() inside the target poison coverage signal and slow the campaign to a crawl.
  • Never fuzz against production data. Crash artifacts contain the raw input; treat testdata/fuzz/ as potentially sensitive.
  • Migrating off go-fuzz: port Fuzz(data []byte) int { ... } to f.Fuzz(func(t *testing.T, data []byte) { ... }), replace return 1 with no-op (native fuzzing derives priority from coverage, not your return value), and convert panic(...) into t.Fatal(...). Then replay the old corpus via f.Add in a loop so no historical finding is lost.
  • Memory blowups are not caught automatically in the same way as panics on some targets; add an explicit size check at the top of the callback if your parser allocates based on length prefixes.
  • t.Skip inside a fuzz target is a trap. Skipping invalid inputs looks tidy but prevents the fuzzer from learning the rejection path’s coverage. Prefer a plain return with a validated branch.

Why Local Fuzzing Beats a Hosted Dashboard

A hosted fuzz dashboard looks great in a slide deck. In practice, the inputs your fuzzer finds are the same inputs an attacker sends to your edge proxy, and shipping them to a third-party service means shipping your most interesting malformed payloads off-site. Keeping the campaign in go test means the corpus, the crashers, and the regression tests all live in the same git history as the fix — which is exactly where an incident reviewer will look six months later.

For adjacent reading, our AFL++ vs honggfuzz vs libFuzzer comparison covers the native-code side of the same problem, the OSS-Fuzz, ClusterFuzz and FuzzBench breakdown explains continuous fuzzing infrastructure, and our Go testing frameworks guide shows where assertions fit once a fuzzer hands you a failing input.

FAQ

Is native Go fuzzing good enough to replace go-fuzz entirely? For new code, yes. Native fuzzing gives you coverage guidance, automatic minimization, and permanent regression tests inside go test. The gaps are multi-process tuning knobs and support for pre-1.18 toolchains. If your campaign needs dozens of parallel workers on a stateful target for days, go-fuzz still has better knobs — but it has been unmaintained since September 2024.

What is the difference between gofuzz and go-fuzz? They are unrelated projects with confusingly similar names. github.com/google/gofuzz is a reflection-based random value generator with no coverage engine — you use it to build realistic structs. github.com/dvyukov/go-fuzz is a real coverage-guided fuzzer that mutates byte slices and minimizes crashes. Installing one when you meant the other is the single most common beginner mistake in this space.

How long should I fuzz in CI? 60 seconds per target on pull requests and 15 minutes nightly is a good starting point. Diminishing returns set in quickly: most crashes in a mature parser appear in the first few minutes because seed coverage is the bottleneck, not wall-clock time. Improve the seed corpus before extending -fuzztime.

Where does native fuzzing store the corpus, and should I commit it? Interesting inputs go to $GOCACHE/fuzz, which is not part of the repository. Only testdata/fuzz/FuzzTargetName/ is committed, and it should contain just the reproducers you want as regression tests — typically a handful of files per target, not thousands.

Can I fuzz CLI tools or functions that read from disk? Not directly. f.Fuzz mutates typed values, so restructure the code so the interesting logic is a pure function from bytes to a result, and keep the I/O in a thin wrapper. Fuzzing a function that opens files mostly measures your filesystem.


💰 想测试你的市场判断力?我用 Polymarket 做预测市场交易——这是全球最大的预测市场平台,从大选结果到技术监管时间线,什么都可以押注。和赌博不同,这是真正的信息市场:你懂的信息越多,胜率越高。我靠预测技术相关事件的走向已经赚了不少。用我的邀请链接注册:Polymarket.com