Testing Lighthouse

Lighthouse includes many tests which ensure the correctness of different components. This page provides a brief overview of how to interact with Lighthouse's tests and how to add to them.

Running tests

We run most of the tests with optimisations enabled. Lighthouse's BLS crypto is very slow without compiler optimisations, and some of the tests take far too long to run in debug mode. Usually you should use the --release flag when running tests:

cargo test --release

To run tests for a single crate, use -p and the crate name:

cargo test --release -p beacon_chain

To run a single test or a handful, provide a pattern to the test binary:

cargo test --release -p beacon_chain -- full_participation_no_skips

Unit tests

If the functionality being tested is self-contained and doesn't require complex setup, you will often find it tested in a unit test inside the crate.

Examples of crates with this kind of testing include:

• bls
• lru_cache
• slasher
• merkle_proof

Many of our external packages also contain tests of this kind:

• ethereum_ssz
• tree_hash
• milhouse

Beacon chain tests

Many tests make use of the BeaconChainHarness type which provides functionality for building out a chain and making assertions about it.

The BeaconChainHarness embeds a BeaconChain and is most useful for testing logic at the level of the BeaconChain or below, e.g. consensus, fork_choice. The BeaconChainHarness does not include a networking stack, so for testing networking you will be better served by other tests.

The canonical examples of tests using the BeaconChainHarness are the ones in beacon_node/beacon_chain/tests. You can often copy an existing test and tweak it to your needs.

Network tests

The main networking crates include tests

See for example:

• Lighthouse RPC and common integration tests
• Enr
• Discv5 (and tests within each module)
• Gossipsub

Property-based tests

We use both quickcheck (historical) and proptest (preferred) for random property tests:

• discv5 uses quickcheck here.
• milhouse uses proptest extensively.

Fuzzing

We maintain some fuzzing harnesses privately, while others are part of the crate they test:

• milhouse fuzzing targets

Consensus specification tests

Some of the most important test vectors for Lighthouse are the test cases generated from the consensus-specs reference implementation.

The runners for these tests are continually updated as new hard forks are implemented and new tests are released. They live in testing/ef_tests.

Simulator

We have a binary that simulates a local testnet to ensure consistency across a handful of nodes. It might be useful to run when creating malicious nodes. The code can be found here and documentation within the CLI

Local Testnet

We have a set of scripts that enable the quick-start of local testnets to perform testing and inspection on local nodes. If you need to perform a local testnet to then attack locally, please see the information for the testnet scripts here

Integration tests

TODO

Logging

Lighthouse's logging crate includes a test_logger feature which causes logs to be printed to stderr when test cases are running, rather than being silently swallowed. It works best when running a single test at a time so that output from different tests doesn't get interleaved:

cargo test --release -p beacon_chain --features logging/test_logger -- full_participation_no_skips