Introduction

In this article we will continue and spin from the previous article about generating OpenAPI with Spring Boot for multipart endpoint and uploading files through it. We strongly recommend reading the last article if you want to import more than one file. But in this article, we will focus only on the optional import of a single file.

But instead of multiple files, we will try to upload only one file and one serialized object, for example, the information about the new user.

We will also show how to handle the deserialization of the incoming object from the string at the Spring Boot backend and how to control proper deconstruction if some fields are optional or not mandatory.

OpenAPI User import definition YAML

So we start where we end the last time. Let’s generate the Spring Boot endpoint through the OpenAPI schema, which will be able to receive objects and, optionally, a file through multipart form data.

openapi: 3.0.2
info:
  title: User management module
  description: User management
  version: '0.1'
  contact:
  email: optional@email.com
servers:
  - url: https://localhost:8080/api/user-management

paths:
  /users/import:
    post:
      summary: Create new Users with optional attachment
      tags:
        - users
      operationId: createUserWithOptionalFile
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                createUser:
                  description: Wrapper containing information for new user creation
                  type: object
                  properties:
                    username:
                      description: Users username
                      type: string
                    age:
                      description: Users password
                      type: number
                    creationTimestamp:
                      description: Time when the user will be defined as created in the system
                      type: string
                      format: date-time
                      example: "2024-02-29T12:30:00.000Z"
                    email:
                      description: Email of the user
                      type: string
                    addressId:
                      description: ID of the users address
                      type: string
                    accessRights:
                      description: List of access rights for the user
                      type: array
                      items:
                        type: object
                        properties:
                          accessRightId:
                            description: ID of the access right
                            type: string
                          note:
                            description: Note for the access right
                            type: string
                  required:
                    - username
                    - email
                    - accessRights
                optionalFile:
                  description: Optional file attachment
                  type: string
                  format: binary
              required:
              - createUser
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUserResponse'
        '400':
          description: Bad Request

As you can see, we have defined the endpoint /users/import, which will be able to receive the object createUser and optionally also a single file. The createUser object is defined in the schema and is required, while the file is optional. CreateUser object also has various definitions of fields, although unimportant and displayed only for current examples.

You can refer to the object schema to make the YAML file more readable and concise. The object’s schema can be defined in self-standing section dedicated to components.

openapi: 3.0.2
info:
  title: User management module
  description: User management
  version: '0.1'
  contact:
  email: optional@email.com
servers:
  - url: https://localhost:8080/api/user-management

paths:
  /users/import:
    post:
      summary: Create new Users with optional attachment
      tags:
        - users
      operationId: createUserWithOptionalFile
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                createUser:
                  $ref: '#/components/schemas/CreateUser'
                optionalFile:
                  description: Optional file attachment
                  type: string
                  format: binary
              required:
              - createUser
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUserResponse'
        '400':
          description: Bad Request

components:
  schemas:
    CreateUser:
      description: Wrapper containing information for new user creation
      type: object
      properties:
        username:
          description: Users username
          type: string
        age:
          description: Users password
          type: number
        creationTimestamp:
          description: Time when the user will be defined as created in the system
          type: string
          format: date-time
          example: "2024-02-29T12:30:00.000Z"
        email:
          description: Email of the user
          type: string
        addressId:
          description: ID of the users address
          type: string
        accessRights:
          description: List of access rights for the user
          type: array
          items:
            type: object
            properties:
              accessRightId:
                description: ID of the access right
                type: string
              note:
                description: Note for the access right
                type: string
      required:
        - username
        - email
        - accessRights

Enforcing and casting mandatory properties of multipart request

Multipart file can accept only the Strings or Files (better visible in testing with Postman section). So any string input – Java’s serialized object, or JSON, is at the end nothing more than just a string of bytes.

The problem will arise during the deserialization of autogenerated code. It does not matter if you declare the object cast as required. With proper mapping, the input will be taken as a String and not as the type you want to use from the method signature.

Mapper and validator factory beans can solve the issue and handle the input.

First, register one new bean for object Validation. Optionally, you can register the ObjectMapper with JavaTimeModule to handle the date-time format, as we will use the date-time string in ISO format (“YYYY-MM-DDTHH:MM:SS.mmmZ”). The Validator is created through LocalValidatorFactoryBean.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.validation.beanvalidation.LocalValidatorFactoryBean;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;

import jakarta.validation.Validator;
import lombok.val;

@Configuration
public class AppConfig {

  //@Bean
  //public ObjectMapper objectMapper() {
  //  val objectMapper = new ObjectMapper();
  //  objectMapper.registerModule(new JavaTimeModule());
  //  return objectMapper;
  //}

  @Bean
  public Validator validator() {
    return new LocalValidatorFactoryBean();
  }

}

The code was written for Java 21 dependencies with Lombok.

To enforce the proper conversion, you must create a new Spring component to convert the incoming string to the object. The component will be able to handle the deserialization and validation of the object.

import java.util.Set;

import org.springframework.core.convert.converter.Converter;
import org.springframework.stereotype.Component;

import com.fasterxml.jackson.databind.ObjectMapper;

import jakarta.validation.ConstraintViolation;
import jakarta.validation.ConstraintViolationException;
import jakarta.validation.Validator;
import lombok.val;

@Component
public class StringToCreateUserDtoConverter implements Converter<String, CreateUserDto> {

  private final Validator validator;
  private final ObjectMapper objectMapper;

  public StringToCreateUserDtoConverter(final Validator validator, final ObjectMapper objectMapper) {
    this.validator = validator;
    this.objectMapper = objectMapper;
  }

  @Override
  public CreateUserDto convert(final String source) {
    CreateUserDto createUserDto;
    try {
        createUserDto = objectMapper.readValue(source, CreateUserDto.class);
    } catch (JsonProcessingException e) {
        throw new CreateUserDeserializationException("Input mapping and processing error: " + e.getMessage());
    }
    val violations = validator.validate(createUserDto);
    if (!violations.isEmpty()) {
        throw new ConstraintViolationException(violations);
    }
    return createUserDto;
  }

}

Just for the record, I will also add here the custom exception you can throw and catch in the custom exception handler:

import java.io.Serial;

import lombok.Getter;

@Getter
public class CreateUserDeserializationException extends RuntimeException {

  @Serial
  private static final long serialVersionUID = 1659771269447893294L;

  public CreateUserDeserializationException(String msg) {
    super(msg);
  }

}

Unit tests

I recommend writing the unit tests for the converter. It is a good practice to test the conversion and validation of the object. As we rely heavily upon Spring magic, a lot can unintentionally influence the component’s behaviour without us discovering it.

The code below is just an example of the unit tests with the usage of SpringBootTest and LocalTestcontainers which ties to get close to real-world use scenarios. We highly recommend to accommodate tests to your environment and needs.

import org.testcontainers.containers.PostgreSQLContainer;

public class LocalTestcontainers {

    public static void startPostgres(){
        PostgreSQLContainer postgre = new PostgreSQLContainer<>("postgres:16.0")
            .withDatabaseName("INSERT_DATABASE_NAME")
            .withUsername("INSERT_DATABASE_USERNAME")
            .withPassword("INSERT_DATABASE_PASSWORD");
        postgre.start();

        System.setProperty("spring.datasource.url", postgre.getJdbcUrl());
        System.setProperty("spring.datasource.username", postgre.getUsername());
        System.setProperty("spring.datasource.password", postgre.getPassword());
    }

}

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotNull;

import java.math.BigDecimal;
import java.time.Instant;
import java.time.format.DateTimeFormatter;
import java.util.UUID;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.testcontainers.junit.jupiter.Testcontainers;

import com.codepills.usermanagementmodule.api.exception.CreateUserDeserializationException;
import com.codepills.usermanagementmodule.utils.LocalTestcontainers;

import jakarta.validation.ConstraintViolationException;
import lombok.val;

@SpringBootTest
@Testcontainers
class StringToCreateUserDtoConverterTest {

    static {
        LocalTestcontainers.startPostgres();
    }

    @Autowired
    private StringToCreateUserDtoConverter stringToCreateUserDtoConverter;

    @Test
    void testConvertValidInputString() {
        // Arrange
        val username = "JohnDoe";
        val age = 25;
        val formatter = DateTimeFormatter.ISO_INSTANT;
        val now4CreationTime = Instant.now();
        val email = "john.doe@noemail.com";
        val addressId = UUID.randomUUID();
        val accessRightId1 = UUID.randomUUID();
        val accessRightId2 = UUID.randomUUID();

        val stringBuilder = new StringBuilder();
        stringBuilder.append("{");
        stringBuilder.append("\"username\" : \"").append(username).append("\",");
        stringBuilder.append("\"age\" : ").append(age).append(",");
        stringBuilder.append("\"creationTimestamp\" : \"").append(formatter.format(now4CreationTime)).append("\",");
        stringBuilder.append("\"email\" : \"").append(email).append("\",");
        stringBuilder.append("\"addressId\" : \"").append(addressId).append("\",");
        stringBuilder.append("\"accessRights\" : [");
        stringBuilder.append("{");
        stringBuilder.append("\"accessRightId\" : \"").append(accessRightId1).append("\",");
        stringBuilder.append("}, {");
        stringBuilder.append("\"accessRightId\" : \"").append(accessRightId2).append("\"");
        stringBuilder.append("}]}");
        val validInput = stringBuilder.toString();

        // Act
        val createUserDto = stringToCreatUserDtoConverter.convert(validInput);

        // Assert
        assertNotNull(createUserDto);
        assertEquals(username, createUserDto.getUsername());
        assertEquals(age, createUserDto.getAge());
        assertEquals(now4CreationTime, createUserDto.getCreationTimestamp());
        assertEquals(email, createUserDto.getEmail());
        assertEquals(addressId.toString(), createUserDto.getAddressId());
        assertEquals(2, createUserDto.getAccessRights().size());
        assertEquals(accessRightId1.toString(), createUserDto.getAccessRights().get(0).getAccessRightId());
        assertEquals(accessRightId2.toString(), createUserDto.getAccessRights().get(1).getAccessRightId());
    }

    @Test
    void testConvertInvalidInputString() {
        // Arrange
        val invalidInput = "invalid input string";
        // Act & Assert
        try {
            stringToCreateUserDtoConverter.convert(invalidInput);
        } catch (CreateUserDeserializationException ex) {
            assertEquals("Input mapping and processing error: Unrecognized token 'invalid': was expecting (JSON String, Number, Array, "
                             + "Object or token 'null', 'true' or 'false')\n at [Source: (String)\"invalid input string\"; line: 1, "
                             + "column: 8]", ex.getMessage());
        }
    }

    @Test
    void testConvertInputWithValidationErrors() {
        // Arrange
        val username = "JohnDoe";
        val age = 25;
        val formatter = DateTimeFormatter.ISO_INSTANT;
        val now4CreationTime = Instant.now();
        val email = "john.doe@noemail.com";
        val addressId = UUID.randomUUID();
        val accessRightId1 = UUID.randomUUID();
        val accessRightId2 = UUID.randomUUID();

        val stringBuilder = new StringBuilder();
        stringBuilder.append("{");
        stringBuilder.append("\"username\" : \"").append(username).append("\",");
        stringBuilder.append("\"age\" : ").append(age).append(",");
        stringBuilder.append("\"creationTimestamp\" : \"").append(formatter.format(now4CreationTime)).append("\",");
        stringBuilder.append("\"email\" : \"").append(email).append("\",");
        // Missing addressId
        stringBuilder.append("\"addressId\" : null,");
        stringBuilder.append("\"accessRights\" : [");
        stringBuilder.append("{");
        stringBuilder.append("\"accessRightId\" : \"").append(accessRightId1).append("\",");
        stringBuilder.append("}, {");
        stringBuilder.append("\"accessRightId\" : \"").append(accessRightId2).append("\"");
        stringBuilder.append("}]}");
        val validInput = stringBuilder.toString();

        // Act & Assert
        try {
            stringToCreateUserDtoConverter.convert(inputWithValidationErrors);
        } catch (ConstraintViolationException ex) {
            assertEquals(1, ex.getConstraintViolations().size());
        }
    }

}

User Management Controller

Now, all we need to do is create a controller to implement the OpenAPI schema.

Here is an example of the controller:

@Logger
@RestController
@RequiredArgsConstructor
public class UserManagementController implements UserManagementApi {

  @Override
  public ResponseEntity<Void>> createUserWithOptionalFile(
        @RequestPart(name = "createUser") final CreateUserDto createUserDto,
        @RequestPart(name = "optionalFile", required = false) MultipartFile optionalFile
     ) {
    if (optionalFile == null || optionalFile.isEmpty()) {
        log.info("No optionalFile uploaded.");
    } else {
        log.info("PDF optionalFile {} uploaded but not saved.", optionalFile.getOriginalFilename());
    }

    // You can work with createUserDto here

    return ResponseEntity.ok().build();
  }

}

I will leave the implementation of createUserWithOptionalFile() method up to you as it is not the main focus of this article.

Again, notice the optionalFile and createUser keywords in the method arguments. It is the same as the keyword as defined in the OpenAPI schema.

Testing with Postman

Nothing blocks our development anymore, and we can start testing the endpoint with Postman. The endpoint will be able to receive the serialized object in the form of string and also the file. However, attaching the file to the request is, of course, optional.

As it might need to be stressed more, the most important thing is using the exact keywords defined in the OpenAPI schema. In our case, for importing object, it will be createUser and for optional file, it will be optionalFile.

Let’s run the SpringBoot app at localhost.

Backend should be running at localhost. And if added the necessary logic for file processing into the controller, we should be able to upload serialized objects in JSON format and optional file through the /users/import endpoint.

When using Postman, you also need to define the type of multipart key. It is either the String or File. For files, use File, and for the object, use String. Do not forget that in the previous article we discuss the implementation of sending multiple files through multipart request.

All you need to do is to define your endpoint POST request in Postman. Select POST request, add the URL, and in the body tab, select form-data and add the keywords createUser set as String and optionalFile as File .

The most important part is to really define serialized object as String and not File.

Here is an example of createUser as String:

{
	"username" : "johndoe",
	"age" : "25",
	"creationTimestamp" : "2024-02-29T12:30:00.000Z",
	"email" : "john.doe@noemail.com",
	"addressId" : "f8935f28-8d7b-40a4-96d7-a3288976617e",
	"accessRights" : [
		{
      "accessRightId" : "712d5a0a-11b5-4a44-9e92-6e67d16be2aa"
    }
	]
}

Conclusion

This article has shown how to create a Spring Boot endpoint to receive objects and, optionally, file through multipart form data. We have also demonstrated how to handle the deserialization of the incoming object from the string at the Spring Boot backend and how to control proper deconstruction if some fields are optional or not mandatory.

Is it applicable to auto-generating infrastructure code through OpenAPI with Spring Boot for multipart endpoint and uploading files? Let us know in the comments below. Do you have your trick or see another way how to enforce and deserialize multipart object? Let us know in the comments below the article. We would like to hear your ideas and stories.

Introduction

We often encounter the problem during testing that we do not care about the data correctness, as much as we care about correct algorithm flow. In this situations, we want to check if specific methods were hit and executed. Sometimes we need to go deeper and seek an answer on how often these methods were called or verify that the methods called at all.

The necessary method, which will help us in our testing quest, is called verify() and is part of Mockito testing framework.

Mockito verify verification options

public static  T verify(T mock, VerificationMode mode)

mock is object of type T you are placing into the verify() method for verification. As a second method argument is VerificationMode mode variable, which describes how the mock should be verified. Possible verification modes are:

verify(mock, times(5)).someMethod("was called exactly five times");
verify(mock, never()).someMethod("was never called");
verify(mock, atLeast(5)).someMethod("was called at least five times");
verify(mock, atLeastOnce()).someMethod("was called at least once");
verify(mock, atMost(5)).someMethod("was called at most five times");

There is also one special VerificationMode mode called only(). This mode verifies that no other method was called on the mock so far.

verify(mock, only()).someMethod("only someMethod was called");

Mockito verify verification modes in action

In order to test individual verification modes, we will write a simple test. For testing purposes it will consist from two classes. (Both are inner private classes for MockitoVerifyTest.java.) First will be a fake class Account which trough dependency injection will use second class Counter. Counter class will be used as a Mock in our test.

Here is a Counter class:

private class Counter {

    private int counter;

    public Counter() {
        this.counter = 0;
    }

    public void increment() {
        this.counter++;
    }

    public void reset() {
        this.counter = 0;
    }

    public int getCount() {
        return this.counter;
    }
}

And here is the Account class:

private class Account {

    private Counter counter;

    public Account(Counter counter) {
        this.counter = counter;
    }

    public void incrementCounter() {
        this.counter.increment();
    }

    public void resetCounter() {
        this.counter.reset();
    }

    public int getCounterValue() {
        return this.counter.getCount();
    }
}

And finally, here is an exemplary test where you can see usage of individual verification modes:

import org.junit.Test;
import org.junit.runner.RunWith;
import org.mockito.Mock;
import org.mockito.Mockito;
import org.mockito.junit.MockitoJUnitRunner;

import static org.mockito.Mockito.atLeast;
import static org.mockito.Mockito.atLeastOnce;
import static org.mockito.Mockito.atMost;
import static org.mockito.Mockito.never;
import static org.mockito.Mockito.only;
import static org.mockito.Mockito.times;
import static org.mockito.Mockito.verify;

@RunWith(MockitoJUnitRunner.class)
public class MockitoVerifyTest {

    @Mock
    Counter counter;

    @Test
    public void testMockitoVerifyMethodCalls() {

        Account account = new Account(counter);

        // Verification using only() and atLeastOnce()
        account.incrementCounter();
        Mockito.verify(counter, only()).increment();
        Mockito.verify(counter, atLeastOnce()).increment();

        // Verification using times(X)
        for (int i = 0; i < 4; i++) {
            account.incrementCounter();
        }
        Mockito.verify(counter, times(5)).increment();

        // Verification using atLeast(X), atMost(X), never()
        for (int i = 0; i < 5; i++) {
            account.incrementCounter();
        }
        Mockito.verify(counter, atLeast(5)).increment();
        Mockito.verify(counter, atMost(10)).increment();
        Mockito.verify(counter, never()).getCount();
    }
}

Let's discuss little but example code.

Account account = new Account(counter);

// Verification using only() and atLeastOnce()
account.incrementCounter();
Mockito.verify(counter, only()).increment();
Mockito.verify(counter, atLeastOnce()).increment();

First, we will create new instance of Account class which trough dependency injection is injected with Mock instance of our Counter class.

As first we verify that there was no method, except increment() method, has been called on our mock at all. And as second verification, we will check that it was called at least once,

for (int i = 0; i < 4; i++) {
    account.incrementCounter();
}
Mockito.verify(counter, times(5)).increment();

Now we call incrementCounter() method four more times, remember we already called it once, and we will check that it was mock method injected to instance was called exactly five times.

for (int i = 0; i < 5; i++) {
    account.incrementCounter();
}
Mockito.verify(counter, atLeast(5)).increment();
Mockito.verify(counter, atMost(10)).increment();
Mockito.verify(counter, never()).getCount();

In the last section, we are incrementing the counter again five more times, and now we are checking if it was called at least five times and at most ten times.

On the last line we are checking method call for Mock' getCount() method that was never called.

Conclusion

This article contains a straightforward test on which we have demonstrated how to use Mockito verify method for mock' method call verification.

As always, you can find all our examples on our GitHub project!

Introduction

Checking list equality is a widespread problem; we often need to compare the list elements against each other. Comparison and assertion occur many times during the testing when we need to assert results with predefined expectations.

Two lists equality

At first, some might think, that for equality of two lists is conditioned by lists containing the same elements. This way of thinking is not entirely true. Single look into the Java documentations for List.equals() method will uncover us true meaning of list equality:

… two lists are defined to be equal if they contain the same elements in the same order.

Therefore, we need to compare the lists’ elements mutually, but we also need to check the order of the elements in the lists reciprocally.

So first, let’s take a good look at how not to do a list equality check.

Compare two list with the bruteforce

Following lines of code are placed here only for demonstration purposes. For all cost, you must avoid such hideous brute force solution in your code.

private boolean compareLists(final List list1,final List list2) {
    if(list1.size() == list2.size()) {
        if(list1.isEmpty() && list2.isEmpty()) {
            return true;
        }
        for(int i = 0; i < list1.size(); i++) {
            if(!list1.get(i).equals(list2.get(i))) {
                return false;
            };
        }
        return true;
    }
    return false;
}

The reason why to not use it in your code is that this code is basically List interface implementation of the equal() method. Therefore all you need to use for comparing two lists is to call equal() method.

private boolean compareLists(final List list1,final List list2) {
    return list1.equals(list2);
}

Interface method definition ensures that the equals method works through different implementations of the List interface in a same way.

Framework usage

For testing purposes, it is probably better to use some of the available Java frameworks for testing, which can give us more options in List testing.

In our examples, we will play with the following code snippet based on user entities belonging to different groups. We will compare lists are figure out if all users are members of all groups.

List users = Arrays.asList("John Doe", "Tom Smith", "Paul Iron", "George Silver");
List moderators = Arrays.asList("John Doe", "Tom Smith", "Paul Iron", "George Silver");
List admins = Arrays.asList("John Doe", "Tom Smith", "Paul Iron", "George Silver");

JUnit

Rather than using and printing equals for tests, it is better to use assert methods. JUnit testing framework offers us three suitable ways for list equality assertion.

• assertEquals(expected, actual) - Asserts that two objects are equal. If they are not, an AssertionError without a message is thrown. If expected and actual are null, they are considered equal.
• assertNotSame(unexpected, actual) - Asserts that two objects do not refer to the same object. If they do refer to the same object, an AssertionError without a message is thrown.
• assertNotEquals(unexpected, actual) - Asserts that two objects are not equals. If they are, an AssertionError without a message is thrown. If unexpected and actual are null, they are considered equal.

@Test
public void testJUnitListAsserts() throws Exception {
    Assert.assertEquals(users, moderators);
    Assert.assertNotSame(users, moderators);
    Assert.assertNotEquals(users, admins);
}

Conclusion

This article has shown you how not to do list assertion and explain how to check and assert two lists equality.

As always, you can find all our examples on our GitHub project!

It is common practice for unit testing in the Spring JUnit test to load files and their content to make more robust test cases. Or we have a test case where we need perhaps read or write data or test specific files in general.

1. Using ClassLoader

First option is to use and instance of the ClassLoader.

final ClassLoader classLoader = getClass().getClassLoader();
final String resourceName = "daily_report.csv";
final File file = new File(classLoader.getResource(resourceName).getFile());
final String absolutePath = file.getAbsolutePath();

System.out.println(absolutePath);

Assert.assertTrue(absolutePath.endsWith("/daily_report.csv"));

We will get the output of the absolute path as:

/Users/your.user.name/DEV/tutorials/testing-modules/junit-5-basics/target/test-classes/daily_report.csv

Be aware that the path to the resource will look slightly different from the rest of the examples. It is because the ClassLoader looks for the resources on the classpath. Therefore obtaining a path to the resource is from the point of the compiled project.

If you build your project with Maven, compiled classes and resources are in the /target directory in the project root folder. That is why you need to count on the path to resource adjusted for the difference. The other two methods use project root.

2. Using Path

Second option is to use an instance of the Path class. We will call a static factory method Paths.get() which will return us its new instance. Then we will convert Path to File instance and from the that we will extract absolute path with getAbsolutePath() method.

final Path resourcePath = Paths.get("src","test","resources");
final String absolutePath = resourcePath.toFile().getAbsolutePath();

System.out.println(absolutePath);

Assert.assertTrue(absolutePath.endsWith("src/test/resources"));

We will get the same output as in example using java.io.File:

/Users/your.user.name/DEV/tutorials/testing-modules/junit-5-basics/src/test/resources

Path class was introduced in Java 7; consequently, it is available also in older and legacy projects.

3. Using java.io.File

Third approach is to use an instance of the java.io.File class to read the /src/test/resources directory. We will create instance and then we will call its method getAbsolutePath() method. Path we will obtain in this way is relative path towards the current working directory of the project.

final String resourcePath = "src/test/resources";
final File file = new File(resourcePath);
final String absolutePath = file.getAbsolutePath();

System.out.println(absolutePath);

Assert.assertTrue(absolutePath.endsWith("src/test/resources"));

Let’s see an example output when running on the Unix based system:

/Users/your.user.name/DEV/tutorials/testing-modules/junit-5-basics/src/test/resources

Conclusion

This article was a quick tutorial where we showed how to read resources from the /src/test/resources directory in JUnit 5.

There are three different ways how to get a resource for testing. We can either use File, Paths or ClassLoader class.

As always, you can find all our examples on our GitHub project!

This is a small guide explaining how to start with Codeception PHP test framework and how to integrate it with Selenium for automated tests.

What is Codeception and what is good for?

Codeception is PHP framework devoted to test PHP code. Installation is very simple and requires only a few steps. It is actually well known for its easy code readability of test units. Codeception PHP framework is used for acceptance testing. Codeception emphasize usage of the variable name $I, so than many lines of code are very descriptive exp. $I want to do this and that, $I expect to see something. etc.

Codeception helps with creating test suites for 3 types of testing:

• Accaptance
• Unit
• Functional

What is acceptance testing?

Acceptance tests are emulating behavior of a real user visiting website.

Acceptance testing is formal testing with respect to user needs, requirements, and business processes conducted to determine whether a system satisfies the acceptance criteria and to enable the user, customers or other authorized entity to determine whether or not to accept the system. Acceptance testing is also known as user acceptance testing (UAT), end-user testing, operational acceptance testing or field (acceptance) testing.

Source: Wikipedia

First of all I have to recommend to watch first video by Jeffrey Way from EnvatoTuts+ for Codeception series Modern Testing in PHP with Codeception. Although the first video is very well narrated and instructive for beginner, rest of the serie is not and I would not recommend to pay for premium account to watch the rest. Jeffrey expect knowledge of many related topics where you can use Codeception (DB connection, Laravel, …) but do not create simple code snippets for your first test and does not talk much about usage of elemental Codeception functions. Serie is aimed for advanced users.

1. Download

You can download Codeception framework out of the box via composer by CLI command $ composer require "codeception/codeception" .

You can also implement it into already existing project updating a composer.json file placing following:

{
    "require": {
        "codeception/codeception": "^2.2",
        ...
    }
}

For newest version of Codeception please visit and search packagist.org . Over CLI just hit composer command in folder of your project: composer update (or composer install).

2. Create codeception.yml

By executing codecept bootstrap Codeception creates the codeception.yml file and bunch of new files for test suites.

What is test suite?

The test suite is a collection of test cases that are intended to be used to test a software program to show that it has some specified set of behaviours. A test suite often contains detailed instructions or goals for each collection of test cases and information on the system configuration to be used during testing. A group of test cases may also contain prerequisite states or steps, and descriptions of the following tests.

Collections of test cases are sometimes incorrectly termed a test plan, a test script, or even a test scenario.

Source: Wikipedia

3. Create your first test

Create your first test by Codeception command:

codecept generate:cept acceptance FirstTest

Note: Codeception scenario tests are called Cepts.

4. Setting Acceptance test method

Basically there are 2 method which I managed to try to in short time – PHP Browser and Selenium WebDriver:

1. PHP Browser – works on idea of web scrapper. Code does not emulate real browser but just download HTML code and apply test scenarios on it.
2. Selenium WebDriver – works as “artificial user”. PHP test case code emulate real browser and perform actions upon real website in browser.

I would recommended to first start with PHP Browser and than try Selenium WebDriver. PHP Browser can check HTML page contents, click links, fill forms, and submit POST and GET requests. Unfortunately PHP Browser have few drawbacks (you can click only on links with valid urls or form submit buttons,  you can’t fill fields that are not inside a form, you can’t work with JavaScript interactions like modal windows or date-pickers) and for more complex tests is necessary to use Selenium WebDriver.

4.1. PHP Browser

For setting up PHP Browser just change acceptance.suite.yml to:

class_name: AcceptanceTester
modules:
    enabled:
        - PhpBrowser:
            url: "http://localhost/app"          
        - \Helper\Acceptance

4.2. Selenium WebDriver

For setting Selenium WebDriver you need to make 3 steps.

1) Change acceptance.suite.yml to:

class_name: AcceptanceTester
modules:
    enabled:
        - WebDriver:
            url: "http://localhost:8000/app"
            browser: firefox            
        - \Helper\Acceptance

2) In your .bash_profile you must also set GeckoDriver (drivers emulating Firefox) which you can download from mozilla/geckodriver GitHub page.

## Selenium GeckoDriver
export PATH=$PATH:/PATH_TO_GECKODRIVER_FOLDER/

3) To set Selenium WebDriver is also necessary download Selenium Server and run it prior the test. To run Selenium Server change directory to folder where is file located and type server run command java -jar selenium-server-standalone-YOUR.V.NO.jar .

5 .Writing first PHP test

Under acceptance folder we will create first test in FirstTest.php file. We will try to check “Hello World!” text at homepage:

<?php
  $I = new AcceptanceTester($scenario);
  $I->wantTo('Test Frontpage');
  $I->amOnPage('/');
  $I->see('Hello World!', 'h1');
?>

6. Running the test

Running the test case is possible by simple command codecept run . You will write this command often so you can create temporary (alias in your folder) or permanent alias (in .bash_profile) by creating alias exp. alias runtest=vendor/bin/codecept run and than just type your alias.

If you have done everything right, with Selenium you should new see Firefox window executing your first test. After finishing it, browser will close down and terminal shows announcement about Success. PHP Webdriver execute all test just over the terminal info panel.

6.1 Further use

To show the list of all available commands you need to type vendor/bin/codecept . It will also handy to create alias for it ( but just for vendor/bin/ and than type codecept ).

Codecept will always by run execute every single test you have wrote all together. It helps to nerrow down only the test suite which we want by selecting test suit in command: codecept acceptance/functional/unit run .