fuzz

Fuzz a parser to find bugs and ensure consistency

The fuzz command tests a parser by performing random edits and ensuring that undoing these edits results in consistent parse trees.

tree-sitter fuzz [OPTIONS]

Aliases: f

How It Works

The fuzzer:

1. Parses test files from your corpus
2. Applies random edits to the source code
3. Re-parses the edited code
4. Undoes the edits
5. Verifies the parse tree matches the original

The test fails if:

• Parse trees are not equal after undoing edits
• Changed ranges are inconsistent
• The parser crashes or hangs

Options

Test Selection

-s, --skip · names

A list of test names to skip fuzzing. Can be specified multiple times.

-i, --include · regex

Only fuzz corpus test cases whose names match this regex.

-e, --exclude · regex

Skip corpus test cases whose names match this regex.

Parser Options

-p, --grammar-path · path

The path to the directory containing the grammar. Implies --rebuild.

--lib-path · path

The path to the parser’s dynamic library. Used instead of the cached or automatically generated library.

--lang-name · string

If --lib-path is used, the name of the language used to extract the library’s language function.

--subdir · path

The directory containing the parser. Primarily useful in multi-language repositories.

Fuzzing Parameters

--edits · number · default: "3"

The maximum number of edits to perform per fuzz test.

Can also be set via the TREE_SITTER_EDITS environment variable.

--iterations · number · default: "10"

The number of iterations to run per test.

Can also be set via the TREE_SITTER_ITERATIONS environment variable.

Debug Options

-l, --log · flag

Output parsing and lexing logs to stderr.

--log-graphs · flag

Output logs of the graphs of the stack and parse trees during parsing. Graphs are constructed with graphviz dot, and output is written to log.html.

Build Options

-r, --rebuild · flag

Force a rebuild of the parser before running the fuzzer.

Examples

Basic Fuzzing

tree-sitter fuzz

Fuzz with More Iterations

tree-sitter fuzz --iterations 100 --edits 5

Fuzz Specific Tests

tree-sitter fuzz --include "function"

Skip Problematic Tests

tree-sitter fuzz --skip "complex_expression" --skip "nested_blocks"

Fuzz with Debug Logging

tree-sitter fuzz --log --log-graphs

Fuzz with Environment Variables

TREE_SITTER_EDITS=10 TREE_SITTER_ITERATIONS=50 tree-sitter fuzz

Best Practices

Start Small

Begin with few iterations and edits, then increase:

tree-sitter fuzz --iterations 10 --edits 3

Focus on Problem Areas

Use --include to focus on specific language constructs:

tree-sitter fuzz --include "string|comment"

Regular Fuzzing

Incorporate fuzzing into your development workflow:

# After making grammar changes
tree-sitter generate
tree-sitter test
tree-sitter fuzz --iterations 20

CI Integration

Add fuzzing to your CI pipeline:

# .github/workflows/test.yml
- name: Fuzz parser
  run: tree-sitter fuzz --iterations 50

Interpreting Results

Success

If all tests pass, you’ll see:

Fuzz test passed for all corpus tests

Failure

If a test fails, you’ll see:

• The test name that failed
• The edit sequence that caused the failure
• Details about the inconsistency

Use this information to:

1. Reproduce the issue manually
2. Add a regression test
3. Fix the grammar or external scanner

Troubleshooting

Fuzzing Takes Too Long

Reduce iterations or edits:

tree-sitter fuzz --iterations 5 --edits 2

Tests Hang

Some inputs may cause infinite loops. Use --skip to bypass:

tree-sitter fuzz --skip "problematic_test"

Inconsistent Failures

Fuzzing is random, so failures may not reproduce. To help:

1. Note the seed value if displayed
2. Run multiple times to confirm
3. Add logging to understand the issue