docs: enhance fuzz testing README with comprehensive guide (#25270)

Co-authored-by: Alex | Interchain Labs <alex@djinntek.world>
This commit is contained in:
Avory 2025-08-29 21:21:02 +03:00 committed by GitHub
parent ca3d0fea69
commit bc8ef3aa41
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -1,10 +1,51 @@
# Fuzzing
## Running
This directory contains fuzz tests for the Cosmos SDK to identify potential bugs, crashes, and security vulnerabilities through automated input generation.
The fuzz tests are in standard [Go format](https://go.dev/doc/fuzz/).
To run a fuzz test, use the `-fuzz` flag to `go test`. For example:
## What is Fuzzing?
Fuzzing is a testing technique that automatically generates random inputs to find edge cases, crashes, and unexpected behavior in code. The Go fuzzing framework uses coverage-guided fuzzing to efficiently explore code paths.
## Available Fuzz Tests
The following fuzz tests are available:
- **Crypto HD**: `FuzzCryptoHDNewParamsFromPath`, `FuzzCryptoHDDerivePrivateKeyForPath`
- **Types**: `FuzzTypesParseTimeBytes`, `FuzzTypesParseDecCoin`, `FuzzTypesParseCoin`, `FuzzTypesVerifyAddressFormat`, `FuzzTypesDecSetString`
- **Tendermint**: `FuzzTendermintAminoDecodeTime`
- **Crypto Types**: `FuzzCryptoTypesCompactBitArrayMarshalUnmarshal`
- **Unknown Proto**: `FuzzUnknownProto`
## Running Fuzz Tests
The fuzz tests use the standard [Go fuzzing format](https://go.dev/doc/fuzz/). To run a specific fuzz test, use the `-fuzz` flag with `go test`:
```shell
go test -fuzz FuzzCryptoHDNewParamsFromPath ./tests
# Run a specific fuzz test
go test -fuzz FuzzCryptoHDNewParamsFromPath ./tests/fuzz/tests
# Run all fuzz tests
go test -fuzz . ./tests/fuzz/tests
# Run with time limit (e.g., 30 seconds)
go test -fuzz FuzzTypesParseTimeBytes -fuzztime 30s ./tests/fuzz/tests
```
## Interpreting Results
- **Crashes**: If a fuzz test crashes, it will save the input that caused the crash in the `testdata` directory
- **Coverage**: Fuzzing automatically tracks code coverage and focuses on unexplored paths
- **Timeouts**: Long-running fuzz tests can be stopped with `Ctrl+C`
## Requirements
- Go 1.18+ (required for built-in fuzzing support)
- The `gofuzz` build tag is also supported for compatibility
## Contributing
When adding new fuzz tests:
1. Follow the naming convention: `Fuzz<Package><Function>`
2. Include proper error handling and input validation
3. Add the test to this README
4. Ensure the test can run for extended periods without crashes