# eth_multicall test suite tutorial This is a guide on how to write test cases for eth_multicall and execute them. There are several pieces to this puzzle: - Tests are implemented in [rpctestgen](https://github.com/lightclient/rpctestgen) which outputs IO (Json-rpc request response sequence) artefacts. - `.io` files are copied over to Hive simulation `rpc-compat` - Then we can execute the tests against a client using Hive CLI Now let's go over them one by one. ## Rpctestgen This is a tool written in Go. It creates a chain from code and starts a Geth node with that. The test cases describe the request to be made which is then sent to geth to fill in the response. The test case can do validation of the response and optionally fail to generate the artefact. There are a few basic test cases in this branch: https://github.com/s1na/rpctestgen/tree/multicall that can act as a sample for writing new ones. First, clone the repo at this branch: ```terminal git clone --branch multicall https://github.com/s1na/rpctestgen.git cd rpctestgen ``` To fill in the tests you need to have a geth binary with multicall support. ```terminal git clone --branch multicall --depth 5 https://github.com/s1na/go-ethereum.git cd go-ethereum make geth ``` This will put the binary at `/path/go-ethereum/build/bin/geth`. Run: ```terminal PATH=$PATH:/path/to/geth/binary make fill ``` The output files are written in the `tests/` dir. ## Hive suite rpc-compat ### Setup simulator Clone Hive. Copy the generated tests to the rpc-compat simulation (under `simulators/ethereum/rpc-compat/tests`). Then you need to modify the Docker file located at `simulators/ethereum/rpc-compat/Dockerfile` to use the tests in that directory instead of fetching them from `execution-apis` repo. Apply this patch (basically comment the `git clone` and uncomment `ADD tests /execution-apis/tests`). ```patch diff --git a/simulators/ethereum/rpc-compat/Dockerfile b/simulators/ethereum/rpc-compat/Dockerfile index d338a2c..79d6a53 100644 --- a/simulators/ethereum/rpc-compat/Dockerfile +++ b/simulators/ethereum/rpc-compat/Dockerfile @@ -3,11 +3,11 @@ FROM golang:1-alpine as builder RUN apk add --update git ca-certificates gcc musl-dev linux-headers # Clone the tests repo. -RUN git clone --depth 1 https://github.com/ethereum/execution-apis.git /execution-apis +#RUN git clone --depth 1 https://github.com/ethereum/execution-apis.git /execution-apis # To run local tests, copy the directory into the same as the simulator and # uncomment the line below -# ADD tests /execution-apis/tests +ADD tests /execution-apis/tests # Build the simulator executable. ADD . /source ``` ### Execute There is a few ways to do this, depending on whether you'd want to run against a published docker container of the client, a git branch, or source code locally. Each client in Hive has three docker files, one for each of this approaches. Here I highlight how to do this against a git branch of geth. Create a `clients.yaml` file: ```yaml= - client: go-ethereum dockerfile: git build_args: github: s1na/go-ethereum tag: multicall ``` then run: ```bash go build . # build hive ./hive --sim rpc-compat --client-file clients.yaml ``` This should run the whole rpc-compat test suite (which we added to the `tests` directory) against the clients configured in `clients.yaml`. If you needed more verbosity you can add `--docker.output` flag to the hive command.