Skip to main content

Java Client

Java Client is a Java library that allows to use Loadero in a programmatic manner. The client wraps the Loadero API service allowing to perform all of the same operations that the API service provides:

  • create, update and delete tests and test related resources.
  • launch, stop and oversee test runs
  • retrieve information about results

To use the client a valid project access token is required. For more information about API tokens check the documentation here.


Documentation for the Client is available in Javadoc.

The client is fully open source and be found in our Github repository.

Releases of the library are available in JitPack.

Installation and setup

To install the client in your application, simply add loadero-java dependency to the Maven pom.xml file.

<!-- loadero.version needs to be defined in properties and should always be the latest version-->


To start using the Client first it needs to be initialized with

Loadero.init(apiToken, projectId);

Project ID can be found in the frontend application in project settings page or it can be retrieved from the URL{projectID}/tests/


Each project requires a separate API token

A new test can be created with the TestParams object. Here is an example showcasing test creation.

TestParams tParams = TestParams
.builder() // initialize builder
.withName("Test 1") // set test name
.withMode(TestMode.LOAD) // set test mode
.withIncrementStrategy(IncrementStrategy.RANDOM) // set test participant increment strategy
.withStartInterval(Duration.ofSeconds(10)) // set test start interval
.withParticipantTimeout(Duration.ofSeconds(360)) // set test participant timeout
.withScript("/path/to/", "testSomething") // set test script from local file
.build(); // build test params

Test newTest = Test.create(tParams); // create test

Test can have grouped and groupless participants. For this quick start, we will use grouped participants.

To create a grouped participant, you need to use a GroupParams object:

GroupParams gParams = GroupParams
.builder() // initialize builder
.withTestId(newTest.getId()) // we need to provide id of existing test in order to create a new group for it
.withName("Group name") // set group name
.withCount(1) // set group count
.build(); // build group params

Group newGroup = Group.create(gParams); // create group

For the test to run, we need to create the participants which will be executing the test script:

ParticipantParams pParams = ParticipantParams
.builder() // initialize builder
.withTestId(newTest.getId()) // we need to provide id of existing test in order to create a new participant for it
// skip .withGroupId() if you wish to make an groupless participant
.withGroupId(newGroup.getId()) // we need to provide id of existing group in order to create a new participant for it
.withName("participant1") // set participant name
.withCount(1) // set participant count
.withLocation(Location.EU_WEST_1) // set participant location
.withNetwork(Network.DEFAULT) // set participant network
.withBrowser(new Browser(BrowserLatest.CHROME_LATEST)) // set participant browser
.withComputeUnit(ComputeUnit.G2) // set participant compute unit
.withMediaType(MediaType.DEFAULT) // set participant media type
.withRecordAudio(false) // set participant record audio
.build(); // build participant params

Participant newParticipant = Participant.create(pParams);

At this point this test is ready to run. To run the test the following snippet can be used, this will also print logs indicating current test status.

TestRun launch = Test.launch(newTest.getId());
// Third parameter is specifying how often it should check on test run.
// In this case it will log update message every 30 seconds.
TestRun run = TestRun.poll(newTest.getId(), launch.getRunId(), Duration.ofSeconds(30));

When the test run is done, the poll method will return the TestRun object. For further actions with the gathered test data, we will need to have access to Result object list - it can be read using the data provided in the TestRun object together with previously created test id.

List<Result> results = Result.readAll(newTest.getId(), run.getId());