---
name: debug-with-valgrind
description: Debug crashes, segfaults, and memory errors using valgrind integration with nextest through pre-configured profiles
---
# Debugging with Valgrind + Nextest
When you encounter crashes, segfaults, or memory errors in tests, use valgrind for proper debugging.
## Quick Usage
```bash
# Run a specific test under valgrind
cargo nextest run --profile valgrind -p PACKAGE --test TEST_FILE TEST_NAME
# Example
cargo nextest run --profile valgrind -p facet-format-json --test jit_deserialize test_jit_option_some
```
## How It Works
The project has valgrind pre-configured in `.config/nextest.toml`:
1. **Wrapper script**: Defined as `[scripts.wrapper.valgrind]`
- Command: `valgrind --leak-check=full --show-leak-kinds=all ...`
- Automatically wraps test execution
2. **Profile**: `[profile.valgrind]` applies the wrapper to all tests on Linux
3. **Running**: Use `--profile valgrind` flag with nextest
## Benefits
- ✅ **Automatic setup** - no manual valgrind commands needed
- ✅ **Proper configuration** - leak checking, error codes pre-configured
- ✅ **Integrated** - works with nextest filtering and test selection
- ✅ **Clean output** - nextest captures and formats valgrind output
## Don't Do This
❌ Running valgrind manually: `valgrind ./target/debug/deps/test-binary`
❌ Using raw `--no-run` + valgrind commands
❌ Playing hunt-the-segfault without proper tools
## Do This Instead
✅ Use the pre-configured profile: `cargo nextest run --profile valgrind <filters>`
✅ Let nextest handle the wrapper script integration
✅ Get clean, actionable valgrind output immediately
## Debugging Workflow
1. Test crashes with SIGSEGV
2. Run: `cargo nextest run --profile valgrind -p PACKAGE --test FILE TEST_NAME`
3. Valgrind shows exact line where invalid read/write occurs
4. Fix the bug
5. Verify with regular tests
## See Also
- Nextest wrapper scripts docs: https://nexte.st/docs/configuration/wrapper-scripts/
- Project nextest config: `.config/nextest.toml`
