Testing Asynchronous Operations in Spring With JUnit 5 and Byteman
In this article, we will be discussing how to test operations in an application that uses a Spring context (with asynchronous operations enabled).
CORE
·
Join the DZone community and get the full member experience.
Join For FreeThis is already the third article that describes how to test asynchronous operations with the Byteman framework in an application using the Spring framework. The article focuses on how to do such testing with the JUnit 5 library.
The previous article focused on how such testing could be done with the usage of the JUnit 4 library (first article) and Spock framework (second article).
Just like in with the second article, It's not necessary to read the previous articles because all of the essentials parts are going to be repeated. Nevertheless, I encourage you to read the previous article, related to the Spock framework because, In my opinion, It is a good alternative for the JUnit 5 library.
Although the whole demo project has some changes comparing to that one which was used for the previous articles (among other the Spring Boot dependency was updated from version 1.5.3 to 2.2.4), the source code used for the test case presentation is the same. So if you have already read the previous article, and you still remember the test case concept, you can quickly jump to the section, "Test Code".
So, let's get started!
In this article, we will be discussing how to test operations in an application that uses a Spring context (with asynchronous operations enabled). We don’t have to change the production code to achieve this.
Tests are going to be run with the JUnit 5 library. If you are not familiar with JUnit 5, I would suggest you read its user guide.
Our main test dependency is the BMUnit library. It is part of the Byteman project, and it has support for the JUnit 5 library. We also need to use the "utils" maven module from the BMUnit-extension project.
Byteman is a tool that injects Java code into your application methods or into Java runtime methods without the need for you to recompile, repackage, or even redeploy your application.
BMUnit is a package that makes it simple to use Byteman as a testing tool by integrating it into the two most popular Java test frameworks, JUnit and TestNG.
The Bmunit-extension is a small project on GitHub, which contains JUnit 4 rule, which allows integration with Byteman framework and JUnit and Spock tests. It also contains a few helper methods in the "utils" method, which is compatible with version 4.0.10 of Byteman project.
As was mentioned before in the article, we are going to use code from the demo application, which is part of the “Bmunit-extension” project.
The source code can be found on page https://github.com/starnowski/bmunit-extension/tree/master/junit5-spring-demo.
Test Case
The test case assumes that we register a new user to our application (all transactions were committed) and send an email to him/her. The email is sent asynchronously. Now, the application contains a few tests that show how this case can be tested. There is no suggestion that the code implemented in the demo application for the Bmunit-extension is the only approach or even the best one.
The primary purpose of this project is to show how such a case could be tested without any production code change while using Byteman.
In our example, we need to check the process of a new application user registration process. Let’s assume that the application allows user registration via a REST API. So, a client sends a request with user data. A controller then handles the request.
When the database transaction has occurred, but before the response has been set, the controller invokes an Asynchronous Executor to send an email to a user with a registration link (to confirm their email address).
The whole process is presented in the sequence diagram below.
Now, I am guessing that this might not be the best approach to register users. It would probably be better to use some kind of scheduler component, which checks if there is an email to send — not to mention that for larger applications, a separate microservice would be more suitable.
Let’s assume that it is acceptable for an application that does not have a problem with available threads.
Implementation for our REST Controller:
public class UserController {
private UserService service;
("/users")
public UserDto post( UserDto dto)
{
return service.registerUser(dto);
}
}
Service that handles the User object:
xxxxxxxxxx
public class UserService {
private PasswordEncoder passwordEncoder;
private RandomHashGenerator randomHashGenerator;
private MailService mailService;
private UserRepository repository;
public UserDto registerUser(UserDto dto)
{
User user = new User().setEmail(dto.getEmail()).setPassword(passwordEncoder.encode(dto.getPassword())).setEmailVerificationHash(randomHashGenerator.compute());
user = repository.save(user);
UserDto response = new UserDto().setId(user.getId()).setEmail(user.getEmail());
mailService.sendMessageToNewUser(response, user.getEmailVerificationHash());
return response;
}
}
A service that handles mail messages:
xxxxxxxxxx
public class MailService {
private MailMessageRepository mailMessageRepository;
private JavaMailSender emailSender;
private ApplicationEventPublisher applicationEventPublisher;
public void sendMessageToNewUser(UserDto dto, String emailVerificationHash)
{
MailMessage mailMessage = new MailMessage();
mailMessage.setMailSubject("New user");
mailMessage.setMailTo(dto.getEmail());
mailMessage.setMailContent(emailVerificationHash);
mailMessageRepository.save(mailMessage);
applicationEventPublisher.publishEvent(new NewUserEvent(mailMessage));
}
public void handleNewUserEvent(NewUserEvent newUserEvent)
{
SimpleMailMessage message = new SimpleMailMessage();
message.setTo(newUserEvent.getMailMessage().getMailTo());
message.setSubject(newUserEvent.getMailMessage().getMailSubject());
message.setText(newUserEvent.getMailMessage().getMailContent());
emailSender.send(message);
}
}
Test Code
To see how to attach all Byteman and Bmunit-extension dependencies, please check the section "How to attach project". Please also check the project descriptor file for the demo application to specify the correct dependencies from the Byteman project with version 4.
Let’s go to the test some code:
xxxxxxxxxx
(webEnvironment=SpringBootTest.WebEnvironment.RANDOM_PORT)
(value = CLEAR_DATABASE_SCRIPT_PATH,
config = (transactionMode = ISOLATED),
executionPhase = BEFORE_TEST_METHOD)
(value = CLEAR_DATABASE_SCRIPT_PATH,
config = (transactionMode = ISOLATED),
executionPhase = AFTER_TEST_METHOD)
public class UserControllerTest {
static GreenMailExtension greenMail = new GreenMailExtension(ServerSetup.verbose(ServerSetup.ALL)).withConfiguration(new GreenMailConfiguration().withUser("no.such.mail@gmail.com", "no.such.password"));
UserRepository userRepository;
TestRestTemplate testRestTemplate;
private int port;
("Should send mail message after correct user sign-up and wait until the async operation which is e-mail sending is complete")
(name = "{index}. expected e-mail is {0}")
(strings = {"szymon.doe@nosuch.domain.com", "john.doe@gmail.com","marry.doe@hotmail.com", "jack.black@aws.eu" })
(verbose = true, bmunitVerbose = true)
(rules = {
(name = "signal thread waiting for mutex \"UserControllerTest.shouldCreateNewUserAndSendMailMessageInAsyncOperation\"",
targetClass = "com.github.starnowski.bmunit.extension.junit5.spring.demo.services.MailService",
targetMethod = "handleNewUserEvent(com.github.starnowski.bmunit.extension.junit5.spring.demo.util.NewUserEvent)",
targetLocation = "AT EXIT",
action = "joinEnlist(\"UserControllerTest.shouldCreateNewUserAndSendMailMessageInAsyncOperation\")")
})
public void testShouldCreateNewUserAndSendMailMessageInAsyncOperation(String expectedEmail) throws IOException, URISyntaxException, MessagingException {
// given
assertThat(userRepository.findByEmail(expectedEmail)).isNull();
UserDto dto = new UserDto().setEmail(expectedEmail).setPassword("XXX");
RestTemplate restTemplate = new RestTemplate();
createJoin("UserControllerTest.shouldCreateNewUserAndSendMailMessageInAsyncOperation", 1);
assertEquals(0, greenMail.getReceivedMessages().length);
// when
UserDto responseEntity = restTemplate.postForObject(new URI("http://localhost:" + port + "/users/"), (Object) dto, UserDto.class);
joinWait("UserControllerTest.shouldCreateNewUserAndSendMailMessageInAsyncOperation", 1, 15000);
// then
assertThat(userRepository.findByEmail(expectedEmail)).isNotNull();
assertThat(greenMail.getReceivedMessages().length).isEqualTo(1);
assertThat(greenMail.getReceivedMessages()[0].getSubject()).contains("New user");
assertThat(greenMail.getReceivedMessages()[0].getAllRecipients()[0].toString()).contains(expectedEmail);
}
}
Test class needs to contain an annotation of type WithByteman (line 1) to load Byteman rules. The BMRule annotation is part of the BMUnit project. All options name (line 26), targetClass (line 27), targetMethod (line 28), targetLocation (line 29) and action (line 30) refers to the specific section in Byteman rule language section. Options targetClass , targetMethod and targetLocation are used to a specified point in java code, after which the rule should be executed.
The action option defines what should be done after reaching the rule point.
If you would like to know more about the Byteman rule language, then please check Programer’s guide.
The purpose of this test method is to confirm that the new application user can be registered via the rest API controller, and the application sends an email to the user with registration details. The last important thing, the test confirms that the method which triggers an Asynchronous Executor which sends an email is being triggered.
To do that, we need to use a “Joiner” mechanism. From “Developer Guide” for Byteman, we can find out that the joiners are useful in situations where it is necessary to ensure that a thread does not proceed until one or more related threads have exited.
Generally, when we create joiner, we need to specify the identification and number of thread which needs to join. In the given (line 33) section we executes BMUnitUtils#createJoin(Object, int)(line 37) to create UserControllerTest.shouldCreateNewUserAndSendMailMessageInAsyncOperation joiner with one as expected number of threads. We expect that the thread responsible for sending is going to join.
To achieve this, we need to via BMRule annotation set that after method exit (targetLocation option with value “AT EXIT”) the specific action need be done which executes method Helper#joinEnlist(Object key), this method does not suspend current thread in which it was called.
In the when section (line 40), besides executing testes method, we invoke BMUnitUtils#joinWait(Object, int, long) to suspend test thread to wait until the number of joined threads for joiner UserControllerTest.shouldCreateNewUserAndSendMailMessageInAsyncOperation reach expected value. In case when there won’t be expected number of joined threads, then execution is going to reach a timeout, and certain exceptions are going to be thrown.
In the then (line 44) section, we check if the user was created, and email with correct content was sent.
This test could be done without changing source code thanks to Byteman.
It also could be done with basic java mechanism, but it would also require changes in source code.
First, we have to create a component with CountDownLatch.
xxxxxxxxxx
public class DummyApplicationCountDownLatch implements IApplicationCountDownLatch{
private CountDownLatch mailServiceCountDownLatch;
public void mailServiceExecuteCountDownInHandleNewUserEventMethod() {
if (mailServiceCountDownLatch != null) {
mailServiceCountDownLatch.countDown();
}
}
public void mailServiceWaitForCountDownLatchInHandleNewUserEventMethod(int milliseconds) throws InterruptedException {
if (mailServiceCountDownLatch != null) {
mailServiceCountDownLatch.await(milliseconds, TimeUnit.MILLISECONDS);
}
}
public void mailServiceResetCountDownLatchForHandleNewUserEventMethod() {
mailServiceCountDownLatch = new CountDownLatch(1);
}
public void mailServiceClearCountDownLatchForHandleNewUserEventMethod() {
mailServiceCountDownLatch = null;
}
}
There are also changes required in MailService so that the specific methods for type DummyApplicationCountDownLatch would be executed.
xxxxxxxxxx
private IApplicationCountDownLatch applicationCountDownLatch;
public void sendMessageToNewUser(UserDto dto, String emailVerificationHash)
{
MailMessage mailMessage = new MailMessage();
mailMessage.setMailSubject("New user");
mailMessage.setMailTo(dto.getEmail());
mailMessage.setMailContent(emailVerificationHash);
mailMessageRepository.save(mailMessage);
applicationEventPublisher.publishEvent(new NewUserEvent(mailMessage));
}
public void handleNewUserEvent(NewUserEvent newUserEvent)
{
SimpleMailMessage message = new SimpleMailMessage();
message.setTo(newUserEvent.getMailMessage().getMailTo());
message.setSubject(newUserEvent.getMailMessage().getMailSubject());
message.setText(newUserEvent.getMailMessage().getMailContent());
emailSender.send(message);
applicationCountDownLatch.mailServiceExecuteCountDownInHandleNewUserEventMethod();
}
After applying those changes, we can implement below test class:
xxxxxxxxxx
(webEnvironment=SpringBootTest.WebEnvironment.RANDOM_PORT)
(value = CLEAR_DATABASE_SCRIPT_PATH,
config = (transactionMode = ISOLATED),
executionPhase = BEFORE_TEST_METHOD)
(value = CLEAR_DATABASE_SCRIPT_PATH,
config = (transactionMode = ISOLATED),
executionPhase = AFTER_TEST_METHOD)
public class UserControllerTest {
static GreenMailExtension greenMail = new GreenMailExtension(new ServerSetup(3025, (String)null, "smtp").setVerbose(true)).withConfiguration(new GreenMailConfiguration().withUser("no.such.mail@gmail.com", "no.such.password"));
UserRepository userRepository;
TestRestTemplate testRestTemplate;
private int port;
private IApplicationCountDownLatch applicationCountDownLatch;
public void tearDown()
{
applicationCountDownLatch.mailServiceClearCountDownLatchForHandleNewUserEventMethod();
}
("Should send mail message after correct user sign-up and wait until the async operation which is e-mail sending is complete")
(name = "{index}. expected e-mail is {0}")
(strings = {"szymon.doe@nosuch.domain.com", "john.doe@gmail.com","marry.doe@hotmail.com", "jack.black@aws.eu" })
public void testShouldCreateNewUserAndSendMailMessageInAsyncOperation(String expectedEmail) throws IOException, URISyntaxException, MessagingException, InterruptedException {
// given
assertThat(userRepository.findByEmail(expectedEmail)).isNull();
UserDto dto = new UserDto().setEmail(expectedEmail).setPassword("XXX");
RestTemplate restTemplate = new RestTemplate();
applicationCountDownLatch.mailServiceResetCountDownLatchForHandleNewUserEventMethod();
assertEquals(0, greenMail.getReceivedMessages().length);
// when
UserDto responseEntity = restTemplate.postForObject(new URI("http://localhost:" + port + "/users/"), (Object) dto, UserDto.class);
applicationCountDownLatch.mailServiceWaitForCountDownLatchInHandleNewUserEventMethod(15000);
// then
assertThat(userRepository.findByEmail(expectedEmail)).isNotNull();
assertThat(greenMail.getReceivedMessages().length).isEqualTo(1);
assertThat(greenMail.getReceivedMessages()[0].getSubject()).contains("New user");
assertThat(greenMail.getReceivedMessages()[0].getAllRecipients()[0].toString()).contains(expectedEmail);
}
}
Full code for demo application can found on the Github.
Summary
The Byteman allows for testing asynchronous operations in an application without changing its source code. The same test cases can be tested without the Byteman, but it would require changes in source code.
Opinions expressed by DZone contributors are their own.
Comments