Java client library for Loadero

Description

---

This is Java library that can be used as a client to interact with Loadero API service.

It allows you to create, delete, update, launch and retrieve information about tests and test's related information.

Documentation

---

Classes

Classes that are mainly used to interact with Loadero API.

Name	Description
enum Loadero(){}	Singleton configuration enum for Loadero. Here you can define things such as what API token to use and for which project.
class Test(){}	Used to perform CRUD operations on tests.
class Group(){}	Used to perform CRUD operations on groups.
class Participant(){}	Used to perform CRUD operations on participants.
class TestRun(){}	Used to perform poll operation on already running test to get information about its test run state.
class File(){}	Used to represent information about file that is used by Loadero to run tests.
class Result(){}	Used to get information about Loadero test's run result.
class Browser(){}	Used to define different versions of browsers.
class Assert(){}	Used to perform CRUD operations on asserts.
class Precondition(){}	Used to perform CRUD operations on assert's preconditions. However, this feature availability depends on your subscription plan.

Enums

Public Enums that can be used to set constant values for Loadero tests and participants.

Name	Description
enum BrowserLatest	Contains latest versions for Chrome and Firefox browsers.
enum ComputeUnit	Contains compute unit options. Availability depends on the subscription plan.
enum IncrementStrategy	Contains options for increment strategies.
enum Location	Contains different geo-locations. Availability depends on the subscription plan.
enum Network	Contains network condition options.
enum TestMode	Contains options for setting testing mode. Availability depends on the subscription plan.
enum MachineAsserts	Contains options for all machine asserts paths.
enum WebrtcAsserts	Contains options for all WebRTC asserts paths.
enum AssertOperator	Contains options for asserts operators.
enum RunStatus	Contains options for test's run statuses.
enum Property	Contains options for precondition's properties.

---

Installation

Add JitPack repository and loadero-java dependency with recent version to your pom.xml.

<repositories>
   <repository>
       <id>jitpack.io</id>
       <url>https://jitpack.io</url>
   </repository>
</repositories>
<dependencies>
    <dependency>
          <groupId>com.github.loadero</groupId>
	  <artifactId>loadero-java</artifactId>
	  <version>1.1.3</version>
    </dependency>
</dependencies>

Setup

// Before beginning to have fun with tests you should
// initiate client instance configuration that is going to be used for performing different operations.
Loadero.init(apiToken, projectId);

Retrieve existing item

All items can be retrieved with their respective IDs.

int testId = 2323;
int groupId = 13123;
int participantId = 1231231;

// Retrieving current test description, if needed.
    
Test test = Test.read(testId);
Group group = Group.read(testId, groupId);
Participant participant = Participant.read(testId, groupId, participantId);
// and so on...

Create new item

Each model has its own respective *Params class that is used for creation or modification of the model.

Disclaimer: There are two different setters for a test's script. Each should be used accordingly with your Loadero's project language.

1. For a Java/TestUI project you should use .withScript(pathToScript, "nameOfTheTestMethod"). This will parse specified .java file and extract test method annotated with @Test and this test method will be used to run tests.
   
2. For a JavaScript/Nigthwatch.js and Python/Py-TestUI project you can use .withScript(pathToScript). This will simply parse specified file into string.

Disclaimer: You can use .withScript(pathToScript) method to set Java/TestUI scripts as well, but then script should be written in .txt file and in the same way as shown in Loadero's wiki page.

TestParams tParams = TestParams
    .builder()
    .withName("Test 1")
    .withMode(TestMode.LOAD)
    .withIncrementStrategy(IncrementStrategy.RANDOM)
    .withStartInterval(Duration.ofSeconds(10))
    .withParticipantTimeout(Duration.ofSeconds(360))
    .withScript("/path/to/TestMe.java/", "testSomething")
    .build();

Test newTest = Test.create(tParams);

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

Group newGroup = Group.create(gParams);

ParticipantParams pParams = ParticipantParams
    .builder()
    .withTestId(newTest.getId())
    .withGroupId(newGroup.getId())
    .withName("participant1")
    .withCount(1)
    .withLocation(Location.EU_WEST_1)
    .withNetwork(Network.DEFAULT)
    .withBrowser(new Browser(BrowserLatest.CHROME_LATEST))
    .withComputeUnit(ComputeUnit.G2)
    .withAudioFeed(AudioFeed.DEFAULT)
    .withVideoFeed(VideoFeed.DEFAULT)
    .withRecordAudio(false)
    .build();

Participant newParticipant = Participant.create(pParams);
// and so on for other items...

Update existing item

When you want to modify an existing object you must not forget to specify the respective IDs of that object.

// Test update
TestParams tParams = TestParams
    .builder()
    .withId(testId)
    .withName("New name") // Given new name to a test
    .build();

Test updatedTest = Test.update(tParams);

// Group update
GroupParams gParams = GroupParams
    .builder()
    .withId(groupId)
    .withTestId(updatedTest.getId())
    .withCount(10)
    .build();

Group updatedGroup = Group.update(gParams);

// Participant update
ParticipantParams pParams = ParticipantParams
    .builder()
    .withId(participantId)
    .withTestId(updatedTest.getId())
    .withGroupId(updatedGroup.getId())
    .withName("new name")
    .build();

Participant updatedParticipant = Participant.update(pParams)

Delete existing item

Delete operation doesn't return anything.

Test.delete(testId);
Group.delete(testId, groupId);
Participant.delete(testId, groupId, participantId);
// and so on...

Launch tests and get results

Test class is closely associated with TestRun class in a sense that you can "launch a test to get test run results". Based on that here is how one can do that.

Disclaimer: You can launch only existing tests.

There are two way of how you can poll for results.

1. .poll(testId, runId, interval, timeout) method can be used when you have time constraints on how long should polling be running. This will run polling function for the specify period of time.
2. .poll(testId, runId, interval) method is similar to the first one except, that here timeout argument by default is set to 12 hours. If the test run exceeds 12 hours time period, then ApiPollingException will be thrown. This should be used with caution. For more information refer to https://wiki.loadero.com/loadero-usage/test-run-queue/.

When the test run is done it will return you TestRun object with status field marked as done and some additional information such as resultId that can be used to retrieve test run results.

TestRun launch = Test.launch(testId);
// 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(testId, launch.getRunId(), Duration.ofSeconds(30));

// Assuming that test run was successful
Result result = Result.read(run.getId(), run.getResultId());    

// Test run can be gracefully aborted.
// In such case polling will be aborted as well as there is no longer active test run   
TestRun.stop(testId, rundId);

Unit tests

---

Package provides some predefined set of unit tests that can be run with Maven.

Unit tests are run using two environment variables called LOADERO_API_TOKEN and LOADERO_BASE_URL, respectively.
Set this variables somewhere in your project if you wish to run tests against actual Loadero API service. Otherwise, tests will be run against mock data on localhost.

For exmaple:

Use System.getenv() to get values for Loader token and base url from your environment variables
and assign them accordingly inside TestWithWireMock class.

private static final String token = System.getenv("LOADERO_API_TOKEN");
private static final String baseUrl = System.getenv("LOADERO_BASE_URL");

Maven unit tests can be run in to modes.
First one is in the mock mode(default). This mode will run tests only against mocked/saved/predifined data.
Second mode can be activating with -Denv=live flag. In this mode unit tests will be run against real Loadero API service using your Loadero API token provided from environment variables.

To run all tests in /test directory.

mvm test

To run a specific set of tests against mocked data.

mvn -DTest=TestPackage test

To run a specific set of tests with real credentials(eg. API toke, real IDs etc.).

mvn -DTest=TestPackage -Denv=live test

To run a specific test method inside test class.

mvn -DTest=TestPackage#testGetTestById test