Optimism Test Book

Documentation for the ethereum-optimism/tests repository.

Introduction

ethereum-optimsim/tests is a collection of test fixtures for testing OP Stack execution and derivation. Alongside test fixtures, the ethereum-optimism/tests repository contains CLI tools for generating new test fixtures written in Rust with the goal of making test fixture generation simple.

It is built and maintained by members of OP Labs as well as open source contributors, and is licensed under the MIT License.

ethereum-optimsim/tests is comparible to the ethereum-tests repository for ethereum. The aim of ethereum-optimism/tests is then to provide a set of standard tests for all OP Stack client and node software to use for testing. In order to run these test fixtures against various execution and derivation implementations, each instance must implement their own test runner. For example, similar to how revm defines a test runner, revme, to run the ethereum-tests against its ethereum execution implementation.

In this book, we will break down the format of test fixtures, how to approach generating new test fixtures, and how to implement custom runners. Much of this book is specific to Rust, but is intentionally portable to other languages over the JSON interface.

Development Status

ethereum-optimism/tests is currently in active development, and is not yet ready for use in production.

Contributing

Contributors are welcome! Please see the contributing guide for more information.

Test Fixture Format

There are two primary types of test fixtures: Derivation and Execution. Test fixtures are static JSON files that live in the [fixtures][fixtures] directory.

Execution Test Fixtures

Execution test fixtures live inside the fixtures/execution/ directory. Each JSON file in this directory contains the JSON-serialized [ExecutionFixture][exec-fixture] object which is defined in Rust in the [op-test-vectors][op-test-vectors] crate.

The ExecutionFixture holds everything needed to test execution of the OP Stack. It's composed of the following.

  • An ExecutionEnvironment, which is used to setup the execution client's environment.
  • An initial set of addresses and their states, also called the "pre-state".
  • A final set of addresses and their states, also called the "post-state".
  • A list of transactions to execute in the environment.
  • The result of executing all the transactions.

Derivation Test Fixtures

// TODO

{{#include ../links.md}}