Configuring the TestProject OpenSDK

After you have created a new project which uses the TestProject OpenSDK, you can start writing your automated tests. However, before you can write the actual test methods, you must configure the TestProject OpenSDK.

This blog post describes how you can configure the TestProject OpenSDK when you are writing tests for a web application with JUnit 5. After you have read this blog post, you:

• Can identify the most common configuration options.
• Know how you can configure the TestProject OpenSDK when you are using JUnit 5.

Let's begin.

Introduction to the Configuration Options of TestProject OpenSDK

You can configure the TestProject OpenSDK by following these steps:

First, you have to choose the web browser which runs your tests. This choice determines the type of the WebDriver object which you must create when you configure the TestProject OpenSDK. You can find the supported WebDriver implementations from the io.testproject.sdk.drivers.web package. After you have selected the web browser, you must create the WebDriver object.

Second, you must configure the TestProject developer token by setting the value of the TP_DEV_TOKEN environment variable. You can also configure the developer token in your test code when you create a new WebDriver object, but I think that this is a bad idea (most of the time) because of these three reasons:

• You shouldn't store secrets in a version control system.
• If you have to change the developer token, it's easier to change the value of an environment variable than to make changes to your test code.
• If your tests must use different developer tokens in different environments, it's easier to use an environment variable than to make the required changes to your test code.

Third, you can specify optional browser specific settings by using a browser specific options class (ChromeOptions, EdgeOptions, FirefoxOptions, InternetExplorerOptions SafariOptions).

Fourth, you can change the url which is used to communicate with the TestProject agent by setting the value of the TP_AGENT_URL environment variable. You can also configure this url in your test code when you create a new WebDriver object, but I think that this is a bad idea. If you configure the agent url in your test code, it's not easy to use different urls in different environments.

Fifth, if you want to use a remote Selenium server provided by a cloud provider such as SauceLabs or BrowserStack, you must set the value of the cloud:URL custom capability.

You can now identify the different configuration options provided by TestProject OpenSDK. Next, you will learn how you can configure the TestProject OpenSDK when you are writing tests for a web application with Junit 5.

Integrating the TestProject OpenSDK With JUnit 5

When you want to integrate the TestProject OpenSDK with JUnit 5, the first that you have to do is to decide when you want to create the required WebDriver object. You have three different options and each option has both pros and cons. Let's go through these options one by one.

1. Create One WebDriver Object Per Test Suite

If you want that your test methods are shown on the same test report, you must create one WebDriver object per test suite. When you use this option, the TestProject agent creates one test job which runs your tests.

The following figure illustrates a scenario where the test methods found from different test classes are run by one job:

Also, this option ensures that your tests are as fast as possible because the "slow" setup code is run only once per test suite. However, the downside of this approach is that you have to pay extra attention for writing cleanup code which cleans the state of the browser after a test method has been run. This is important because you shouldn't write tests which depend on other tests.

When you want to use this option, you must follow these steps:

1. Create a new public class.
2. Add a new public and static ChromeDriver field to the created class. This field contains the WebDriver object which is used by your test methods.
3. Create a new ChromeDriver object by using the fluent API provided by the DriverBuilder class and store the created object in the INSTANCE field.

After you have created the WebDriver object, the source code of your "driver container class" looks as follows:

import io.testproject.sdk.DriverBuilder;
import io.testproject.sdk.drivers.web.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;

public class TestDriver {

    public static ChromeDriver INSTANCE = new DriverBuilder<ChromeDriver>(
            new ChromeOptions()
    )
            .withCapabilities(new ChromeOptions())
            .build(ChromeDriver.class);
}

When you want to use the created WebDriver object in your test methods, you can simply get the reference which is stored to the INSTANCE field of the TestDriver class. The following code sample demonstrates how you can use the WebDriver object in your test method:

import org.junit.jupiter.api.Test;

public class FirstSingletonExampleTest {

    @Test
    void openReddit() {
        TestDriver.INSTANCE.get("https://www.reddit.com");
    }
}

2. Create One WebDriver Object Per Test Class

If you want that all test methods of one test class are shown on the same test report, you must create one WebDriver object per test class. When you use this option, the TestProject agent creates one test job per test class. Each job runs the test methods found from the related test class.

The following figure illustrates a scenario where the test methods found from the same test class are run by one job:

Also, this option is basically a compromise between the state management of the used web browser and the performance of your test suite. If you use this option, your test suite will be a bit slower than a test suite which uses the first option. However, your tests are easier (and faster) to write because your cleanup code has to support only a limited number of test cases which test the same feature. In other words, your cleanup code will most likely be quite simple.

When you want to use this option, you must follow these steps:

First, you have create a new WebDriver object by following these steps:

1. Add a private and static ChromeDriver field to your test class. This field contains a reference to the created driver object.
2. Add a new setup method to your test class.
3. Ensure that the setup method is run once before the test methods of your test class are run.
4. Create a new ChromeDriver object by using the fluent API provided by the DriverBuilder class and store the created object in the driver field.

After you have created a new WebDriver object, the source code of your test class looks as follows:

import io.testproject.sdk.DriverBuilder;
import io.testproject.sdk.drivers.web.ChromeDriver;
import org.junit.jupiter.api.BeforeAll;
import org.openqa.selenium.chrome.ChromeOptions;

class BeforeAllExampleTest {

    private static ChromeDriver driver;

    @BeforeAll
    static void configureTestProjectOpenSDK() {
        driver = new DriverBuilder<ChromeDriver>(new ChromeOptions())
                .withCapabilities(new ChromeOptions())
                .build(ChromeDriver.class);
    }
}

Second, you have to free the resources reserved by the WebDriver object. You can do this by following these steps:

1. Add a new teardown method to your test class.
2. Ensure that the teardown method is run once after all test methods of your test class have been run.
3. Free the resources reserved by the used WebDriver object.

After you have freed the resources reserved by the WebDriver object, the source code of your test class looks as follows:

import io.testproject.sdk.DriverBuilder;
import io.testproject.sdk.drivers.web.ChromeDriver;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;
import org.openqa.selenium.chrome.ChromeOptions;

class BeforeAllExampleTest {

    private static ChromeDriver driver;

    @BeforeAll
    static void configureTestProjectOpenSDK() {
        driver = new DriverBuilder<ChromeDriver>(new ChromeOptions())
                .withCapabilities(new ChromeOptions())
                .build(ChromeDriver.class);
    }

    @AfterAll
    static void shutdownTestProjectOpenSDK() {
        driver.quit();
    }
}

3. Create a New WebDriver Object Before a Test Method Is Run

If you want that all test methods are shown on a new test report, you must create a new WebDriver object before a test method is run. When you use this option, the TestProject agent ensures that all test methods are run by different test jobs.

The following figure illustrates a scenario where the test methods found from the same test class are run by different jobs:

Also, this option ensures that every test method gets a "clean" web browser. That being said, the downside of this approach is that the "slow" setup code is run before every test method. In other words, if you use this option, your test suite might be too slow.

When you want to use this option, you must follow these steps:

First, you have create a new WebDriver object by following these steps:

1. Add a private ChromeDriver field to your test class. This field contains a reference to the created driver object.
2. Add a new setup method to your test class.
3. Ensure that the setup method is run before a test method is run.
4. Create a new ChromeDriver object by using the fluent API provided by the DriverBuilder class and store the created object in the driver field.

After you have created a new WebDriver object, the source code of your test class looks as follows:

import io.testproject.sdk.DriverBuilder;
import io.testproject.sdk.drivers.web.ChromeDriver;
import org.junit.jupiter.api.BeforeEach;
import org.openqa.selenium.chrome.ChromeOptions;

class BeforeEachExampleTest {

    private ChromeDriver driver;

    @BeforeEach
    void configureTestProjectOpenSDK() {
        driver = new DriverBuilder<ChromeDriver>(new ChromeOptions())
                .withCapabilities(new ChromeOptions())
                .build(ChromeDriver.class);
    }
}

Second, you have to free the resources reserved by the WebDriver object. You can do this by following these steps:

1. Add a new teardown method to your test class.
2. Ensure that the teardown method is run after a test method has been run.
3. Free the resources reserved by the used WebDriver object.

After you have freed the resources reserved by the WebDriver object, the source code of your test class looks as follows:

import io.testproject.sdk.DriverBuilder;
import io.testproject.sdk.drivers.web.ChromeDriver;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.openqa.selenium.chrome.ChromeOptions;

class BeforeEachExampleTest {

    private ChromeDriver driver;

    @BeforeEach
    void configureTestProjectOpenSDK() {
        driver = new DriverBuilder<ChromeDriver>(new ChromeOptions())
                .withCapabilities(new ChromeOptions())
                .build(ChromeDriver.class);
    }

    @AfterEach
    void shutdownTestProjectOpenSDK() {
        driver.quit();
    }
}

You can now configure TestProject OpenSDK and integrate it with JUnit 5. Let's summarize what you learned from this blog post.

Summary

This blog post has taught you four things:

• The io.testproject.sdk.drivers.web package contains the WebDriver implementations which are supported by TestProject OpenSDK.
• You must configure the TestProject developer token by setting the value of the TP_DEV_TOKEN environment variable.
• When you create a new WebDriver object, you should use the option that generates the test reports which fulfill your requirements.
• You can create a new driver object by using the fluent API provided by the DriverBuilder class.

P.S. You can get the example application of this blog post from Github.