Using the SDK

To simplify workflows and make automation of test cases and test suites as simple and as powerful as possible, we offer a webmate SDK. In this tutorial, we will show you how to integrate the SDK into your tests and make use of its features.

Installing the SDK

1
2
3
4
5

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

1

 "webmate-sdk-js": "^0.52"

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

1

npm install

Getting Started

First, you need to store your credentials, and specify the context in which you want to work. To do so, we recommend defining 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.

1
2
3
4
5
6
7
8
9

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);

1

webmateSession = Webmate.startSession("xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=", "https://api.webmate.io/v1", "7c4f09fd-xxx-xxx-xxx-xxx");

Set up an Automated Test

When setting up the authentication capabilities for webmate, there is no need to specify the capability names yourself, you can use the constants from the SDK. That way you can be sure that you always supply the correct names.

1
2

caps.setCapability(WebmateCapabilityType.API_KEY, "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=");
caps.setCapability(WebmateCapabilityType.PROJECT, "7c4f09fd-xxx-xxx-xxx-xxx");

1
2
3
4

capabilities: {
    apikey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
    project: "7c4f09fd-xxx-xxx-xxx-xxx"
}

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.

1

WebmateSeleniumSession seleniumSession = webmateSession.addSeleniumSession(driver.getSessionId().toString());

1

seleniumSession = webmateSession.addSeleniumSession(session.getId());

Report Test Results

If you want to make use of all features of the TestLab, we recommend synchronizing test results of your functional tests 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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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();
}

1
2
3
4
5
6
7
8
9

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.

1

browserSession.createState("after click");

1

await webmateSession.browserSession.createState("state name").toPromise();