Remove cargo test targets, use nextest exclusively (#7874)

Fixes #7835


  - Remove cargo test-based Make targets (`test-release`, `test-debug`, `run-ef-tests`)
- Update aliases (`test`, `test-full`, `test-ef`) to use existing nextest equivalents
- Update contributing documentation to use nextest examples
- Fix example commands that previously referenced non-existing packages (`ssz`/`eth2_ssz`)


Co-Authored-By: Daniel Ramirez-Chiquillo <hi@danielrachi.com>
This commit is contained in:
Daniel Ramirez-Chiquillo
2025-09-10 08:52:34 -05:00
committed by GitHub
parent f71d69755d
commit 2ecbb7f90b
5 changed files with 79 additions and 114 deletions

View File

@@ -7,25 +7,28 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
**Important**: Always branch from `unstable` and target `unstable` when creating pull requests.
### Building and Installation
- `make install` - Build and install the main Lighthouse binary in release mode
- `make install-lcli` - Build and install the `lcli` utility binary
- `cargo build --release` - Standard Rust release build
- `cargo build --bin lighthouse --features "gnosis,slasher-lmdb"` - Build with specific features
### Testing
- `make test` - Run the full test suite in release mode (excludes EF tests, beacon_chain, slasher, network, http_api)
- `make nextest-release` - Run tests using nextest (faster parallel test runner)
- `make test-release` - Run tests using nextest (faster parallel test runner)
- `make test-beacon-chain` - Run beacon chain tests for all supported forks
- `make test-slasher` - Run slasher tests with all database backend combinations
- `make test-ef` - Download and run Ethereum Foundation test vectors
- `make test-full` - Complete test suite including linting, EF tests, and execution engine tests
- `cargo test -p <package_name>` - Run tests for a specific package
- `cargo test -p <package_name> <test_name>` - Run individual test (preferred during development iteration)
- `cargo nextest run -p <package_name>` - Run tests for a specific package
- `cargo nextest run -p <package_name> <test_name>` - Run individual test (preferred during development iteration)
- `FORK_NAME=electra cargo nextest run -p beacon_chain` - Run tests for specific fork
**Note**: Full test suite takes ~20 minutes. When iterating, prefer running individual tests.
### Linting and Code Quality
### Linting and Code Quality
- `make lint` - Run Clippy linter with project-specific rules
- `make lint-full` - Run comprehensive linting including tests (recommended for thorough checking)
- `make cargo-fmt` - Check code formatting with rustfmt
@@ -33,8 +36,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
- `make audit` - Run security audit on dependencies
### Cross-compilation
- `make build-x86_64` - Cross-compile for x86_64 Linux
- `make build-aarch64` - Cross-compile for ARM64 Linux
- `make build-aarch64` - Cross-compile for ARM64 Linux
- `make build-riscv64` - Cross-compile for RISC-V 64-bit Linux
## Architecture Overview
@@ -44,13 +48,15 @@ Lighthouse is a modular Ethereum consensus client with two main components:
### Core Components
**Beacon Node** (`beacon_node/`)
- Main consensus client that syncs with the Ethereum network
- Contains the beacon chain state transition logic (`beacon_node/beacon_chain/`)
- Handles networking, storage, and P2P communication
- Provides HTTP API for validator clients and external tools
- Entry point: `beacon_node/src/lib.rs`
**Validator Client** (`validator_client/`)
**Validator Client** (`validator_client/`)
- Manages validator keystores and performs validator duties
- Connects to beacon nodes via HTTP API
- Handles block proposals, attestations, and sync committee duties
@@ -60,31 +66,37 @@ Lighthouse is a modular Ethereum consensus client with two main components:
### Key Subsystems
**Consensus Types** (`consensus/types/`)
- Core Ethereum consensus data structures (BeaconState, BeaconBlock, etc.)
- Ethereum specification implementations for different networks (mainnet, gnosis)
- SSZ encoding/decoding and state transition primitives
**Storage** (`beacon_node/store/`)
- Hot/cold database architecture for efficient beacon chain storage
- Supports multiple backends (LevelDB, RocksDB, REDB)
- Handles state pruning and historical data management
**Networking** (`beacon_node/lighthouse_network/`, `beacon_node/network/`)
- Libp2p-based P2P networking stack
- Gossipsub for message propagation
- Discovery v5 for peer discovery
- Request/response protocols for sync
**Fork Choice** (`consensus/fork_choice/`, `consensus/proto_array/`)
- Implements Ethereum's fork choice algorithm (proto-array)
- Manages chain reorganizations and finality
**Execution Layer Integration** (`beacon_node/execution_layer/`)
- Interfaces with execution clients
- Retrieves payloads from local execution layer or external block builders
- Handles payload validation and builder integration
**Slasher** (`slasher/`)
- Optional slashing detection service
- Supports LMDB, MDBX, and REDB database backends
- Can be enabled with `--slasher` flag
@@ -120,6 +132,7 @@ Lighthouse is a modular Ethereum consensus client with two main components:
## Common Review Standards
### CI/Testing Requirements
- All checks must pass before merge
- Test coverage expected for significant changes
- Flaky tests are actively addressed and fixed
@@ -127,12 +140,14 @@ Lighthouse is a modular Ethereum consensus client with two main components:
- `beacon_chain` and `http_api` tests support fork-specific testing using `FORK_NAME` env var when `beacon_chain/fork_from_env` feature is enabled
### Code Quality Standards
- Clippy warnings must be fixed promptly (multiple PRs show this pattern)
- Code formatting with `cargo fmt` enforced
- Must run `cargo sort` when adding dependencies - dependency order is enforced on CI
- Performance considerations for hot paths
### Documentation and Context
- PRs require clear descriptions of what and why
- Breaking changes need migration documentation
- API changes require documentation updates
@@ -140,6 +155,7 @@ Lighthouse is a modular Ethereum consensus client with two main components:
- Comments appreciated for complex logic
### Security and Safety
- Careful review of consensus-critical code paths
- Error handling patterns must be comprehensive
- Input validation for external data
@@ -147,6 +163,7 @@ Lighthouse is a modular Ethereum consensus client with two main components:
## Development Patterns and Best Practices
### Panics and Error Handling
- **Panics should be avoided at all costs**
- Always prefer returning a `Result` or `Option` over causing a panic (e.g., prefer `array.get(1)?` over `array[1]`)
- Avoid `expect` or `unwrap` at runtime - only acceptable during startup when validating CLI flags or configurations
@@ -154,18 +171,22 @@ Lighthouse is a modular Ethereum consensus client with two main components:
- Use proper error handling with `Result` types and graceful error propagation
### Rayon Usage
- Avoid using the rayon global thread pool as it results in CPU oversubscription when the beacon processor has fully allocated all CPUs to workers
- Use scoped rayon pools started by beacon processor for computational intensive tasks
### Locks
- Take great care to avoid deadlocks when working with fork choice locks - seek detailed review ([reference](beacon_node/beacon_chain/src/canonical_head.rs:9))
- Keep lock scopes as narrow as possible to avoid blocking fast-responding functions like the networking stack
### Async Patterns
- Avoid blocking computations in async tasks
- Spawn a blocking task instead for CPU-intensive work
### Tracing
- Design spans carefully and avoid overuse of spans just to add context data to events
- Avoid using spans on simple getter methods as it can result in performance overhead
- Be cautious of span explosion with recursive functions
@@ -173,14 +194,17 @@ Lighthouse is a modular Ethereum consensus client with two main components:
- Avoid using `span.enter()` or `span.entered()` in async tasks
### Database
- Maintain schema continuity on `unstable` branch
- Database migrations must be backward compatible
### Consensus Crate
- Use safe math methods like `saturating_xxx` or `checked_xxx`
- Critical that this crate behaves deterministically and MUST not have undefined behavior
### Testing Patterns
- **Use appropriate test types for the right scenarios**:
- **Unit tests** for single component edge cases and isolated logic
- **Integration tests** using [`BeaconChainHarness`](beacon_node/beacon_chain/src/test_utils.rs:668) for end-to-end workflows
@@ -204,6 +228,7 @@ Lighthouse is a modular Ethereum consensus client with two main components:
- See [`scripts/local_testnet/README.md`](scripts/local_testnet/README.md) for setup instructions
### TODOs and Comments
- All `TODO` statements must be accompanied by a GitHub issue link
- Prefer line (`//`) comments to block comments (`/* ... */`)
- Use doc comments (`///`) before attributes for public items
@@ -211,7 +236,9 @@ Lighthouse is a modular Ethereum consensus client with two main components:
- Provide examples in doc comments for public APIs when helpful
## Logging Guidelines
Use appropriate log levels for different scenarios:
- **`crit`**: Critical issues with major impact to Lighthouse functionality - Lighthouse may not function correctly without resolving. Needs immediate attention.
- **`error`**: Error cases that may have moderate impact to Lighthouse functionality. Expect to receive reports from users for this level.
- **`warn`**: Unexpected code paths that don't have major impact - fully recoverable. Expect user reports if excessive warning logs occur.
@@ -221,6 +248,7 @@ Use appropriate log levels for different scenarios:
## Code Examples
### Safe Math in Consensus Crate
```rust
// ❌ Avoid - could panic
let result = a + b;
@@ -234,6 +262,7 @@ let result = a.safe_add(b)?;
```
### Panics and Error Handling
```rust
// ❌ Avoid - could panic at runtime
let value = some_result.unwrap();
@@ -253,6 +282,7 @@ let item = array.get(1).expect("Array always has at least 2 elements due to vali
```
### TODO Format
```rust
pub fn my_function(&mut self, _something: &[u8]) -> Result<String, Error> {
// TODO: Implement proper validation here
@@ -261,6 +291,7 @@ pub fn my_function(&mut self, _something: &[u8]) -> Result<String, Error> {
```
### Async Task Spawning for Blocking Work
```rust
// ❌ Avoid - blocking in async context
async fn some_handler() {
@@ -276,6 +307,7 @@ async fn some_handler() {
```
### Tracing Span Usage
```rust
// ❌ Avoid - span on simple getter
#[instrument]
@@ -291,9 +323,10 @@ async fn process_block(&self, block: Block) -> Result<(), Error> {
```
## Build and Development Notes
- Full builds and tests take 5+ minutes - use large timeouts (300s+) for any `cargo build`, `cargo test`, or `make` commands
- Full builds and tests take 5+ minutes - use large timeouts (300s+) for any `cargo build`, `cargo nextest`, or `make` commands
- Use `cargo check` for faster iteration during development and always run after code changes
- Prefer targeted package tests (`cargo nextest run -p <package>`) and individual tests over full test suite when debugging specific issues
- Use `cargo fmt --all && make lint-fix` to format code and fix linting issues once a task is complete
- Prefer targeted package tests (`cargo test -p <package>`) and individual tests over full test suite when debugging specific issues
- Always understand the broader codebase patterns before making changes
- Minimum Supported Rust Version (MSRV) is documented in `lighthouse/Cargo.toml` - ensure Rust version meets or exceeds this requirement
- Minimum Supported Rust Version (MSRV) is documented in `lighthouse/Cargo.toml` - ensure Rust version meets or exceeds this requirement