DEV Community: Elias Nogueira

Custom JUnit 5 Extensions for Testing

Elias Nogueira — Mon, 02 Feb 2026 21:05:49 +0000

Introduction

JUnit 5 extensions are one of those features many teams rely on every day without ever thinking about them. If you use Mockito, Spring Boot tests, or Testcontainers, extensions are already doing a lot of work behind the scenes for you.

What is far less common is to use the same mechanism deliberately to solve problems in your own test suite. Especially in integration tests, extensions can simplify code, remove repetition, and make tests easier to reason about.

What a JUnit 5 extension really is

A JUnit 5 extension is not just a helper class or a utility method. It is a way to hook into the test execution lifecycle.

When JUnit runs a test, it goes through a well-defined lifecycle. Test classes are discovered, instances are created, methods are executed, and results are collected. At each of these steps, JUnit checks whether there are extensions registered for that test and gives them a chance to participate in the process.

From a technical point of view, an extension is a plain Java class that implements one or more interfaces from the org.junit.jupiter.api.extension package. Each interface represents a specific moment in the test lifecycle. Some extensions run before a test class is instantiated, others after each test method, and others only when an exception is thrown.

Once registered using the @ExtendWith annotation, the extension becomes part of the execution flow. It reacts to events triggered by the engine instead of being explicitly invoked by the test code.

Why does this matter for any type of tests?

Sometimes, tests often fail for reasons that have nothing to do with business logic. Timing issues, asynchronous processing, external services, and unstable environments are common sources of problems.

If this kind of logic is handled directly inside test methods, like the common approach of creating helper classes, tests quickly become noisy and hard to maintain. Extensions allow these concerns to live in one place, outside the test logic, while still being applied consistently across the entire test suite.

Example: Environment availability check

This example is more of a feature of the testing framework than many tools you already use, such as Testcontainers, Mockito, and others, that provide their own JUnit extension.

The problem with environment failures

Let’s think that you have a project that also runs system or end-to-end tests in different environments, like a staging, QA, pre-pro, ephemeral, or whatever environment you have to test. We have all been facing this problem: the environment unavailability.

We run the test, everything fails, the error message is noisy and misleading, and, only after a few seconds or minutes, we realize that the target system is not running. This is not a test failure; this is an infrastructure failure. This failure can be anything: a backend service, a database, or the message broker, and any other thing in the architecture that can prevent the system, or part of it, from being available.

There are some symptoms, like connection refused errors, timeouts, stack traces unrelated to the test intent, and dozens of failed tests hiding a single root cause. The approach we will take in the example is: if the environment is not ready, do not run any test.

Why does this not belong in the test code?

The availability of a backend is not part of the test logic, as tests should describe behavior, not infrastructure health checks.

This makes it a perfect candidate for a JUnit 5 Extension, as it:

runs before tests
applies consistently
keeps test code clean
fails fast with a clear message

The idea is to make an environment availability a precondition. As we can influence the test lifecycle in JUnit 5 using a custom extension can do the following if the requirements about the environment availability are not met:

abort the execution
or skip the tests with a clear explanation

That is exactly what Assumptions.assumeTrue(...) is designed for.

Implementing the extension

The extension below checks whether a backend health endpoint is reachable before any test runs. If the backend is down, tests are skipped immediately with a clear message.

public class EnvironmentAvailabilityExtension implements BeforeAllCallback {

    private static final int TIMEOUT = 1000;
    private static Boolean isEnvironmentReady;

    private static final Logger log = LogManager.getLogger(EnvironmentAvailabilityExtension.class);

    @Override
    public void beforeAll(ExtensionContext context) {
        if (isEnvironmentReady == null) checkEnvironmentHealth();

        Assumptions.assumeTrue(isEnvironmentReady,
                "Environment is not available. Start it before running the tests."
        );
    }

    private synchronized void checkEnvironmentHealth() {
        if (isEnvironmentReady != null) return;

        HttpURLConnection connection = null;

        try {
            URL url = URI.create("http://my-environment-address/api/health").toURL();

            connection = (HttpURLConnection) url.openConnection();
            connection.setConnectTimeout(TIMEOUT);
            connection.setReadTimeout(TIMEOUT);
            connection.setRequestMethod("GET");

            isEnvironmentReady = (connection.getResponseCode() == HttpURLConnection.HTTP_OK);
        } catch (Exception e) {
            log.error("Environment is not available. Start it before running the tests.");
            isEnvironmentReady = false;
        } finally {
            if (connection != null) connection.disconnect();
        }
    }
}

The method checkEnvironmentHealth() will check if the health check of the environment is healthy, which means returning an HTTP status of OK (200); then, it will return true or false. This control is done via the BeforeAllCallback interface, where we add the check that the environment is available, validating it via an Assumption action that will make the test not run. As it does not provide any output, we have logged in the catch that the environment is not available, so we can see it in any log.

How to use it?

Add the @ExtendWith on top of the test class within the EnvironmentAvailabilityExtension class as a parameter.
This will “tell” JUnit to run this extension as part of the test lifecycle, like the @BeforeAll or @BeforeEach.

@ExtendWith(EnvironmentAvailabilityExtension.class)
class OrderTest {

    @Test
    void shouldCreateOrder() {
        // test logic
    }
}

Live example

The project restassured-complete-basic-example has the example of the environment availability developed as one of the available test strategies: a custom JUnit Extension that won’t run the tests in the case the health check endpoint is not reachable.

Take a look at the implementation and, maybe, try it out in your local machine: https://github.com/eliasnogueira/restassured-complete-basic-example/blob/main/src/main/java/com/eliasnogueira/credit/extensions/EnvironmentAvailabilityExtension.java

Extensions you are already relying on

Most Java developers already use JUnit 5 extensions, even if they never wrote one themselves.

Mockito uses an extension to initialize mocks, spies, and argument captors.
Spring relies on an extension to bootstrap the application context and manage dependency injection in tests.
Testcontainers integrates with JUnit to control container startup and shutdown predictably.

All of these tools hook into the same extension points shown in the examples above.

Final thoughts

JUnit 5 extensions are not an advanced feature reserved for framework authors. They are a practical way to keep integration tests focused, readable, and consistent.

When you see the same setup code, retry logic, or infrastructure concerns appearing across multiple tests, an extension is often the cleanest solution. Once you start using them intentionally, it becomes hard to imagine maintaining a larger integration test suite without them.

Assert with Grace: Custom Soft Assertions using AssertJ for Cleaner Code

Elias Nogueira — Tue, 19 Nov 2024 20:39:25 +0000

Introduction

If you don’t know what a soft assertion is, please read Soft Asserts – Why should you use them for Unit and Integration tests?

This article is a continuation of Assert with Grace: Custom Assertions for Cleaner Code which shows you how to create custom assertions using AssertJ. Here you will learn how to extend its approach to use the soft assertion approach on top of the custom assertion.

Custom Soft Assertions with AssertJ

You can have a hard assertion using the Assertions class from AssertJ or a custom one. To get all the benefits of the soft assertion we need to:

have a custom assertion implemented
create the custom soft assertion class and extend the AbstractSoftAssertions from AssertJ

The custom assertion

You learned how to create a custom assertion in the Assert with Grace: Custom Assertions for Cleaner Code article. It looks like this:

public class SimulationAssert extends AbstractAssert<SimulationAssert, Simulation> {
    protected SimulationAssert(Simulation actual) {
        super(actual, SimulationAssert.class);
    }
    public static SimulationAssert assertThat(Simulation actual) {
        return new SimulationAssert(actual);
    }
    public SimulationAssert hasValidInstallments() {
        isNotNull();
        if (actual.getInstallments() < 2 || actual.getInstallments() >= 48) {
            failWithMessage("Installments must be must be equal or greater than 2 and equal or less than 48");
        }
        return this;
    }
    public SimulationAssert hasValidAmount() {
        isNotNull();
        var minimum = new BigDecimal("1.000");
        var maximum = new BigDecimal("40.000");
        if (actual.getAmount().compareTo(minimum) < 0 || actual.getAmount().compareTo(maximum) > 0) {
            failWithMessage("Amount must be equal or greater than $ 1.000 or equal or less than than $ 40.000");
        }
        return this;
    }
}

The usage of the custom assertion shows more legibility in the test as well as sends the responsibility of testing the valid values to it:

class SimulationsCustomAssertionTest {
    @Test
    void simulationErrorAssertion() {
        var simulation = Simulation.builder().name("John").cpf("9582728395").email("john@gmail.com")
                .amount(new BigDecimal("1.500")).installments(5).insurance(false).build();
        SimulationAssert.assertThat(simulation).hasValidInstallments();
        SimulationAssert.assertThat(simulation).hasValidAmount();
    }
}

With the custom assertion on hand, it’s time to implement the custom soft assertion.

Create the custom soft assertion

There is an easy process to create the custom soft assertion where the precondition is to have a custom assertion implemented. Given the previous article, we have the SimulationAssert class as the custom assertion and will create the SimulationSoftAssert as a custom soft assertion. These are the steps:

Extend the AbstractSoftAssertions class
Create the assertThat() method with:
- the method returns an object as the custom assertion class
- a parameter to the subject of the assertion
- the method returns the method proxy where the parameters are the custom assertion class and the subject of the assertion
Create the assertSoftly() method with:
- a parameter as a Consumer to the custom soft assert class
- Use the SoftAssertionsProvider.assertSoftly() method as the parameter is the custom soft assertion class and the method parameter

The steps look complex, but in practice, you will end up with this:

public class SimulationSoftAssert extends AbstractSoftAssertions {
    public SimulationAssert assertThat(Simulation actual) {
        return proxy(SimulationAssert.class, Simulation.class, actual);
    }
    public static void assertSoftly(Consumer<SimulationSoftAssert> softly) {
        SoftAssertionsProvider.assertSoftly(SimulationSoftAssert.class, softly);
    }
}

Using the Custom Soft Assertion

The AssertJ SoftAssertion class is responsible for the soft assertions. This is the example applicable to the Simulation context:

The AssertJ SoftAssertion class is responsible for the soft assertions. This is the example applicable to the Simulation context:

@Test
public void normalSoftAssertion() {
    SoftAssertions.assertSoftly(softly -> {
        var simulation = Simulation.builder().name("John").cpf("9582728395").email("john@gmail.com")
                .amount(new BigDecimal("500")).installments(1).insurance(false).build();
        softly.assertThat(simulation.getInstallments()).isEqualTo(1);
        softly.assertThat(simulation.getAmount()).isEqualTo(500);
    });
}

The “problem” using it is that we won’t be able to use the custom assertion we have created. In the example above you can see the assertions in the installments and amount using the isEqualTo() as the SoftAssertions class has no access to the custom assertion.

We have solved this problem by creating the custom soft assertions class. So, instead of using the SoftAssertions class we will use the custom one: SimulationSoftAssert.

@Test
void simulationValidationErrorSoftAssertion() {
    var simulation = Simulation.builder().name("John").cpf("9582728395").email("john@gmail.com")
            .amount(new BigDecimal("500")).installments(1).insurance(false).build();
    SimulationSoftAssert.assertSoftly(softly -> {
        softly.assertThat(simulation).hasValidInstallments();
        softly.assertThat(simulation).hasValidAmount();
    });
}

The SimulationSoftAssert.assertSoftly() is a provider for the soft assertion that will call all internal methods to be able to manage the errors and other activities during the assertions. The assertThat() in use, inside the assertSoftly() will be the custom one which will have access to the custom assertion by the proxy() between the soft assert and the subject of the assertion.

Using this approach we have the custom assertions available in the soft assertion by the implementation of a custom one.

The end

That’s all folks!

You can find a fully implemented and working example in the credit-api project, where you can see the following:

SimulationAssert class
Test usage in the SimulationsCustomAssertionTest class

How to simulate real BeforeAll and AfterAll in JUnit 5

Elias Nogueira — Fri, 05 Jul 2024 08:51:00 +0000

Introduction

JUnit 5 is a well-known Java Testing Framework/Library across developers. It’s the evolution of JUnit 4 and carries with it a lot of awesome features. One of the most important ones is setting pre and post-conditions as knowing by the terms Before (pre-condition) and After (post-condition).

It has 2 supported ways: Before/After All and Before/After Each.
The “All” part means that a code block can be executed as pre or post-condition before or after it can initialize all tests. The “Each” part means that a code block can be executed as a pre or post-condition before or after each test.

The JUnit 5 official docs say the following about these strategies, which are annotations:

Annotation	Description
`@BeforeEach`	Denotes that the annotated method should be executed before each `@Test`, `@RepeatedTest`, `@ParameterizedTest`, or `@TestFactory` method in the current class; analogous to JUnit 4’s `@Before`. Such methods are inherited unless they are overridden
@AfterEach	Denotes that the annotated method should be executed after each `@Test`, `@RepeatedTest`, `@ParameterizedTest`, or `@TestFactory` method in the current class; analogous to JUnit 4’s @After. Such methods are inherited unless they are overridden.
`@BeforeAll`	Denotes that the annotated method should be executed before all `@Test`, `@RepeatedTest`, `@ParameterizedTest`, and `@TestFactory` methods in the current class; analogous to JUnit 4’s `@BeforeClass`. Such methods are inherited unless they are overridden and must be static unless the “per-class” test instance lifecycle is used.
`@AfterAll`	Denotes that the annotated method should be executed after all `@Test`, `@RepeatedTest`, `@ParameterizedTest`, and `@TestFactory` methods in the current class; analogous to JUnit 4’s `@AfterClass`. Such methods are inherited unless they are overridden and must be static unless the “per-class” test instance lifecycle is used.

What problem we are trying to solve

Only by looking at the annotations, we understand that it covers most of the scenarios we want for our tests.
We have the @BeforeAll and @AfterAll annotations as a general pre or post-condition.

One common testing pattern applied in good testing architectures is the BaseTest class: a place where we can add pre and post-conditions that will shared across different tests by inheritance. Normally, we want to control these conditions in different ways. Developers have different ways to control it through the BaseTest pattern:

open the browser only once when any test starts to save time
keep a container (Testcontainer) opened for different test classes
ingest data before any test is executed and remove it after all are executed

I have bad news: JUnit 5 doesn’t have a way to control the three mentioned scenarios as the @BeforeAll and @AfterAll are executed per test instance, meaning per test class. Other frameworks like TestNG have this ability called @BeforeSuite and @AfterSuite, and it’s exactly what we want that JUnit 5 does not support.

Let’s understand how we could use JUnit 5 for this and how to fix this problem.

The BeforeAllCallback and AfterAllCallback interfaces

You might do some Google search, like I did infinite times, encountering the BeforeAllCallback and AfterAllCallback interfaces which are Extensions of Testing Lifecycle Callbacks. It seems a good solution as these interfaces enable you to run the @BeforeAll or @AfterAll.

public class MyExtension implements BeforeAllCallback, AfterAllCallback {
    @Override
    public void afterAll(ExtensionContext context) {
        // pre general condition
    }

    @Override
    public void beforeAll(ExtensionContext context) {
        // post general conditions
    }
}

The UML diagram shows a BaseTest using a JUnit 5 Extension called MyExtension that implements the BeforeAllCallback and AfterAllCallback. The base test is used in the FeatureTest1 and FeatureTest2. Note that the MyExtension has the beforeAll and afterAllMethods, as well as the BaseTest has it.

It solves the problem as the MyExtension would serve as the global before and after, as the ones in the BaseTest would run per test instance, meaning running when Feature1Test and Feature2Test run. Unfortunately, it’s not the case. If we would add only a System.out.println() call in each method, the output would be the following:

[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.eliasnogueira.feature1.Feature1Test
MyExtension.beforeAll
BaseTest.beforeAll
Feature1Test.test1
Feature1Test.test2
Feature1Test.test3
BaseTest.afterAll
MyExtension.afterAll
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.018 s -- in com.eliasnogueira.feature1.Feature1Test

[INFO] Running com.eliasnogueira.feature2.Feature2Test
MyExtension.beforeAll
BaseTest.beforeAll
Feature2Test.test1
Feature1Test.test2
BaseTest.afterAll
MyExtension.afterAll
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.002 s -- in com.eliasnogueira.feature2.Feature2Test

You can see that the methods in the MyExtension run for every test class, as well as the BaseTest. This means that JUnit runs it per test instance. Unfortunately, JUnit 5 doesn’t have a solution for a general precondition before or after any test for the whole test execution.

Want to see it in action?
– Clone this repo: git clone https://github.com/eliasnogueira/junit5-before-after-all
– Switch to the no-solution branch
– Run mvn test

How to solve it

There is a light at the end of the tunnel and it’s not difficult. Like everyone, I Google it and found an interesting workaround on this Stackoverflow thread: https://stackoverflow.com/questions/43282798/in-junit-5-how-to-run-code-before-all-test.

Be aware that this is a workaround and might not work in future JUnit versions.

The solution is based on using the BeforeAllCallback interface, with a thread lock in case parallel tests run to solve the general precondition and the JUnit storage mechanism to mimic the postcondition using the ExtensionContext.Store.CloseableResource interface. Don’t worry, I will break down the implementation.

The example

It is a simple one just to show you that the approach works. The example shows a general BaseTest and a BaseTest per feature, where an extension will be created to give the ability of execution a general pre and postcondition.

The extension implementation

The implementation can be done in four steps, and the final solution will look like this:

1  public class SetupExtension implements BeforeAllCallback, Store.CloseableResource {
2 
3     private static final Lock LOCK = new ReentrantLock();
4     private static volatile boolean started = false;
5 
6     @Override
7     public void beforeAll(ExtensionContext context) {
8         LOCK.lock();
9  
10         try {
11            if (!started) {
12                started = true;
13                System.out.println("[pre-condition] Should run only once");
14                context.getRoot().getStore(Namespace.GLOBAL).put("Placeholder for post condition", this);
15            }
16        } finally {
17            // free the access
18            LOCK.unlock();
19        }
20    }
21 
22 
23    @Override
24    public void close() {
25        System.out.println("[post-condition] Should run only once");
26    }
27 }

Implementation of the necessary interfaces

Line 1 shows that the two interfaces: BeforeAllCallback overriding the beforeAll() method which will control the general precondition and ExtensionContext.Store.CloseableResource overrides the close() method which will mimic the general postcondition.

Controlling the single execution of the beforeAll

To guarantee that it will be executed only once one strategy must be applied: control that it has started, so the beforeAll() won't execute again.

Line 8 shows that we are locking the thread. This is necessary to ensure that any parallel execution will be possible. Line 11 checks if the code had any previous execution. When it's the first time the boolean started is set as true ensure it won't go to the code block in the subsequent runs. The finally section unlocks the thread.

Implementing the general precondition

Any necessary implementation for the general precondition should be placed inside the if condition, simple like that. We can see this in the line 13.

Add a signal (storage) to mimic the general postcondition

The way to mimic the general postcondition here is through the Store. In JUnit 5, we can store objects for later retrieval in an extension and it can be done using the getStore(context).put(key, value) where the context is the root or current context and the key,value are the key and value to add to its storage.

Line 14 creates a dummy store object for later usage in the automatic close() method invocation.

Implement the general postcondition

The close() method from the ExtensionContext.Store.CloseableResource interface will be invoked when the extension lifecycle ends [reference]. This is the last opportunity to execute any code before the program exits. In this way, we can simulate the general postcondition.

Code example

The https://github.com/eliasnogueira/junit5-before-after-all project shows the implementation based on this article’s explanation matching the diagram in “The example” section.

While running the tests you will see the following output:

[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.eliasnogueira.feature1.Feature1Test
[pre-condition] Should run only once
BaseTest.beforeAll
BaseFeature1Test.beforeAll
Feature1Test.test1
Feature1Test.test2
Feature1Test.test3
BaseFeature1Test.afterAll
BaseTest.afterAll
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.019 s -- in com.eliasnogueira.feature1.Feature1Test

[INFO] Running com.eliasnogueira.feature2.Feature2Test
BaseTest.beforeAll
BaseFeature2Test.beforeAll
Feature2Test.test1
Feature1Test.test2
BaseFeature2Test.afterAll
BaseTest.afterAll
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.002 s -- in com.eliasnogueira.feature2.Feature2Test
[post-condition] Should run only once

Note that the general precondition is the text output as [pre-condition] Should run only once and the general postcondition is the output as [post-condition] Should run only once. You can see them at the beginning and the end of all test executions, respectively.

Using this simple approach you can have the general pre and postcondition in your code.
Happy tests!

JUnit 5 – When to use CSV Providers

Elias Nogueira — Sun, 10 Mar 2024 21:38:56 +0000

Introduction

This article belongs to the Managing Test Data series.
I will show you different ways to smartly use testing framework features when the date changes but the test output is the same.

In this article, you will see one use case for the @CsvSource and @CsvFileSource features. These annotations are particularly useful when you want to provide test data in CSV (Comma-Separated Values) format either directly in the source code or from an external file.

@CsvSource

This Source of Argument in JUnit 5 allows you to use the data as CSV values to allow you either a fast prototype of a CSV file consumption in a test or by the simple use of it to give you the advantage of readability for small data sets. It has different ways to configure it, but let’s focus first on the basic usage.

class CsvSourceTest {
    private static final String MAXIMUM_PRICE = "30.0";

    @DisplayName("Products should not exceed the maximum price")
    @ParameterizedTest(name = "product ''{0}'' of amount ${1} does not exceeds $" + MAXIMUM_PRICE)
    @CsvSource({
            "Micro SD Card 16Gb, 6.09",
            "JBL GO 2, 22.37",
            "iPad Air Case, 14.99",

    })
    void productsLassThan(String product, BigDecimal amount) {
        assertThat(product).isNotEmpty();
        assertThat(amount).isLessThanOrEqualTo(new BigDecimal(MAXIMUM_PRICE));
    }
}

Lines 6 to 11 show you the basic usage of the @CsvSource. Note that:

The CSV data is placed between brackets in the annotation
Each CSV line has double quotes at the beginning and end of it
All the values are separated by a comma, after the end of the double quotes.

The test output will look like this:

CsvSourceTest
└─ Products should not exceed the maximum price
  ├─ [1] product 'Micro SD Card 16Gb' of amount $6.09 does not exceeds $30.0 ✔
  ├─ [2] product 'JBL GO 2' of amount $22.37 does not exceeds $30.0 ✔
  └─ [3] product 'iPad Air Case' of amount $14.99 does not exceeds $30.0 ✔

Annotation configurations

There are different ways to change the @CsvSource behavior:

Annotation configuration	What it does
`value`	This is the default.
`delimiter`	Set the delimiter as a char. The default value is a comma (`,`)
`delimiterString`	Set the delimiter as a String. The default is a comma (`,`)
`emptyValue`	Set what will be added as an empty value. The default is an empty value set as a double quote (`""`) The empty value should be added as a single quote on the line value.
`ignoreLeadingAndTrailingWhitespace`	The leading and trailing whitespace is automatic tribber by default. Set it to `true` to ignore it.
`maxCharsPerColum`	Sets the max chars in the column. The default is `4096`.
`nullValues`	Add the ability to set a specific value to the CSv to `null`.
`quoteChar`	Determine which character will be used to quote the value. You quote the value when you need to add either a space or any char that might fail the process of reading the line. The default is single quotes (`''`).
`textBlock`	Allows you to use the Text Blocks feature of Java >= 15. It also gives the ability to add comments in the data source which must begin with `#`
`useHeadersInDisplayName`	Set to true when you want to use a header in the first line. This option is set by default as `false`.

When you use a configuration the value attribute must be explicitly declared. You see the example in the below extra explanation.

nullValues

Use it when you want to make a specific value to null.

@CsvSource(nullValues = "6.09", value = {
        "Micro SD Card 16Gb, 6.09",
        "JBL GO 2, 22.37",
        "iPad Air Case, 14.99",

})

In the code snippet above you can see that the nullValues is using "6.09". The first value the @CsvSource contains this value, so it will be replaced by a null value instead of using the original one.

textBlock

It allows you to use the Text Blocks feature from Java >= 15, so you don’t need to wrap up the value in the curly brackets. Instead, use the """ as you can see in the example below.

@CsvSource(textBlock = """
        "Micro SD Card 16Gb, 6.09",
        "JBL GO 2, 22.37",
        "iPad Air Case, 14.99"
        """
)

Why using @CsvSource?

Inline CSV data will make the test method more readable and concise, especially when you are dealing with a small number of test cases, so you get the benefit of readability and conciseness.

All test data is directly visible within the test method, making it easy for developers to understand the different scenarios being tested without having to navigate to external files adding immediate visilibity, also reducing external dependencies since the test data is embedded within the source code, you don’t need external CSV files, which can simplify the project structure and reduce dependencies on external resources.

It’s easy to maintain for a small set of test data, helping you to prototype possible scenarios using a CSV file without adding all the dependencies, external files, and complexity.

@CsvFileSource

The @CsvFileSource allows you to provide test data from an external CSV file. This is especially useful when you have a larger set of test data that you want to manage separately from your test code.

class CsvFileSourceTest {

    private static final String MAXIMUM_PRICE = "30.0";

    @DisplayName("Products should not exceed the maximum price")
    @ParameterizedTest(name = "product ''{0}'' of amount ${1} does not exceeds $" + MAXIMUM_PRICE)
    @CsvFileSource(resources = "/products.csv")
    void productsLassThan(String product, BigDecimal amount) {

        assertThat(product).isNotEmpty();
        assertThat(amount).isLessThanOrEqualTo(new BigDecimal(MAXIMUM_PRICE));
    }
}

Line 6 shows the usage of the @CsvFileSource. Not that is using the attribute resources, which will look at the file provided in the resource folders. The default behavior is also to expect the CSV file without a header. You can see a possible file for this test execution:

Micro SD Card 16Gb,6.09
JBL GO 2,22.37
iPad Air Case, 14.99

The particularities

These are the following particularities compared to the @CsvSource.

Same configuration as the @CsvSource

The @CsvFileSource has the same annotation configuration as the @CsvSource, except for the change in the expected quoteChar as it expects double quotes ("") instead of single ones.

Extra configurations

Annotation configuration	What it does
`files`	Read the external file as a file, so it requires a full path based on the project classpath.
`numLinesToSkip`	Skip N lines as N is the number of lines to skip. This is useful when you have a header in the file, where you can set it as `1`. The default value is `0`.
`encoding`	Changes the file encoding. The default value is `UTF-8`.

resources and files

I believe you noticed that both are in the plural. This means that you can set multiple files. Only single quotes are necessary when you add only one file, as you can see in the previous example.

In case, you want to merge multiple files, simply add the files separated by commas wrapped up in curly brackets.

@DisplayName("Products should not exceed the maximum price")
@ParameterizedTest(name = "product ''{0}'' of amount ${1} does not exceeds $" + MAXIMUM_PRICE)
@CsvFileSource(resources = {"/products.csv", "/products-no.csv"}, numLinesToSkip = 1)
void productsLassThan(String product, BigDecimal amount) {
    assertThat(product).isNotEmpty();
    assertThat(amount).isLessThanOrEqualTo(new BigDecimal(MAXIMUM_PRICE));
}

Line 3 shows the usage of two files: products.csv and products-no.csv.

They must share the same columns you are using in your parameter conversion, the ones you add in your test like String product and BigDecimal amount in this example.

If you use a column and parameter that is present in one file, but not in the other, a ParameterResolutionException will be thrown.

When to use these annotations?

The @CsvFileSource is straightforward: use it when you need to use an external CSV file in your tests.

The author recommends you use the @CsvSource while protecting your data-driven tests using only primitive values or object-related ones like String, Integer, and so on. Otherwise, use any other Source of Arguments provided by JUnit 5.

One of the most underrated Maven configurations: maven.config

Elias Nogueira — Tue, 27 Feb 2024 16:06:52 +0000

Introduction

Maven is a solid and most used build automation tool in the Java world. Everyone knows Maven!
It’s present in any type of project and one of the first tools we have contact with while learning Java.

How much do you know about Maven features?

This is why I will show one of the most underrated Maven Configuration features: the maven.config file.

Motivation

I asked this question on Twitter: How frequently do you use the maven.config file?
The answer you can see below leads me to think that people don't know about this Maven feature.

// Detect dark theme var iframe = document.getElementById('tweet-1759616561290031497-38'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1759616561290031497&theme=dark" }

Maven Configurations

The most common Maven Configurations, that you might use at some point are the command line MVN_OPTS and MVN_ARGS environment variables for JVM arguments and Maven options, respectively.

But there are more! On the Maven Configurations page, you will see the .mvn directory section that contains explanations about extensions, JVM config, and the Maven config as the .mvn/maven.config file.

The Maven Config file

It consists of a file that must be placed in a .mvn folder in the root project directory. Then the maven.config file can contain all the parameters you commonly pass as arguments.

Example: When you want to run any command, for example, the test lifecycle, with a quiet output (-q), using 3 threads (-T3) and failing it fast (-fail-fast) you would end up with the following command

mvn -q -T3 -fail-fast test

Be aware of one thing: the configuration in the file is “global” meaning that it will be applied for all the Maven Lifecycles you execute.

For example, let’s assume you have this configuration in your project and you compile, run the tests, and distribute it in a pipeline, the following commands would be used:

Compilation process: mvn clean install
Testing process: mvn test
Distribution process: mvn install

Note that all the commands do not have the -q -T3 -fail-fasttest parameters, but they will be executed anyway because it’s in the .mvn/maven.config file.

Better Page Objects strategy using AjaxElementLocatorFactory with Selenium and Java

Elias Nogueira — Wed, 20 Dec 2023 09:50:30 +0000

Introduction

Page Objects Model is a Testing Pattern created by Selenium WebDriver to better model the web test architecture into the domain we are testing, creating classes that have all interactions with a web page.

There are thousands of articles on the internet, and I recommend you view the one from the Selenium WebDriver page: https://www.selenium.dev/documentation/test_practices/encouraged/page_object_models

Page Factory

If you already know about it, please skip this section.

Page Factory is a class that initializes all the elements in the page objects to reduce the class verbosity. Without the usage of the Page Factory class, we would have a class like this:


public class PageObjectExample {

    private final WebDriver driver;

    public PageObjectExample(WebDriver driver) {
        this.driver = driver;
    }

    public void login(String email, String password) {
        driver.findElement(By.id("email")).sendKeys(email);
        driver.findElement(By.id("password")).sendKeys(password);
        driver.findElement(By.name("next")).click();
    }
}

Note that the method login has all the interactions with the page, where we are using the driver field to find and interact within the elements based on its locator.

This example is fine for a few elements on the page, but I’m sure you will have a lot of elements on some pages.

Now, what the Page Factory class proposes to do is mainly reduce the verbosity of the Page Object by using WebElements as fields in the class followed by the PageFactory class usage to instantiate the elements.

This will reduce the necessity to use driver.findElement(By...)

public class PageObjectExample {

    @FindBy(id = "email")
    private WebElement email;

    @FindBy(id = "password")
    private WebElement password;

    @FindBy(name = "next")
    private WebElement next;

    public PageObjectExample(WebDriver driver) {
        PageFactory.initElements(driver, this);
    }

    public void login(String email, String password) {
        this.email.sendKeys(email);
        this.password.sendKeys(password);
        next.click();
    }
}

You can see on lines 3 to 10, that we are adding each element in the page as a WebElement field, using the @FindBy annotation to express its locator.

On line 13 you can see the usage of the PageFactory class using the initiElements, which will, behind the scenes, translate each element into driver.findElement(By...).

On lines 17 to 19, you can see the usage of the element itself without the driver.findElement(By…) because it was already one by the PageFactory class. This reduces the amount of code and verbosity you would possibly have.

Please, also read this definition of Page Factory from the SeleniumHQ wiki: https://github.com/SeleniumHQ/selenium/wiki/PageFactory

The common problem during the Page Objects modeling

The main problem is the element wait strategy. For instance, we have three different ones in Selenium WebDriver and the recommended ones are the Explicitly Wait and the Fluent Wait. The Implicitly Wait is, nowadays, considered a bad practice.

We have two main cases to apply a waiting strategy in the Page Objects: in the class constructor or the action methods.

Just a heads-up: we only use either Explicitly or Fluent Waits when necessary. Not for any action, we create!

Wait for an element in the constructor

Normally this approach is used when you need to make sure the main element you will interact with is loaded into the page. You could replace this with the wait in the action method, of course, but this approach “tells” you explicitly that you are waiting for the element before proceeding with all the actions.

This is a simple example:

public class PageObjectExample {

    private WebDriver driver;

    @FindBy(id = "email")
    private WebElement email;

    @FindBy(id = "password")
    private WebElement password;

    @FindBy(name = "next")
    private WebElement next;

    public PageObjectExample(WebDriver driver) {
        this.driver = driver;

        PageFactory.initElements(driver, this);
        new WebDriverWait(driver, Duration.of(5, ChronoUnit.SECONDS))
            .until(ExpectedConditions.visibilityOf(email));
    }

    public void login(String email, String password) {
        this.email.sendKeys(email);
        this.password.sendKeys(password);
        next.click();
    }
}

Note that, on lines 18 and 19, there’s an Explicitly Wait waiting until the email field is visible on the page.

Wait for an element in the action methods

When an element that you are about to interact with is not present/visible/clickable we add an Explicitly Wait to make sure test integrity. We simply add an Explicitly Wait before the real action.

This is a simple example:

public class PageObjectExample {

    private WebDriver driver;

    @FindBy(id = "email")
    private WebElement email;

    @FindBy(id = "password")
    private WebElement password;

    @FindBy(name = "next")
    private WebElement next;

    public PageObjectExample(WebDriver driver) {
        PageFactory.initElements(driver, this);
    }

    public void fillEmail(String email) {
        new WebDriverWait(driver, Duration.of(5, ChronoUnit.SECONDS))
            .until(ExpectedConditions.visibilityOf(this.email));

        this.email.sendKeys(email);
    }
}

You can see in lines 19 to 20, that we are waiting for the email field to be visible before filling in a value on it.

How to reduce verbosity for the PageFactory and Waiting strategy

We can use two techniques:

Use the AjaxElementLocatorFactory in the PageFactory.initiElements to apply an automatic explicit wait
Use the inheritance to avoid duplicated code for the PageFactory.initiElements usage

What’s the AjaxElementLocatorFactory

This class in Selenium WebDriver adds a lazy load approach in the Page Factory class. It uses an Explicitly Wait when loading the element, which means when we use it, for at least de defined time you will express.

The usage of this class will reduce the necessity of explicitly waiting for elements in most cases. Of course, you might face cases where you need to add an Explicitly wait.

The regular code within the combination of the PageFactory class will look like this:

public class PageObjectExample {

    private WebDriver driver;

    // WebElements ignored

    public PageObjectExample(WebDriver driver) {
        PageFactory.initElements(new AjaxElementLocatorFactory(driver, 5), this);
    }
}

You can see that we are instantiating the AjaxElementLocatorFactory inside of the PageFactory.initElements. This class needs the driver instance and the timeout in seconds.

This would be added in each Page Object class you have, but we have a better way to avoid it.

Using inheritance in our favor

Instead of adding this code snippet to each Page Object, we can create an abstract class to handle this job.

public abstract class AbstractPageObject {

    private WebDriver driver;

    protected AbstractPageObject(WebDriver driver) {
        PageFactory.initElements(new AjaxElementLocatorFactory(driver, 5), this);
    }
}

Note we have an abstract class that will init the elements for the provided driver instance, adding the AjaxElementLocatorFactory and waiting until 5 seconds for the element, if necessary.

Now we need to extend it in the Page Object class, adopting the constructor and invoking super to use the one from the abstract class:

public class PageObject extends AbstractPageObject {

    // WebElements ignored

    protected PageObject(WebDriver driver) {
        super(driver);
    }

   // action steps ignored
}

Concrete example

In the selenium-java-lean-test-architecture project you can see the following implemented structure:

The class AbstractPageObject has the Page Object initialization within the AjaxElementLocatorFactory
The driver inside the AbstractPageObject is managed by the DriverManager class which creates a thread instance to guarantee the parallel execution
The AbstractPageObject class is being used in the NavigationPage. Note that we don’t have the constructor using the super to send the driver instance as the DriverManager is taking care of the driver
The other page object classes are using the NavigationPage, so indirectly they are also using the AbstractPageObject class

The best way to create browser instances using the Factory Pattern, Java, and Selenium WebDriver

Elias Nogueira — Sat, 20 Aug 2022 09:41:19 +0000

Introduction

This article belongs to a series of 3 posts explaining how to use the Factory Pattern to create different browser instances for either local or remote execution using Selenium WebDriver.

You can find the following previous article:

This one will refer to some explanations and code from the previous one, but don’t be afraid, you will understand everything.

General explanation

Can you imagine you can implement a good approach to create multiple browser instances with only two classes?

The BrowserFactory and the power of enums

We already know that the Enum Types have constant and can have methods.

The BrowserFactory class is an enum with the list of supported browsers (constants) for the implementation I’ve created: Chrome, Firefox, Edge, and Safari.

We can add an extra function on this enum with methods, but instead of creating the regular ones we will make each constant implement two methods: createDriver() for the local execution and getOptions() for the remote execution. In order to do so, we must implement abstract methods inside the enum. Take a look at the example:

public enum BrowserFactory {

    CHROME {
        @Override
        public WebDriver createDriver() {
            WebDriverManager.getInstance(DriverManagerType.CHROME).setup();

            return new ChromeDriver(getOptions());
        }

        @Override
        public ChromeOptions getOptions() {
            ChromeOptions chromeOptions = new ChromeOptions();
            chromeOptions.addArguments("--start-maximized");
            chromeOptions.addArguments("--disable-infobars");
            chromeOptions.addArguments("--disable-notifications");
            chromeOptions.setHeadless(configuration().headless());

            return chromeOptions;
        }
    };

    public abstract WebDriver createDriver();
    public abstract AbstractDriverOptions<?> getOptions();
}

On lines 23 and 24 we have two abstract methods. Each enum constant needs to implement the abstract method.

On lines 5 to 9, there’s the implementation of the createDriver() method creating a local browser instance using the WebDriverManager library. Note that the new browser instance is using the getOptions() and I will explain it in a minute.

You can see that line 24 has the AbstractDriverOptions with an unknown generic, placed with ? as the wildcard. It returns this class because each internal Selenium WebDriver remote browser implementation extends this class, making it easier to set the correct object for the remote instance creation. You can see this by accessing the AbstractDriverOptions Javadoc in the section “Direct Known Subclasses“

Lines 12 to 20 show the specific ChromeOptions we must set for the remote execution, as the remote class is called “option” which must be set.

And why we have the getOptions() method being used in the createDriver()? To automatically set any option we want to. The option classes do not need the browser driver set as needed in the local execution.

The full BrowserDriver implementation can be found at https://github.com/eliasnogueira/selenium-java-browser-factory/blob/master/src/main/java/com/eliasnogueira/driver/BrowserFactory.java

The DriverFactory class

This class is responsible to manage the local or remote instances because we need different code approaches using Selenium WebDriver. We have two main methods: the createInstance() for the local execution and the createRemoveInstance() for the remote execution.

Creating the local instance

The local instance means that we will run the tests locally in the browser installed on the machine.

The method createInstance() has the browser as the method parameter that the BaseTest class will use to determine which browser will be instantiated.

The browser value attribute is transformed in the Target enum and then used in the switch-case.

public class DriverFactory { 

  public WebDriver createInstance(String browser) {
        Target target = Target.valueOf(configuration().target().toUpperCase());
        WebDriver webdriver;

        switch (target) {
            case LOCAL:
                webdriver = BrowserFactory.valueOf(browser.toUpperCase()).createDriver();
                break;
            case REMOTE:
                webdriver = createRemoteInstance(BrowserFactory.valueOf(browser.toUpperCase()).getOptions());
                break;
            default:
                throw new TargetNotValidException(target.toString());
        }
        return webdriver;
    }
}

When the target is LOCAL the BrowserFactory class will call the createDriver() method for the browser we have set. This approach removes the necessity to have the switch-case for each browser as the browser value will be transformed in the enum constant. Less code, more readable code!

You can see this happening on lines 8 to 10.

Remember that the browser to use locally is set in the general.properties class.

Creating the Remote instance

It works similar to the local approach when the code determines if the execution is local or remote. Line 12, in the previous code snippet, shows that the BrowserFactory will call the getOptions() method based on the browser we have set. With this, we have the browser options object. Now it’s time to create the real remote instance.

private RemoteWebDriver createRemoteInstance(MutableCapabilities capability) {
    RemoteWebDriver remoteWebDriver = null;
    try {
        String gridURL = String.format("http://%s:%s", configuration().gridUrl(), configuration().gridPort());

        remoteWebDriver = new RemoteWebDriver(new URL(gridURL), capability);
    } catch (java.net.MalformedURLException e) {
        logger.log(Level.SEVERE, "Grid URL is invalid or Grid is not available");
        logger.log(Level.SEVERE, String.format("Browser: %s", capability.getBrowserName()), e);
    } catch (IllegalArgumentException e) {
        logger.log(Level.SEVERE, String.format("Browser %s is not valid or recognized", capability.getBrowserName()), e);
    }

    return remoteWebDriver;
}

The createRemoteInstance() method expects a MutableCapability object, which is the same as the browser option object because the AbstractDriverOptions extends the MutableCapabilities class.

To create a remote browser instance we must use the RemoteWebDriver class, adding as a parameter the target remote machine (or a grid) and the capability, which is the browser with the options.

On line 4 the URL for the remote machine is created based on the information we have in the grid.properties file. On line 6 the remote instance is created. The rest of the code is the exception handler, necessary to know what happened if any problem occurs during the remote instance creation.

How to associate this with the test?

First, it’s a good practice to have a BaseTest class managing the general pre and post-conditions. The BaseWeb class has the pre-conditions, as a JUnit @BeforeEach annotation, the following:

Line 8: getting the configurations, which means all the information from the properties file
Line 10: the creation of the browser instance based on the browser set in the properties file
Line 11: setting the URL to start the test

public class BaseWeb {

    protected WebDriver driver;
    protected Configuration configuration;

    @BeforeEach
    public void preCondition() {
        configuration = configuration();

        driver = new DriverFactory().createInstance(configuration().browser());
        driver.get(configuration().url());
    }

    @AfterEach
    public void postCondition() {
        driver.quit();
    }
}

The main part related to this approach is in line 10, where the DriverFactory class will know, internally, if the execution is local or remote based on the value set for the target property set in the general.properties file. The browser was also set in this file but through the browser property will be used to create the local browser instance or the remote instance.

The tests must extends the BaseWeb to work properly.

class BookRoomWebTest extends BaseWeb {

    @Test
    void bookARoom() {
        driver.navigate().to(configuration.url() +
                "how-to-create-lean-test-automation-architecture-for-web-using-java-libraries");

        assertThat(driver.findElement(By.cssSelector(".hestia-title.title-in-content")).getText()).
                isEqualTo("How to create Lean Test Automation Architecture for Web using Java libraries");
    }
}

How to run this project in remote machines

If you would like to give it a try the complete project selenium-java-browser-factory has a docker-compose file that will start a Selenium 4 Grid with Chrome, Firefox, and Edge browsers. So you will be able to run remote instances.

To exercise this, please follow these steps:

Start Docker
Navigate, through your Command-Line/Terminal app to the project root folder
Run docker-compose up command
Access http://localhost:4444 to see the Selenium Grid page with the browsers available (Chrome, Edge, and Firefox)
In the general.properties file, change the target attribute value to remote
- the grid.properties file in src/main/java/resources already have the values to connect to a local grid
Run the BookARoomWebTest
- you can go to the Selenium Grid dashboard and click on the Sessions tab
- as soon as the test starts a session related to the browser in use will be listed

The complete example

You can navigate to the following GitHub repo to see a complete and functional example in the branch local-remote-example. Spare some time to look at the new classes added and understand how it was structured.

https://github.com/eliasnogueira/selenium-java-browser-factory/tree/basic-example

How to use the Factory design pattern to create browser instances: local and remote approach

Elias Nogueira — Mon, 20 Jun 2022 14:53:15 +0000

Introduction

In the previous article [How to use the Factory design pattern to create browser instances: the simple approach
(http://www.eliasnogueira.com/how-to-use-the-factory-design-pattern-to-create-browser-instances-the-simple-approach/), you have learned how to implement it. I’ve named it “simple” because the code created runs only locally, which is the simplest and most elegant way of using Java to do it.

Code explanation

To make this post/tutorial as short as possible I will refer, through links, to the existing code implementation where you can access and understand more about the solution applied.

Difference between local and remote execution

Local execution means the usage of the browser installed on the same machine you will run the tests, so we need the web browser and the browser drivers.

Remote execution means the execution of the tests in a different machine from the one you will trigger. This “machine” is actually any resource as a different real machine (bare-metal), a Docker container, or a remote service (E.g: SauceLabs, BrowserStack).

The technical differences in Selenium

In the local execution, we directly use the browser instance. Don’t forget you need also the browser driver and it can be easily configured using the WebDriverManager library.

// setting up the browser driver with the WebDriverManager library
WebDriverManager.getInstance(CHROME).setup();

// creating the local browser instance
WebDriver driver = new ChromeDriver();

The WebDriverManager will set up the Chrome driver and Selenium will look a the local Google Chrome installation and will use it to run your tests.

But, for the remote execution, things are a little bit different. You will need to:

have the target machine URL
use the RemoteWebDriver class, instead of the browser class with the following parameters:
- the URL for the target machine
- the “capability” to run

Code organization

Similar to the How to use the Factory design pattern to create browser instances: the simple approach article shows how to create a factory class to manage different browsers to run locally, we have now to create a way to determine when to run locally and when to run in a remote machine.

This is the class diagram that we will work on.

Diagram explanation

manager package

The IDriveManager is an interface that has the methods to implement in the manager classes. The manager classes have the implementation for the local, and now, remote execution.
The local execution is done by the method createDriver() and the remote execution is done by the getOptions() method. I will explain more about it later.

driver package

The DriverFactory class is the one responsible to know if the execution will be either local or remote. We manage this through a property value. Based on the target environment we will instantiate either the LocalDriverFactory or the RemoteDriverFactory. This class implemented the interface IDriverFactory.

factory package

The LocalDriverFactory class is responsible to create the local browser instance using the createDriver() method from the manager classes.

The RemoteDriverFactory class is responsible to create the remote browser execution using the getOptions() from the manager classes. The internal private method createRemoteInstance() will connect to the remote machine before the creation of the browser instance.

Implementation

I will explain here how to evolve code based on the simple approach. The following sub-items will explain it.

1. Manager the local and remote execution

New properties

The first thing we need to create is a way to run the test using either a local or remote machine. For the remote execution, we will need to parameterize the URL and port we will connect our tests. We also need to add a way to say when we need to execute it as local or remote.

The approach I’ve created is to add a new grid.properties file to add the Selenium Grid URL and port

# grid url and port
grid.url = localhost
grid.port = 4444

Note: the file is named grid, as well as the properties because the way to run Selenium tests in different machines implies the Selenium Grid features.

We also need to update the general.properties file to have the local property to tell, somehow, we can execute it locally or remote. Line 2 shows the new property.

Finally, in the Configuration class, you will see the new association to the new properties created in the gird.properties and general.properties. Also the load of the grid.properties in the @Config.Sources annotation from the Owner library.

New class to manage the local and remote execution

The previous DriverFactory was managing the local execution. Now, to maintain a better naming consistency, we are changing it to manage the execution into local or remote. It has a simple switch-case to instantiate the correct internal class.

public class DriverFactory implements IDriverFactory {

    @Override
    public WebDriver createInstance(String browser) {
        Target target = Target.valueOf(configuration().target().toUpperCase());
        WebDriver webdriver;

        switch (target) {
            case LOCAL:
                webdriver = new LocalDriverFactory().createInstance(browser);
                break;
            case REMOTE:
                webdriver = new RemoteDriverFactory().createInstance(browser);
                break;
            default:
                throw new TargetNotValidException(target.toString());
        }
        return webdriver;
    }

    enum Target {
        LOCAL, REMOTE
    }
}

Lines 21 to 23 show an internal enum named Target which has LOCAL and REMOTE as possible values.

Line 5 loads the target property from the general.properties file and converts it to Target enum, whereas line 8 applies a switch statement in the enum.

When the execution is from the local, the LocalDriverFactory class is in use to create the WebDriver instance based on the browser set in general.properties file. When the execution is remote the RemoteDriverFactory class is in use. The LocalDriverFactory class is the same as the previous DriverFactory from the basic-example branch.

New LocalDriverFactory

This class is identical to the previous DriverFactory. You can take a look at the implemented LocalDriverFactory class.

New RemoteDriverFactory class

We now have a new class to instantiate the different browsers for the remote execution. I will assume here you are already familiar with Selenium Grid, so I will skip the explanation of the code that creates the RemoteWebDriverInstance. If you need to learn more about it, please read the official Selenium Grid documentation and the code I’ve implemented for this solution.

Basically, we will have the same switch-case strategy for each browser compared to the LocalDriverFactory, but instead of instantiating the local browser, we need to instantiate the remote one.

@Override
public WebDriver createInstance(String browser) {
    MutableCapabilities capability;
    BrowserList browserToCreate = BrowserList.valueOf(browser.toUpperCase());

    switch (browserToCreate) {
        case CHROME:
            capability = new ChromeDriverManager().getOptions();
            break;
        case FIREFOX:
            capability = new FirefoxDriverManager().getOptions();
            break;
        case EDGE:
            capability = new EdgeDriverManager().getOptions();
            break;
        case SAFARI:
            capability = new SafariDriverManager().getOptions();
            break;
        default:
            throw new BrowserNotSupportedException(browser + "is not supported!");
    }

    return createRemoteInstance(capability);
}

Note that the RemoteDriverFactory class is now using the getOptions() method instead of the createDriver() from each manager driver class.

2. Additional getOptions() method in the driver manager classes

Each driver manager class will have, additionally, a new method to use when the execution is remote. As the RemoteWebDriver does not accept a browser instance directly, but a MutableCapabilities class, we need to specify the correlated option class of the browser.

Each browser has its own *Options class, like ChromeOptions, FirefoxOptions, and so on. Those classes exist for the remote execution and have pre-configured options as their identification plus methods that can extend their features. Internally the *Options classes have a hierarchy dependency on the MutableCapabilities class.

What we need to do is to add the getOptions() methods to each DriverManager class. This method must instantiate the related browser option and can add more features.

@Override
public ChromeOptions getOptions() {
    ChromeOptions chromeOptions = new ChromeOptions();
    chromeOptions.addArguments("--start-maximized");
    chromeOptions.addArguments("--disable-infobars");
    chromeOptions.addArguments("--disable-notifications");
    chromeOptions.setHeadless(configuration().headless());

    return chromeOptions;
}

The code above shows the getOptions() method for the ChromeDriverManager class where we are:

creating an instance of its option on line 3
adding additional arguments to the browser on lines 4 to 6
setting it as headless based on the headless configuration value present in the general.properties
returning the object instantiated to be used as the RemoteWebDriver

You can see all the implemented DriverManager classes in the manager package.

How to run

The execution to local or remote will is based on the target property value in the general.properties file. We know that when the execution is local the DriverFactory will use the LocalDriverFactory class to create the local browser instance and when the execution is remote the DriverFactory will use the RemoteDriverFactory to create a remote browser instance.

Running it locally

Follow these steps:

Open the general.properties file located in src/test/java/resources
Change the target property value to local
Change the browser property value to any browser you have installed
Run the BookARoomWebTest class

The expected result is the test being executed in your local machine for your set browser. This is the same way we did in the previous post.

Running it in a remote machine

Now things get more interesting. We need to find a way to execute the test on a remote machine. As written before a remote machine can be a physical or virtual machine existent in your network or a cloud provider. To be able to run it on your machine right now the Docker is one of your best choices.

The project has a docker-compose.yml file which will start a full Selenium Grid infrastructure containing the sessions, distributors, router, event bus, and the browsers. You can learn more about the Selenium Grid 4 on their official page and in their GitHub project.

As a pre-condition, you need to have Docker installed on your machine and then follow these steps:

Start Docker
Navigate, through your Command-Line/Terminal app to the project root folder
Run docker-compose up command
Access http://localhost:4444 to see the Selenium Grid page with the browsers available (Chrome, Edge, and Firefox)
In the general.properties file, change the target attribute value to remote
- the grid.properties file in src/main/java/resources already have the values to connect to a local grid
Run the BookARoomWebTest
- you can go to the Selenium Grid dashboard and click on the Sessions tab
- as soon as the test starts a session related to the browser in use will be listed

The complete example

https://github.com/eliasnogueira/selenium-java-browser-factory/tree/basic-example

The best way to add a Request Body to a POST request using Rest-Assured

Elias Nogueira — Wed, 08 Dec 2021 11:54:10 +0000

Introduction

One of my activities is to review the Quality Engineers’ technical assignment. We ask the candidate to automate at least 2 features in the API and Web layers.

Most of the candidates are delivering the API test automation solution using Java and Rest-Assured, which is the same combination we use. Of course, we are evaluating it based on the candidate experience in general which includes the whole testing experience, test automation experience, and libraries experience.

Rest-Assured is a well-known library to use for API test automation, simple to use, and fast. But I can see one gap in most of the solutions they delivered: the lack of knowledge about the library. It’s in different ways and one is unanimous: the use of either String or HashMap in the requests.

The intention here is to tell you which way you can have most of the professional benefits using Rest-Assured as I refer it here as the recommended approach.

The test implementation

To not add some complexity here and stay focused on our main goal we will use the https://reqres.in/, a mock API ready to respond to any request for testing purposes.

As the goal is sent a request with an object with it, sometimes referred to as the payload object, we will use the following endpoint:

Given the request body, we must send the name and job attributes, which are text (strings).

Working approaches

String concatenation (not recommended)

The string concatenation approach consists of creating a string with the same output as JSON.

Note that, on line 5, the String user is a string concatenation of the JSON Object we must send into the request.
As we are using Java we must escape all the double quotes, as a string starts and ends with it.
The validation on lines 15 and 16 must be hardcoded as well because there is no way to retrieve the data sent because it is a string.

class PostTest {

    @Test
    void postUsingStringConcatenation() {
        String user = "{\"name\":\"Elias\",\"job\":\"Principal Engineer\"}";

        given().
            contentType(ContentType.JSON).
            body(user).
        when().
            post("/users").
        then().
            statusCode(HttpStatus.SC_CREATED).
            body(
                "name", is("Elias"),
                "job", is("Principal Engineer"),
                "id", notNullValue(),
                "createdAt", notNullValue()
            );
    }
}

We can see clearly that this approach works but will give you a lot of maintenance and trouble. You must avoid it.

Advantages

none

Disadvantages

hard to read
hard to maintain
looks unprofessional
does not allow easy object update (properties or values)

Using a HashMap (not recommended, but acceptable)

You can see this approach described in the Rest-Assured documentation but it does not mean this is the best approach.

This approach consists of creating a HashMap object to send it on the request.
As a HashMap as a key-value map where the key is the attribute and value is the attribute value, it seems a good candidate to use.

On line 5 we are using a Map typing the attribute as String and the value as an Object. This is not the case but you know that a JSON value can be an object.

On lines 6 and 7 we are adding the key (attribute name) and value (the value we want to send).

Behind the scene the binding library will transform the HashMap into a JSON object like this:

{ "name": "Elias", "job": "Principal Engineer" }


class PostTest {

    @Test
    void postUsingHashMap() {
        Map<String, Object> user = new HashMap<>();
        user.put("name", "Elias");
        user.put("job", "Principal Engineer");

        given().
            contentType(ContentType.JSON).
            body(user).
        when().
            post("/users").
        then().
            statusCode(HttpStatus.SC_CREATED).
            body(
                "name", is(user.get("name")),
                "job", is(user.get("job")),
                "id", notNullValue(),
                "createdAt", notNullValue()
            );
    }
}

This approach is better than the String concatenation and looks more professional, but it’s not the best one…

Advantages

Give you a clear vision of the attributes and values
Can enable you to go further and create a class placing the objects, like a test data factory approach

Disadvantages

It’s not flexible to create complex objects, as you need to create several HashMap
An update can cause confusion as you need to set the value in the same key. E.g: put("name", "New value")
Any typo in the keys will lead to errors that might be hard to find. Eg: put("name", "Elias") as we have a typo on “o”

Recommended approach

Using the Object Mapping

Rest-Assured supports mapping Java objects to and from JSON and XML. This means you can create a Java object and Rest-Assured will try to match all the attributes in the class with either the request or response.

To be able to use it you need to explicitly add an object mapping library in your classpath. For JSON you need to have either Jackson, Jackson2, Gson, or Johnzon in the classpath and for XML you need JAXB.

As we are sending information into the request let’s talk about first the Serialization.

Object Mapping Serialization

https://github.com/rest-assured/rest-assured/wiki/Usage#serialization

Rest-Assured will use one of the object mapping libraries you added into your classpath to bind the attributes from a Java object into the request body. We already know that we required, for this example, the name and job attributes to post an user. The Java object will look like this:

public class User {

    private String name;
    private String job;

    public User(String name, String job) {
        this.name = name;
        this.job = job
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

      public String getJob() {
        return job;
    }

    public void setJob(String job) {
        this.job = job;
    }
}

In the test, we need first to create the User object with the data we would like to use. You can see this on line 6.

Now we simply use the user object into the body(object). It’s important to explicitly set the Content-type. You can see it in lines 9 and 10.

class PostTest {

    @Test
    void postUsingObjectMapping() {

        User user = new User("Elias", "Principal Engineer");

        given().
            contentType(ContentType.JSON).
            body(user).
        when().
            post("/users").
        then().
            statusCode(HttpStatus.SC_CREATED).
            body(
                "name", is(user.getNama()),
                "job", is(user.getJob()),
                "id", notNullValue(),
                "createdAt", notNullValue()
            );
    }
}

Rest-Assured will do the magic when the body() method uses an object where it will try to find the required request attribute names into the object used.

The request needs the name and job attributes, as text. As the User object has the name and job attributes as String (text) RestAssured will to the automatic value match. Both combinations of attribute and value match are called Object Serialization.

Important note

You might face the following exception, which is super self-explanatory:

java.lang.IllegalStateException: Cannot serialize object because no JSON serializer found in the classpath. Please put Jackson (Databind), Gson, Johnzon, or Yasson in the classpath.

at java.base/jdk.internal.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
at java.base/jdk.internal.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:62)
at java.base/jdk.internal.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
at java.base/java.lang.reflect.Constructor.newInstance(Constructor.java:490)
at org.codehaus.groovy.reflection.CachedConstructor.invoke(CachedConstructor.java:72)
at org.codehaus.groovy.runtime.callsite.ConstructorSite$ConstructorSiteNoUnwrapNoCoerce.callConstructor(ConstructorSite.java:105)
at org.codehaus.groovy.runtime.callsite.CallSiteArray.defaultCallConstructor(CallSiteArray.java:59)
at org.codehaus.groovy.runtime.callsite.AbstractCallSite.callConstructor(AbstractCallSite.java:263)
at org.codehaus.groovy.runtime.callsite.AbstractCallSite.callConstructor(AbstractCallSite.java:277)
at io.restassured.internal.mapping.ObjectMapping.serialize(ObjectMapping.groovy:160)
at io.restassured.internal.mapping.ObjectMapping$serialize.call(Unknown Source)
at org.codehaus.groovy.runtime.callsite.CallSiteArray.defaultCall(CallSiteArray.java:47)
at org.codehaus.groovy.runtime.callsite.AbstractCallSite.call(AbstractCallSite.java:125)
at io.restassured.internal.RequestSpecificationImpl.body(RequestSpecificationImpl.groovy:751)

This will happen if you don’t add any library to serialize the objects. You need to explicitly add one of the following libraries:

It might be the case you are not using one of these libraries, having a successful test execution. Some dependencies can have one of these as an internal dependency, and you can figure out it simply by running mvn dependency:tree and trying to look at one of the libraries mentioned.

Examples

In the restassured-complete-basic-example project, you can find the Simulation model, which models the request and response for the Simulations API.

The model is in use by the SimulaitonDataFactory to create the Simulation data, necessary to make the POST request using the body parameter.

The SimulationFunctionalTest has tests using different HTTP methods. You can see the createNewSimulationSuccessfully, invalidSimulations, and simulationWithDuplicatedCpf test methods using the Simulation object to POST a body using it instead of Strings or any other mentioned approach.

Reasons to avoid RandomStringUtils for test data generation

Elias Nogueira — Fri, 15 Oct 2021 15:24:24 +0000

Which problem do we want to solve?

We will try to solve one of the worst practices used on tests at any level: fixed/hard-coded data.

I want to avoid as much as possible any manual pre-action before I can run my tests and, because of that, I try to avoid as well the usage of static files (CSV, TXT, XLS, JSON).

Here we will see a common usage from Java developers: the RamdomStringUItils and how it might not be the best choice for automatic data generation.

By the way, I recommend the automatic data generation in the tests using the Test Data Factory approach, and you can find an example here in my blog: Test Data Factory: Why and How to Use.

The examples described here are simple, without the usage of the Test Data Factory, and will show you why the RandomStringUtils might not be the best approach.

Example

We will automatically generate data to a Customer object with has the following criteria:

Attribute	Type	Constraints
id	int	Not null
name	String	Not null and size between 2 and 50 characters
profession	String	Not null and size between 2 and 30 characters
accountNumber	String	Not null and size as 18 characters
address	String	Not null and size between 2 and 50 characters
phoneNumber	String	Not null and size between 11 and 14 characters
birthday	Date	Not null

To reduce the number of tests, the key point is to generate valid data given the constraints. In a professional environment, we would implement the tests for the edge cases as well.

Think about this Customer data as an object used in any test level (unit, integration, service, UI).

What does the RandomStringUtils class do?

RandomStringUtils is a class from the Apache Commons Lang library that generates random Strings based on different conditions like:

length
letters
numbers
alphanumeric
ASCII
numeric
print

It’s a static class where you can directly generate any String, so it’s super handy!

See the example below, where you can generate a different set of random data.

public class RandomStringUtilsExample {

    public static void main(String[] args) {
        // returns a String with 5 numbers
        // example 82114
        RandomStringUtils.randomNumeric(5);

        // returns an alphanumeric String with length as 30 mixing upper and lower cases
        // example gQ6RB8MiwKOg9O3qnHFo7I3jilHoIy
        RandomStringUtils.randomAlphanumeric(30);
    }
}

What is the result of using RandomStringUtils class?

Let’s first take a look at the code example implementing the usage of RamdonStringUtils:

in line 7 is using the RandomStringUtils.randomNumeric() method to generate an int value and, to make it, possible we are parsing the String into Int using Integer.valueOf()
the lines 8 to 12 uses RandomStringUtils.randomAlphanumeric() to generate alphanumeric data
line 13 has a fixed date as now (today) because RandomStringUtils generates only Strings

class BasicExampleTest {

    @Test
    @DisplayName("Data validations using RandomStringUtils")
    void randomStringUtils() {
        CustomerData customerData = CustomerData.builder().
                id(Integer.valueOf(RandomStringUtils.randomNumeric(10))).
                name(RandomStringUtils.randomNumeric(50)).
                profession(RandomStringUtils.randomAlphanumeric(30)).
                accountNumber(RandomStringUtils.randomAlphanumeric(18)).
                address(RandomStringUtils.randomAlphanumeric(50)).
                phoneNumber(RandomStringUtils.randomAlphanumeric(14)).
                birthday(new Date()).
                build();
    }
}

The output of the test execution, if we print or inspect the customerData object, is:

{
  "id": 1335130963,
  "name": "GGXS19kN6kSuzHwW6T0YjJCxUaIyKKmAaUdQH51gdUAtt1TwqY",
  "profession": "0kk8HSiFgCUVfLzbD3PyR6cn8j0LH3",
  "accountNumber": "PqvekXb9ekRAJi3ypy",
  "address": "90lqP2LHnQMWtmMP8vasO3BR5dsICIL85u5sJ0yjGKWXxCkFsj",
  "phoneNumber": "OpoJ3tOE53woy9",
  "birthday": "Sep 26, 2021, 10:01:10 PM"
}

We could successfully generate the necessary data! Yay!

What does JavaFaker do?

[]JavaFaker](https://github.com/DiUS/java-faker) is an open-source library based on Faker to generate fake data.

There’ are some nonsense data generation there like Avatar, Friends, etc.., but there’s also a good set of objects that can generate data in certain conditions that matches our necessities.

I invite you to take a look at the GitHub repo and see the different objects to generate data.

What is the result of using JavaFaker?

The code implementation to generate data using the CustomerData class is:

in line 9, the number() method is in use to generate a random number
in line 10, the name() method is in use to generate a full name
in line 11, the company() is in use to generate a profession
in line 12, the finance() method is in use to generate a valid IBAN for the Netherlands country
in line 13, the address() method is in use to generate a full street address
in line 14, the phoneNumber() method is in use to generate a cell phone number
in line 15, the date() method is in use to generate birthday data with the age between 18 and 90

class BasicExampleTest {

    @Test
    @DisplayName("Data validations using faker library")
    void faker() {
        Faker faker = new Faker();

        CustomerData customerData = CustomerData.builder().
                id((int) faker.number().randomNumber()).
                name(faker.name().name()).
                profession(faker.company().profession()).
                accountNumber(faker.finance().iban("NL")).
                address(faker.address().streetAddress()).
                phoneNumber(faker.phoneNumber().cellPhone()).
                birthday(faker.date().birthday(18, 90)).
                build();
    }
}

The output of the test execution, if we print or inspect the customerData object, is:


{
  "id": 520543,
  "name": "Tena Pagac",
  "profession": "photographer",
  "accountNumber": "NL07HUUN1518167413",
  "address": "12672 Romaguera Tunnel",
  "phoneNumber": "(561) 638-5813",
  "birthday": "Mar 5, 1982, 10:29:18 AM"
}

We could successfully generate the necessary data! But let’s not focus on the differences.

Comparing both approaches

There’re two aspects I would like to consider to choose between one approach or another:

legibility of future troubleshooting (log analysis)
easy data creation in different criteria

We can see the main differences comparing the data result side by side (click on the image to expand it):

Legibility of future troubleshooting (analysis)

The regular activity for an engineer that writes code is troubleshooting: we constantly see the logs and debug the application to understand current and future problems in the code.

Now imagine yourself looking at the CustomerData object where the data was filled in with the RandomStringUtils approach: it’s hard to correlate the data you have with a list of objects you might get or even taking a look at the data used inside a log file.

Easy data creation in different criteria

For most of the attributes present in the CustomerData class, you can use RandomStringUtils to generate the different criteria. For example, you can easily set 51 characters to the name attribute and expect a failing constraint validation using RandomStringUtils.randomAlphanumeric(51);

For more specialized data, like phone number and date you need a proper library, and JavaFaker can generate both data.

In this way, we can make the process easier by adopting one library.

Considerations

Of course, I’m put more emphasis on the JavaFaker library because we have almost everything we need to generate data, but it does not exclude a possible necessity to use the RandomStringUtils class or any other class placed in the Apache Commons library.

The main consideration here is the ability to generate all the possible data you need using a single source of truth without reinventing the wheel, as well as the indirect benefits it will show during the troubleshooting process.

Examples

The avoid-random-string-utils project shows a basic example comparing RandomStringUtils vs JavaFaker.

The restassured-complete-basic-example project has a factory data class to generate all the necessary data in different conditions. It’s a good real-world example.

Thoughts on Selenium 101 Certification from LambdaTest

Elias Nogueira — Tue, 23 Mar 2021 21:37:15 +0000

Introduction

LambdaTest created their different Certifications delivering them at free cost! They have a detailed announcement on their blog.

I took the Selenium 101 exam and I passed. I will share my thought with you.

My thoughts

First of all, I don’t believe that much about certifications that don’t have a way to make you practice it.

I do recommend for everyone who wants to take testing/quality paid certifications like ISTQB or related the following: invest your time and money into courses, books, and practicing the tech skills most of the open positions in the market required. It will worth your time, money, and dedication.

I’m not telling you to give up your current focus on those certifications if you have. I truly believe you will learn something valuable. My main concern is regarding the experience you can have from different sources and get prepared for your dream job.

What about the LambdaTest certification?

I would say it worth your time. I liked it because:

there are multiple-choice questions
there is an assignment task
it’s free!

Part 1: Multiple choice questions

You need to select the correct questions regarding a topic. The same procedure that all certification has. There are some questions I think don’t belong/fit into the Selenium knowledge base like questions about Apache POI and Excel files, regexp, and Selenium 1.

I might consider the Selenium 1 questions valid for those that have legacy code wrote down in these versions, but I would say it’s unusual.

Part 2: Assignment task

I loved this one. They will give you a web app link and the e2e scenario to automate. A real e2e scenario.

There’s only one thing I think is not that valid to reproduce, which is a download part, but you might see a weird requirement from your PO to test if the PDF report can be download (!!!).

You must deliver the assignment task in a “short” period, so get prepared.
Btw, it should be functional and run because they will do it!

I would say to deliver the assignment in a functional way rather than the most beautiful code you can create with some design patterns. The focus is to show that you know how to automate an e2e scenario.

Are you ready?

Are you ready to give it a try? If you are an experienced engineer you can “play” with the assignment and even learn something new. If you are learning Selenium this is a good way to validate your knowledge.

100 Best Tips about Java Testing tools

Elias Nogueira — Sun, 07 Feb 2021 13:25:02 +0000

I started a new initiative 100 days ago: post daily tips about Testing tools you can use with Java!

I posted it on Twitter and LinkedIn.
By the way, don’t hesitate to follow/add me!

What are the tools?

I have covered the following tools that can give you complete test coverage and deliver bug-free high-quality software.

Where the tips based?

Believe me or not: from the official tool documentation!
I’ve learned a lot from the official documentation. I always start from there.

Each tip has a link for the feature documentation. Don’t forget to click on it!

Where can I find the tips?

I’ve created a simple webpage where you can see all the tips or filter them by one of the tools.

https://eliasnogueira.github.io/100-tips-testing-java

Would you like to see how I created the web page? (please don’t judge me, I’m not a frontend engineer 😛 ). You can access the following GitHub repo https://github.com/eliasnogueira/100-tips-testing-java