Development Environment

Most Lighthouse developers work on Linux or MacOS, however Windows should still be suitable.

First, follow the Installation Guide to install Lighthouse. This will install Lighthouse to your PATH, which is not particularly useful for development but still a good way to ensure you have the base dependencies.

The additional requirements for developers are:

cmake. Used by some dependencies. See Installation Guide for more info.
java 17 runtime. 17 is the minimum, used by web3signer_tests.

Using `make`

Commands to run the test suite are available via the Makefile in the project root for the benefit of CI/CD. We list some of these commands below so you can run them locally and avoid CI failures:

$ make cargo-fmt: (fast) runs a Rust code formatting check.
$ make lint: (fast) runs a Rust code linter.
$ make test: (medium) runs unit tests across the whole project using nextest.
$ make test-ef: (medium) runs the Ethereum Foundation test vectors.
$ make test-full: (slow) runs the full test suite (including all previous commands). This is approximately everything that is required to pass CI.

The lighthouse test suite is quite extensive, running the whole suite may take 30+ minutes.

Testing

Lighthouse uses cargo nextest for unit and integration tests. Nextest provides better parallelization and is used by CI. For example, to test the safe_arith crate run:

$ cd consensus/safe_arith
$ cargo nextest run
    Finished test [unoptimized + debuginfo] target(s) in 0.43s
    ------------
     Nextest run ID: 01234567-89ab-cdef-0123-456789abcdef
     Starting 8 tests across 1 binary
        PASS [   0.001s] safe_arith tests::test_safe_add_u64
        PASS [   0.001s] safe_arith tests::test_safe_mul_u64
        <snip>
    ------------
     Summary [ 0.012s] 8 tests run: 8 passed, 0 skipped

Alternatively, since lighthouse is a cargo workspace you can use -p safe_arith where safe_arith is the package name as defined in /consensus/safe_arith/Cargo.toml:

$ head -2 consensus/safe_arith/Cargo.toml
[package]
name = "safe_arith"
$ cargo nextest run -p safe_arith
    Finished test [unoptimized + debuginfo] target(s) in 0.43s
    ------------
     Nextest run ID: 01234567-89ab-cdef-0123-456789abcdef
     Starting 8 tests across 1 binary
        PASS [   0.001s] safe_arith tests::test_safe_add_u64
        PASS [   0.001s] safe_arith tests::test_safe_mul_u64
        <snip>
    ------------
     Summary [ 0.012s] 8 tests run: 8 passed, 0 skipped

Integration tests

Due to the size and complexity of the test suite, Lighthouse uses a pattern that differs from how integration tests are usually defined. This pattern helps manage large test suites more effectively and ensures tests only run in release mode to avoid stack overflow issues.

The “main pattern”

For packages with integration tests that require more than one file, Lighthouse uses the following structure:

A main.rs file is defined at package/tests/main.rs that declares other test files as modules

In package/Cargo.toml, integration tests are explicitly configured:

[package]
autotests = false

[[test]]
name = "package_tests"
path = "tests/main.rs"

Rust Analyzer configuration

This pattern, combined with #![cfg(not(debug_assertions))] directives in test files (which prevent tests from running in debug mode), causes Rust Analyzer to not provide IDE services like autocomplete and error checking in integration test files by default.

To enable IDE support for these test files, configure Rust Analyzer to disable debug assertions. For VSCode users, this is already configured in the repository’s .vscode/settings.json file:

{
    "rust-analyzer.cargo.cfgs": [
        "!debug_assertions"
    ]
}

Logging in tests

By default, when running tests, the logs will not be printed if the tests passed. For example, to run the tests for the beacon_chain package:

cargo test --release  -p beacon_chain

To always show the logs, run the tests with -- --nocapture.

cargo test --release  -p beacon_chain -- --nocapture

By default, the log shown is DEBUG level. This can be overridden using the environment variable RUST_LOG. For example, to only show logs with INFO level and above:

RUST_LOG=info cargo test --release  -p beacon_chain -- --nocapture

To only show logs from the beacon_chain crate and with INFO level and above:

RUST_LOG=beacon_chain=info cargo test --release  -p beacon_chain -- --nocapture

Consensus Spec Tests

The ethereum/consensus-spec-tests repository contains a large set of tests that verify Lighthouse behaviour against the Ethereum Foundation specifications.

These tests are quite large (100’s of MB) so they’re only downloaded if you run $ make test-ef (or anything that runs it). You may want to avoid downloading these tests if you’re on a slow or metered Internet connection. CI will require them to pass, though.

Local Testnets

During development and testing it can be useful to start a small, local testnet.

The scripts/local_testnet/ directory contains several scripts and a README that should make this process easy.

Keyboard shortcuts

Lighthouse Book