# ethereum/execution-spec-tests architecture

> Architecture diagram of the GitHub repository ethereum/execution-spec-tests, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ethereum/execution-spec-tests
- Repository: https://github.com/ethereum/execution-spec-tests

## Overview

##### Project Type and Purpose
- This is a Python‐based test-fixture generation framework (an open-source tool) for Ethereum execution clients.
- It collects Python test cases, invokes external “t8n” executables (EVM transition tools like `evm t8n`, `evmone-t8n`, etc.), and outputs JSON fixtures that clients or the Ethereum Hive integration framework can consume.

##### High-Level Components
a. Command-Line Interface (CLI)
- src/cli: Implements `fill`, `make`, `check_fixtures`, `order_fixtures`, and other entry-points.
- Uses `uv` (external tool) to manage Python virtual environments.
b. Core Engine Modules
- src/ethereum_test_base_types, _fixtures, _execution, _forks, _rpc, _specs, _tools, _types, _vm: Organize functionality to parse tests, generate intermediate representations, drive the t8n tool invocation, and assemble the JSON output.
c. Pytest Plugins
- src/pytest_plugins: Provide custom pytest commands (`fill`, `consume`, `execute`, `filler`, `forks`, etc.) that tie test discovery and execution to fixture generation.
d. Configuration & Orchestration
- src/config and .github/configs: Define external tool versions (EIPs), YAML templates, environment variables, and CI workflows.
e. External Dependencies & Services
- Transition tools (e.g., `evm t8n`, `evmone-t8n`, `ethereum-spec-evm`, `solc`) invoked by the framework.
- GitHub Actions workflows for CI, CD, and documentation deployment.
f. Output Consumers
- JSON fixtures under `fixtures/` are consumed by client test frameworks (ethereum/hive) or other EVM clients.

##### Relationships & Data Flows
- The user invokes a CLI command (`uv run fill …`).
- CLI parses arguments and loads configuration (src/config).
- Pytest plugin hooks into pytest to discover Python test cases (src/cli and src/ethereum_test_* modules).
- For each test, the framework calls the appropriate external t8n executable with test data.
- The t8n tool returns execution results; the framework then formats them into JSON fixtures.
- Fixtures are written to disk (`fixtures/...`).
- Downstream, those JSON files flow into client test harnesses or the Hive framework.

##### Architectural Patterns & Principles
- Modular packaging: Each major feature has its own Python namespace (`ethereum_test_*`).
- Plugin architecture: Custom pytest plugins extend pytest for test discovery and fixture generation.
- External tool abstraction: Adapters in `src/ethereum_clis` abstract over different t8n implementations.
- Configuration-as-code: YAML templates and Python config modules drive versions and environment setup.
- Separation of concerns: CLI layer, core engine, plugins, adapters, and configuration are clearly separated.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI & Entry Points
    subgraph "CLI & Entry Points"
        CLI["CLI & Entry Points"]:::internal
    end
    click CLI "https://github.com/ethereum/execution-spec-tests/tree/main/src/cli"

    %% Configuration & CI
    subgraph "Configuration & CI"
        ConfigModules["Configuration Modules"]:::config
        GitHubConfigs["GitHub & CI Configs"]:::config
        GitHubActions["GitHub Actions Workflows"]:::config
    end
    click ConfigModules "https://github.com/ethereum/execution-spec-tests/tree/main/src/config"
    click GitHubConfigs "https://github.com/ethereum/execution-spec-tests/tree/main/.github/configs"
    click GitHubActions "https://github.com/ethereum/execution-spec-tests/tree/main/.github/actions"

    %% Core Engine Modules
    subgraph "Core Engine Modules"
        BaseTypes["Base Types"]:::internal
        Exceptions["Exceptions"]:::internal
        ExecEngine["Execution Engine"]:::internal
        FixtureGen["Fixture Generation"]:::internal
        Forks["Fork Definitions"]:::internal
        RPC["RPC Interfaces"]:::internal
        Specs["Test Specs"]:::internal
        Tools["Tools & Templates"]:::internal
        Types["Data Types"]:::internal
        VM["VM Utilities"]:::internal
    end
    click BaseTypes "https://github.com/ethereum/execution-spec-tests/tree/main/src/ethereum_test_base_types"
    click Exceptions "https://github.com/ethereum/execution-spec-tests/tree/main/src/ethereum_test_exceptions"
    click ExecEngine "https://github.com/ethereum/execution-spec-tests/tree/main/src/ethereum_test_execution"
    click FixtureGen "https://github.com/ethereum/execution-spec-tests/tree/main/src/ethereum_test_fixtures"
    click Forks "https://github.com/ethereum/execution-spec-tests/tree/main/src/ethereum_test_forks"
    click RPC "https://github.com/ethereum/execution-spec-tests/tree/main/src/ethereum_test_rpc"
    click Specs "https://github.com/ethereum/execution-spec-tests/tree/main/src/ethereum_test_specs"
    click Tools "https://github.com/ethereum/execution-spec-tests/tree/main/src/ethereum_test_tools"
    click Types "https://github.com/ethereum/execution-spec-tests/tree/main/src/ethereum_test_types"
    click VM "https://github.com/ethereum/execution-spec-tests/tree/main/src/ethereum_test_vm"

    %% Pytest Plugins
    subgraph "Pytest Plugins"
        Plugins["Pytest Plugins"]:::internal
    end
    click Plugins "https://github.com/ethereum/execution-spec-tests/tree/main/src/pytest_plugins"

    %% External T8n Adapters
    subgraph "Adapters"
        Adapters["External T8n Adapters"]:::internal
    end
    click Adapters "https://github.com/ethereum/execution-spec-tests/tree/main/src/ethereum_clis"

    %% External Tools
    subgraph "External T8n Tools"
        extEvmt8n[(evm t8n)]:::external
        extEvmone[(evmone-t8n)]:::external
        extSpecEvm[(ethereum-spec-evm)]:::external
        extSolc[(solc)]:::external
    end

    %% Fixtures Output
    Fixtures["Fixtures Output (JSON)"]:::artifact
    click Fixtures "https://github.com/ethereum/execution-spec-tests/tree/main/fixtures/"

    %% Output Consumers
    subgraph "Output Consumers"
        Hive["Hive Framework"]:::external
        Clients["Client Test Harness"]:::external
    end

    %% Data Flows
    CLI -->|"loads config"| ConfigModules
    CLI -->|"invoke core"| ExecEngine
    Plugins -->|"hook into pytest"| ExecEngine
    ExecEngine -->|"generate fixtures"| FixtureGen
    ExecEngine -->|"invoke adapters"| Adapters
    Adapters -->|"invoke"| extEvmt8n
    Adapters -->|"invoke"| extEvmone
    Adapters -->|"invoke"| extSpecEvm
    Adapters -->|"invoke"| extSolc
    extEvmt8n -->|"results"| ExecEngine
    extEvmone -->|"results"| ExecEngine
    extSpecEvm -->|"results"| ExecEngine
    extSolc -->|"results"| ExecEngine
    FixtureGen -->|"write JSON"| Fixtures
    Fixtures -->|"consume"| Hive
    Fixtures -->|"consume"| Clients
    GitHubActions -->|"runs workflows on"| CLI

    %% Styling
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef config fill:#90EE90,stroke:#333,stroke-width:1px
    classDef artifact fill:#D3D3D3,stroke:#333,stroke-width:1px
```
