Contains the API for a testsuite container, and a library that makes writing those testsuites easier

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

Test SDK Documentation

The Kurtosis testing SDK exists in multiple languages and maintaining in-code comments for each of these is prohibitively expensive. This page provides the canonical reference for testing SDK classes and methods. For documentation on the client (which is used to manipulate the testnet), see the Kurtosis Client documentation.

Found a bug? File it on the repo!


Implementations of this interface are responsible for initializing the user-defined testsuite object for Kurtosis.

setLogLevel(String logLevelStr)

This function should configure the logging framework that the testsuite uses, since Kurtosis won’t know what logging framework the testsuite uses or how to configure it.


parseParamsAndCreateSuite(String paramsJsonStr) -> TestSuite

This function should parse the custom testsuite parameters JSON and create an instance of the user’s implementation of the TestSuite interface.



An instance of the user’s custom TestSuite implementation.

Test<N extends Network>

This interface represents a test that will be executed against a test network. You should create one implementation per test that you want to run. The generic type N will be the type of the test network that the test will run against.

configure(TestConfigurationBuilder builder)

Sets configuration values that will affect the test’s execution.


setup(NetworkContext networkContext) -> N

Performs tasks necessary to initializing the test network before test execution, and returns a Network implementation that will be fed in as an argument to Test.run.

For example, to create a test network of three nodes you might call NetworkContext.addService three times here, use [AvailabilityChecker.waitForStartup][availabilitychecker_waitforstartup] to wait for the nodes to be available, and then return the NetworkContext (which is a Network implementation).

For a more complex use case where you’ve written a custom Network implementation that encapsulates startup logic in a setupNetwork function, you might call something like:

MyCustomNetwork customNetwork = new MyCustomNetwork(networkContext);
return customNetwork;



A Network implementation that will be passed to Test.run. If you don’t have a custom implementation, you can return the NetworkContext (which implements Network).

run(N network)

Executes test logic after Test.setup has completed. For languages that have explicit error return types (e.g. Go), returning an error from this function indicates a failure; for languages that don’t (e.g. Java), throwing an exception indicates the same. These will be marked in the individual languages’ APIs.



Object that contains various configuration parameters controlling how a test behaves, which will be configured by the TestConfigurationBuilder in the Test.configure method.

uint32 testSetupTimeoutSeconds

The amount of time a test has to finish the Test.setup phase. If the phase doesn’t complete in the allotted time, an error will be thrown.

uint32 testRunTimeoutSeconds

The amount of time a test has to finish the Test.run phase. If the phase doesn’t complete in the allotted time, an error will be thrown.

bool isPartitioningEnabled

Setting this to true allows a test to make use of the NetworkContext.repartitionNetwork method. This is a configuration flag (rather than enabled by default) because enabling repartitioning requires spinning up extra sidecar Docker containers, and thus an extra load on the system running Kurtosis.

Map<String, String> filesArtifactUrls

Mapping of a user-defined key -> URL of a gzipped TAR whose contents the test will mount on a service. This should be left empty if no files artifacts are needed. For more details on what files artifacts are, see [ContainerCreationConfig.filesArtifactMountpoints][containercreationconfig_filesartifactmountpoints].


Builder for creating a TestConfiguration object, which you should manipulate in your test’s Test.configure function. The functions on this builder will correspond to the properties on the TestConfiguration object, in the form withProperyName (e.g. withSetupTimeoutSeconds sets the test timeout in seconds). If not set, the default values for the properties are as follows:


Implementations of this interface serve as packages for a set of tests.

getTests() -> Map<String, Test>

Returns the tests the testsuite contains. This output can be modified based on custom testsuite parameters (e.g. have a doSlowTests flag that can be set to false during local development).


Map of test name -> test object.

Found a bug? File it on the repo!