hclsyntax/fuzz/README.md

# hclsyntax fuzzing utilities

This directory contains helper functions and corpora that can be used to
fuzz-test the `hclsyntax` parsers using Go's native fuzz testing capabilities.

Please see https://go.dev/doc/fuzz/ for more information on fuzzing.

## Prerequisites
* Go 1.18

## Running the fuzzer

Each exported function in the `hclsyntax` package has a corresponding fuzz test.
These can be run one at a time via `go test`:

```
$ cd fuzz
$ go test -fuzz FuzzParseTemplate
$ go test -fuzz FuzzParseTraversalAbs
$ go test -fuzz FuzzParseExpression
$ go test -fuzz FuzzParseConfig
```

This command will exit only when a crasher is found (see "Understanding the 
result" below.)

## Seed corpus

The seed corpus for each fuzz test function is stored in the corresponding
directory under `hclsyntax/fuzz/testdata/fuzz/`. For example:

```
$ ls hclsyntax/fuzz/testdata/fuzz/FuzzParseTemplate
empty.tmpl
escape-dollar.tmpl
escape-newline-tmpl
...
```

Additional seed inputs can be added to this corpus. Each file must be in the Go 1.18 corpus file format. Files can be converted to this format using the `file2fuzz` tool. To install it:

```
$ go install golang.org/x/tools/cmd/file2fuzz@latest
$ file2fuzz -help
```

## Understanding the result

A small number of subdirectories will be created in the work directory.

If you let `go-fuzz` run for a few minutes (the more minutes the better) it
may detect "crashers", which are inputs that caused the parser to panic.
These are written to `hclsyntax/fuzz/testdata/fuzz/<fuzz test name>/`:

```
$ ls hclsyntax/fuzz/testdata/fuzz/FuzzParseTemplate
582528ddfad69eb57775199a43e0f9fd5c94bba343ce7bb6724d4ebafe311ed4
```

A good first step to fixing a detected crasher is to copy the failing input
into one of the unit tests in the `hclsyntax` package and see it crash there
too. After that, it's easy to re-run the test as you try to fix it.