Project maintained by kurtosis-tech Hosted on GitHub Pages — Theme by mattgraham

Kurtosis Architecture


Every test in existence goes through four phases:

  1. Setup
  2. Perturbation
  3. Validation
  4. Teardown

In unit testing, this usually looks like:

  1. Instantiate the object to test and mock all surrounding objects
  2. Execute the functions being tested
  3. Assert the expected result
  4. Garbage collect all objects

Engineers have well-established unit-testing tools for each phase, so developers write many.

When the component being tested is the entire distributed system however, things become seriously difficult: where do we run the test nodes? How do we initialize their config & data files? Where do we run the test logic, and how does it talk to the system? How do we ensure the network is cleaned up after the test is done?

These are challenging questions, and in our experience teams tend to go one of two ways: write their own automation framework from scratch, or skip sandboxed networks altogether and run a single long-lived testnet that everyone uses. The latter is error-prone and costly to maintain while the former is bespoke and costly to write. Ideally, teams would have a platform that automates the heavy lifting of each phase so they can focus on writing tests. This is Kurtosis.


To see how Kurtosis resolves the distributed system testing challenges, here’s an example diagram of a Kurtosis testsuite for Microservice X that contains two tests:

This architecture has the following components:

The test phases proceed in the following order for each test:

  1. Setup:
    1. The CLI creates a new Docker subnet to contain the Kurtosis API container, testsuite container, and testnet services
    2. The API container and testsuite containers are launched
    3. As part of launch, the Kurtosis client library instructs the API container what the testnet looks like
    4. The API container instantiates the testnet as instructed
  2. Perturbation: The test, running inside the testsuite container, makes calls against the network
  3. Validation: The test asserts the expected responses
  4. Teardown:
    1. The test completes and reports its status back to the CLI
    2. The API container stops the testnet containers
    3. The API container and testsuite container exit
    4. The CLI tears down the Docker subnet created for the test

Key features:

Back to index