Using the SDK

The webmate SDK simplifies test automation workflows and provides helpers for authentication, session handling, result reporting, and TestLab state creation.

Use this tutorial to integrate the SDK into Selenium or Appium tests and use its core features.

Installing the SDK

The Java SDK is available via Maven Central. Add the following dependency to your pom.xml (or another Maven based build tool):

<dependency>
    <groupId>com.testfabrik.webmate.sdk</groupId>
    <artifactId>java-sdk</artifactId>
    <version>0.56</version>
</dependency>

You can find the source code on this repository (opens in a new tab) .

The SDK is open-source, so, if you want to, you can also build it from source, modify or extend it. If you want to build your own webmate SDK, clone the repository from there and install the compiled artifacts to your local Maven repository with

`1`	`mvn install`

You can then include the SDK as a Maven dependency in your project as shown above. Make sure to use the version number that is set in the sources you build to prevent your dependency manager from downloading it from Maven Central.

Getting Started

You can find more code examples of how to use the SDK in this repository (opens in a new tab)

First, store your credentials and specify the context in which you want to work. Define variables for the login credentials for webmate and the ID of the project you want to work in. With these, you can create a new WebmateAPISession which is needed for most SDK functionality.

String WEBMATE_APIKEY = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=";
ProjectId WEBMATE_PROJECTID = new ProjectId(UUID.fromString("7c4f09fd-xxx-xxx-xxx-xxx"));

WebmateAuthInfo authInfo = new WebmateAuthInfo(WEBMATE_APIKEY);

WebmateAPISession webmateSession = new WebmateAPISession (
        authInfo,
        WebmateEnvironment.create(),
        WEBMATE_PROJECTID);

Set up an Automated Test

When setting up the authentication capabilities for webmate, use the constants from the SDK instead of specifying capability names manually. This ensures that the test always supplies the correct names.

When an automated Selenium or Appium test is running, you can use the SDK to obtain a seleniumSession by adding it to the created webmateSession using the session ID from your test driver. Even though the type is called WebmateSeleniumSession this also works when testing with Appium on Android or iOS.

Report Test Results

To use all TestLab features, synchronize functional test results with webmate. By calling finishTestRun() on the test session object obtained from the SDK , you can pass test results (such as logical failures or exceptions thrown in your test) to the webmate API.

try {
    driver.get("http://www.examplepage.org/");
    ...
    seleniumSession.finishTestRun(TestRunEvaluationStatus.PASSED, "TestRun completed successfully");
} catch(Throwable e) {
    seleniumSession.finishTestRun(TestRunEvaluationStatus.FAILED, e.getMessage());
    e.printStackTrace();
} finally {
    driver.quit();
}

try {
    browser.url("http://www.examplepage.org/");
    ...
    await seleniumSession.finishTestRun(TestRunEvaluationStatus.PASSED, "TestRun completed successfully").toPromise();
} catch(err) {
    await seleniumSession.finishTestRun(TestRunEvaluationStatus.FAILED, "TestRun has failed").toPromise();
} finally {
    await browserObj.deleteSession();
}

Extract State Information for Analysis in webmate

You can create checkpoints (called States) in your test run to inspect in the TestLab. This allows you to structure your tests and make the logical steps visible in webmate. It also serves as a basis for visual testing, since it allows inspection of layouts in webmate and can be used to create visual comparison or regression tests.