_content/doc/tutorial: update fuzzing tutorial
Update the fuzzing tutorial based on results from the UXR study to:
-Link to further documentation
-Add explanation of -fuzztime and other testing flags
-Explain fuzzing output terms like "new interesting"
-Improved clarity on some tutorial steps re: copy/pasting
Change-Id: Ia781407130b87d3a79e2bbcc912ad7fa24028056
Reviewed-on: https://go-review.googlesource.com/c/website/+/464020
Reviewed-by: Julie Qiu <julieqiu@google.com>
Run-TryBot: Julie Qiu <julieqiu@google.com>
Auto-Submit: Julie Qiu <julieqiu@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Alice Merrick <amerrick@google.com>
diff --git a/_content/doc/tutorial/fuzz.md b/_content/doc/tutorial/fuzz.md
index 13f9085..8957197 100644
--- a/_content/doc/tutorial/fuzz.md
+++ b/_content/doc/tutorial/fuzz.md
@@ -302,7 +302,20 @@
2. Run `FuzzReverse` with fuzzing, to see if any randomly generated string
inputs will cause a failure. This is executed using `go test` with a new
- flag, `-fuzz`.
+ flag, `-fuzz`, set to the parameter `Fuzz`. Copy the command below.
+
+ ```
+ $ go test -fuzz=Fuzz
+ ```
+
+ Another useful flag is `-fuzztime`, which restricts the time fuzzing takes.
+ For example, specifying `-fuzztime 10s` in the test below would mean that,
+ as long as no failures occurred earlier, the test would exit by default
+ after 10 seconds had elapsed. See [this
+ section](https://pkg.go.dev/cmd/go#hdr-Testing_flags) of the cmd/go
+ documentation to see other testing flags.
+
+ Now, run the command you just copied.
```
$ go test -fuzz=Fuzz
@@ -538,6 +551,12 @@
This time, we only want to run the failing test in order to inspect the logs. To
do this, we will use `go test -run`.
+To run a specific corpus entry within FuzzXxx/testdata, you can provide
+{FuzzTestName}/{filename} to `-run`. This can be helpful when debugging.
+In this case, set the `-run` flag equal to the exact hash of the failing test.
+Copy and paste the unique hash from your terminal;
+it will be different than the one below.
+
```
$ go test -run=FuzzReverse/28f36ef487f23e6c7a81ebdaa9feffe2f2b02b4cddaa6252e87f69863046a5e0
input: "\x91"
@@ -553,9 +572,6 @@
FAIL example/fuzz 0.145s
```
-To run a specific corpus entry within FuzzXxx/testdata, you can provide
-{FuzzTestName}/{filename} to `-run`. This can be helpful when debugging.
-
Knowing that the input is invalid unicode, let’s fix the error in our `Reverse`
function.
@@ -655,8 +671,10 @@
ok example/fuzz 0.019s
```
-2. Fuzz it with `go test -fuzz=Fuzz`, then after a few seconds has passed, stop
- fuzzing with `ctrl-C`.
+2. Fuzz it with `go test -fuzz=Fuzz`, then after a few seconds has passed, stop
+ fuzzing with `ctrl-C`. The fuzz test will run until it encounters a failing
+ input unless you pass the `-fuzztime` flag. The default is to run forever if no
+ failures occur, and the process can be interrupted with `ctrl-C`.
```
$ go test -fuzz=Fuzz
@@ -672,10 +690,6 @@
ok example/fuzz 228.000s
```
- The fuzz test will run until it encounters a failing input unless you pass
- the `-fuzztime` flag. The default is to run forever if no failures occur, and
- the process can be interrupted with `ctrl-C`.
-
3. Fuzz it with `go test -fuzz=Fuzz -fuzztime 30s` which will fuzz for 30
seconds before exiting if no failure was found.
@@ -703,6 +717,13 @@
In addition to the `-fuzz` flag, several new flags have been added to `go
test` and can be viewed in the [documentation](/security/fuzz/#custom-settings).
+ See [Go Fuzzing](https://go.dev/security/fuzz/#command-line-output) for more
+ information on terms used in fuzzing output. For example, "new interesting"
+ refers to inputs that expand the code coverage of the existing fuzz test
+ corpus. The number of "new interesting" inputs can be expected to increase
+ sharply as fuzzing begins, spike several times as new code paths are
+ discovered, then taper off over time.
+
## Conclusion {#conclusion}
Nicely done! You've just introduced yourself to fuzzing in Go.
@@ -788,3 +809,5 @@
})
}
```
+
+[Back to top](#top)
\ No newline at end of file
