# ethereum/tests architecture

> Architecture diagram of the GitHub repository ethereum/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/tests
- Repository: https://github.com/ethereum/tests

## Overview

##### Project type and purpose
- This is an open-source test suite (“Ethereum Execution Tests (EVM)”) not a typical application. It provides canonical test vectors (JSON, YAML) for EVM behavior, plus “fillers” that generate or transform tests, ansible scripts for provisioning, and documentation. Clients (Geth, Parity, etc.) consume the test data via the retesteth test harness.

##### File structure
- Top-level directories:
- BasicTests, BlockchainTests, TransactionTests, EOFTests, RLPTests, PoWTests, etc. → static test specs
- src/…Filler → scripts and templates (JavaScript/Node.js, YAML) to generate test vectors
- JSONSchema → defines schemas for validating test JSON
- ansible/ → infrastructure-as-code for spinning up environments (Docker, EC2) to run tests
- docs/ → Sphinx/RST docs about test formats, fillers, usage
- Config files: requirements.txt (Python deps), .travis.yml (CI), .gitmodules, Vagrantfile.

##### README for additional insights
- The repo is consumed by a variety of client implementations via retesteth.
- Tests are version-tagged; the “src” fillers auto-generate canonical tests, so one must maintain both raw and generated tests.
- Ansible + Vagrant + Docker are used to run retesteth across multiple clients and collect stats.

##### Elements
- Clear component labels (e.g., “Filler Generator”, “Schema Validator”, “retesteth”)
- “Templates → Filler → Test JSON”
- “Test JSON → retesteth → Ethereum Client”
- “Client Results → Hive → Web UI”

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Source Code"
        Repo["Test Repository (Git)"]:::code
        CI["CI Configuration (.travis.yml, requirements.txt)"]:::code
    end

    subgraph "Generation Pipeline"
        Filler["Filler Generator"]:::code
        Templates["Templates for Custom Fillers"]:::code
        Repo --> Filler
        Filler --> Templates
    end

    subgraph "Static Test Suites"
        Tests["JSON/YAML Test Suites"]:::data
        Templates --> Tests
    end

    subgraph "Validation"
        Schema["JSON Schema Validator"]:::code
        Tests --> Schema
    end

    subgraph "Execution"
        RET["retesteth (Test Harness)"]:::code
        Clients["Ethereum Clients (Geth, Parity, etc.)"]:::external
        Schema --> RET
        RET --> Clients
    end

    subgraph "Infrastructure Provisioning"
        Infra["Infrastructure Provisioner (Ansible/Vagrant)"]:::infra
        Infra --> RET
        Infra --> Clients
        CI --> Infra
    end

    subgraph "Results Aggregation"
        Hive["Results Aggregator (hive)"]:::external
        UI["Web UI"]:::external
        Clients --> Hive
        Hive --> UI
    end

    subgraph "Documentation"
        Docs["Documentation Portal (Sphinx/RST)"]:::code
        Repo --> Docs
    end

    click Repo "https://github.com/ethereum/tests/blob/develop/.gitignore"
    click Filler "https://github.com/ethereum/tests/tree/develop/src/BlockchainTestsFiller/"
    click Templates "https://github.com/ethereum/tests/tree/develop/src/Templates/"
    click Tests "https://github.com/ethereum/tests/tree/develop/BasicTests/"
    click Schema "https://github.com/ethereum/tests/tree/develop/JSONSchema/"
    click Infra "https://github.com/ethereum/tests/tree/develop/ansible/"
    click Docs "https://github.com/ethereum/tests/tree/develop/docs/"
    click CI "https://github.com/ethereum/tests/blob/develop/.travis.yml"

    classDef code fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef data fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef infra fill:#DDA0DD,stroke:#333,stroke-width:1px;
```
