feat(test-consume): initial implementation of the enginex simulator

[danceratopz]

🗒️ Description

Adds a consume enginex simulator that reuses client instances across tests sharing the same pre-allocation state. This simulator significantly reduces test execution time compared to consume engine by avoiding per-test client startup overhead.

Includes basic pytest-xdist support via --dist=loadgroup, with further optimizations planned in subsequent PRs.

Architecture

The enginex simulator groups tests by pre_hash (hash of genesis + pre-state). Tests in the same group run against a single client instance instead of starting/stopping per test.

New Files

File	Purpose
simulators/enginex/conftest.py	Client fixture with reuse logic, test sorting by group
simulators/multi_test_client.py	MultiTestClientManager for client lifecycle
simulators/helpers/test_tracker.py	Tracks test completion per group for cleanup

Modified

File	Change
consume.py	Adds xdist_group marker based on pre_hash for enginex fixtures
test_via_engine.py	Unified test logic supporting both engine and enginex modes
pytest_hive.py	Adds shared_hive_test fixture for cross-test client sharing
processors.py	Adds --dist=loadgroup default for enginex with xdist

Execution Flow

1. Collection: pytest_collection_modifyitems counts tests per group, sorts by pre_hash.
2. First test in group: Starts client, registers with manager.
3. Subsequent tests: Reuses existing client (skips FCU to keep at genesis).
4. Last test in group: mark_test_completed triggers client shutdown.
5. Session end: Cleanup any remaining clients.

Fixture Chain

flowchart LR
    subgraph "Per Group (cached)"
        PAG[pre_alloc_group] --> CG[client_genesis]
        PAG --> GH[genesis_header]
        CG --> BG[buffered_genesis]
        BG --> CF[client_files]
    end

    subgraph "Client (reused)"
        CF --> C[client]
        C --> ETH[eth_rpc]
        C --> ENG[engine_rpc]
    end

    subgraph "Per Test"
        TC[test_case] --> F[fixture]
        F --> P[payloads]
    end

    subgraph "Test Execution"
        GH --> TEST[test_blockchain_via_engine]
        ENG --> TEST
        P --> TEST
    end

Loading

Testing

For testing, use this custom release which keeps tests marked as @pytest.mark.slow in the same pre-alloc group as their non-slow counterparts (greatly reduces the number of groups):

https://github.com/danceratopz/execution-specs/releases/tag/v0.1.0a1

# Dev mode (requires hive --dev backend)
uv run consume enginex --input=https://github.com/danceratopz/execution-specs/releases/download/v0.1.0a1/fixtures.tar.gz -v -s -k "/shanghai/ and (fork_shanghai or fork_cancun) and push0"

# With parallelism
uv run consume enginex --input=https://github.com/danceratopz/execution-specs/releases/download/v0.1.0a1/fixtures.tar.gz -n 4 -k "(fork_shanghai or fork_cancun) and push0"

🔗 Related Issues or PRs

N/A.

✅ Checklist

• All: Ran fast tox checks to avoid unnecessary CI fails, see also Code Standards and Enabling Pre-commit Checks:

  uvx tox -e static

• All: PR title adheres to the repo standard - it will be used as the squash commit message and should start type(scope):.
• [ ] All: Considered adding an entry to CHANGELOG.md. skipped
• All: Considered updating the online docs in the ./docs/ directory.
• All: Set appropriate labels for the changes (only maintainers can apply labels).

Cute Animal Picture

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.33%. Comparing base (d618e52) to head (6fe382c).

Additional details and impacted files

@@               Coverage Diff                @@
##           forks/amsterdam    #1964   +/-   ##
================================================
  Coverage            86.33%   86.33%           
================================================
  Files                  538      538           
  Lines                34557    34557           
  Branches              3222     3222           
================================================
  Hits                 29835    29835           
  Misses                4148     4148           
  Partials               574      574           

Flag	Coverage Δ
unittests	86.33% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.