Skip to content

Consume Simulators

The engine, rlp and wirex simulators test clients by delivering blocks through different interfaces. These simulators run within the Hive testing framework to provide containerized, isolated testing environments.

For your first run, start with Hive setup, then choose how to run the simulators:

  • Run tests or reproduce a dashboard failure: use published images with ./hive --sim. Hive runs both the simulator and clients in containers.
  • Run locally generated fixtures or debug interactively: use development mode with ./hive --dev. Hive manages the clients while you run uv run consume from your local checkout.

Run with published images

Start with Run a Simulator from Images to run consume tests through Hive. Use the tag guide to select a mainnet release, a devnet or a nightly fill, and the image reference to choose a simulator and fixture format.

For example, run the latest published mainnet release with:

./hive --sim consume-engine --client go-ethereum

Hive accepts the short simulator name. The image contains the fixtures and framework, so you do not need to install consume separately.

To reproduce a dashboard failure, match its simulator image, client version and configuration, and test selection. A release tag always runs the same image. For latest or a devnet channel, which may have moved since the dashboard run, follow Reproduce a run exactly to pin the simulator image digest. Use Select a single test to filter the failing test.

Once you can reproduce the failure, switch to development mode if you need to inspect Python state or edit the simulator. You can also build images locally to test changes in containers.

Debug in development mode

Development mode lets you run against locally generated fixtures directly, without building or publishing an image. It also runs the simulator from your checkout, so edits take effect on the next run and you can use a Python debugger. Install the testing tools first, then follow Hive development mode for platform-specific setup.

On Linux, start Hive from its checkout and leave it running:

./hive --dev --client go-ethereum

In another terminal, from your execution-specs checkout, connect to Hive and run the simulator against fixtures you generated in ./fixtures:

export HIVE_SIMULATOR=http://127.0.0.1:3000
uv run consume engine --input ./fixtures \
    --sim.limit ".*test_name.*" --pdb

Use the familiar Hive --sim.limit flag to select tests by regular expression. Replace test_name with the name of the test you are debugging; the surrounding .* matches the rest of its test ID. Regular pytest flags are also available: -k test_name is an alternative filter, and --pdb opens the debugger on failure. See Useful Pytest Options for more options.

Set --input to your local fixture directory, or use --input tests@v20.0.2 to debug against a published release. See Fixture Inputs for supported inputs. Simulator code comes from your checkout; the published image's tag no longer selects it.

Command Syntax

uv run consume <engine|rlp|wirex> [OPTIONS]

Further development references

A separate hive simulator build-block is also fixture-driven but tests the client's producer-side path via the testing_buildBlockV1 engine-API testing-namespace endpoint, rather than the consumer-side import path that the simulators above exercise.