JUnit Testing in Spring Boot

This chapter covers the fundamentals of testing in Spring Boot. It explores the differences between unit and integration testing, the architecture of the JUnit 5 (Jupiter) framework, and how to write robust, maintainable test suites. You will learn how to write basic assertions, bootstrap the Spring ApplicationContext using @SpringBootTest, implement parameterized tests using @CsvSource, @ValueSource, and custom @ArgumentsSource, analyze code coverage, and manage test lifecycles.

1. Introduction to Unit Testing and Test-Driven Development (TDD)

Whenever we build APIs or write production-grade code, testing is a non-negotiable requirement. Testing ensures that our code behaves exactly as expected under various conditions and prevents regressions when new features are introduced.

Testing is generally divided into two major categories:

• Unit Testing: The process of testing individual, isolated components of an application. For example, if a service class contains four distinct methods, writing unit tests involves testing each of these methods independently of the others and external systems (like databases or external APIs).
• Integration Testing: The process of testing how multiple components, modules, or external systems work together. This involves verifying database interactions, network calls, and the overall application workflow.

Test-Driven Development (TDD)

Test-Driven Development is a software development process where you write tests before writing the actual production code. The workflow follows a tight, iterative cycle:

By verifying each small function as it is built, you gain immediate feedback and can proceed with further development with high confidence.

2. JUnit 5 (JUnit Jupiter) Setup & Dependency Architecture

In the Java ecosystem, JUnit is the standard framework used for unit testing. The current major version is JUnit 5, also known as JUnit Jupiter.

Mental Hook: The JUnit team named version 5 "JUnit Jupiter" because Jupiter is the fifth planet from the Sun. If you work on legacy codebases, you might encounter JUnit 4, but modern Spring Boot applications default to JUnit 5.

Dependency Management in pom.xml

When you initialize a Spring Boot project, the spring-boot-starter-test dependency is automatically included in your pom.xml.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

Understanding the <scope>test</scope> Tag

The <scope>test</scope> configuration is critical:

• It instructs Maven to compile and run this dependency only during the testing phase.
• When Maven packages the application into a production-ready JAR or WAR file, the testing libraries (including JUnit, Mockito, and AssertJ) are excluded. This keeps the production artifact lightweight and secure.

Under the hood, spring-boot-starter-test transitively imports all necessary testing libraries, including junit-jupiter, meaning no manual setup or external dependency configuration is required.

3. Directory Structure & Naming Conventions

Spring Boot projects follow a standardized directory structure enforced by Maven. This separation ensures clean packaging and build isolation.

Key Conventions

1. Package Mirroring: The package structure inside src/test/java must exactly mirror the package structure inside src/main/java. If UserService.java is located in com.example.app.service, its corresponding test class must be placed in com.example.app.service inside the test directory.
2. Naming Convention: The standard convention is to append Test or Tests to the name of the class being tested. For example, UserService is tested by UserServiceTests or UserServiceTest.
3. Build Separation: During the Maven build process, the test classes are compiled separately and are not bundled into the final executable artifact.

4. Writing Your First Unit Test & Understanding Assertions

To write a test, you define a standard Java class and annotate its methods with @Test from the org.junit.jupiter.api package.

Basic Assertion Example

Let's write a simple test to understand how JUnit assertions work.

package com.example.app.service;

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

public class UserServiceTests {

    @Test
    public void testAddition() {
        int expected = 4;
        int actual = 2 + 2;
        
        // Assert that the expected value matches the actual value
        assertEquals(expected, actual);
    }
}

How Assertions Work

Assertions are static methods provided by the org.junit.jupiter.api.Assertions class. They assert that a specific condition is met. If the condition is met, the test passes; if not, the assertion throws an AssertionFailedError, and the test fails.

Commonly used assertion methods include:

5. The Need for @SpringBootTest (Resolving NullPointerExceptions)

When testing real-world Spring Boot components (such as Services, Repositories, or Controllers), your classes rely on dependency injection via @Autowired.

The Naive Approach (And Why It Fails)

Suppose we want to test a method findByUsername in our UserService which relies on UserRepository.

package com.example.app.service;

import com.example.app.repository.UserRepository;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import static org.junit.jupiter.api.Assertions.assertNotNull;

public class UserServiceTests {

    @Autowired
    private UserRepository userRepository;

    @Test
    public void testFindByUsername() {
        // This will throw a NullPointerException!
        assertNotNull(userRepository.findByUsername("ram"));
    }
}

Why does this throw a NullPointerException?

In a standard JUnit test run, the Spring IoC (Inversion of Control) container is not started. Because the container is not running:

1. No Spring Beans are created.
2. The @Autowired annotation is ignored.
3. userRepository remains null.
4. Invoking any method on userRepository results in a NullPointerException.

The Solution: @SpringBootTest

To resolve this, we must instruct JUnit to bootstrap the Spring ApplicationContext before running the tests. We do this by annotating the test class with @SpringBootTest.

package com.example.app.service;

import com.example.app.repository.UserRepository;
import com.example.app.entity.User;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertFalse;

@SpringBootTest
public class UserServiceTests {

    @Autowired
    private UserRepository userRepository;

    @Test
    public void testFindByUsername() {
        User user = userRepository.findByUsername("ram");
        assertNotNull(user, "User should exist in the database");
        assertFalse(user.getJournalEntries().isEmpty(), "User's journal entries should not be empty");
    }
}

When you run this test:

1. @SpringBootTest starts the embedded Spring ApplicationContext (scanning components, reading configurations, and initializing database connections).
2. The Spring container injects the real UserRepository bean into our test class.
3. The test executes successfully against the database.

6. Parameterized Testing with @CsvSource and @ValueSource

Sometimes, you need to run the same test logic multiple times with different inputs and expected outputs. Writing separate test methods for each input leads to code duplication. JUnit 5 solves this with Parameterized Tests.

To write a parameterized test, use @ParameterizedTest instead of @Test, and provide a source of arguments.

1. Using @CsvSource

@CsvSource allows you to express argument lists as comma-separated values inside an array of strings.

package com.example.app.service;

import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;
import org.junit.jupiter.api.Disabled;
import static org.junit.jupiter.api.Assertions.assertEquals;

public class ParameterizedTests {

    @ParameterizedTest
    @CsvSource({
        "1, 1, 2",     // a = 1, b = 1, expected = 2
        "2, 10, 12",   // a = 2, b = 10, expected = 12
        "3, 3, 9"      // a = 3, b = 3, expected = 9 (This will fail!)
    })
    public void testAddition(int a, int b, int expected) {
        assertEquals(expected, a + b);
    }
}

Disabling Tests

If you want to skip a test during execution (for example, if a test is temporarily failing and you want to ignore it), annotate it with @Disabled.

@Disabled
@ParameterizedTest
@CsvSource({ "1, 1, 2" })
public void disabledTest(int a, int b, int expected) {
    assertEquals(expected, a + b);
}

2. Using @ValueSource

If your test method accepts only a single argument, @ValueSource is a cleaner alternative. It supports arrays of primitive types, strings, and classes.

package com.example.app.service;

import com.example.app.repository.UserRepository;
import com.example.app.entity.User;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import static org.junit.jupiter.api.Assertions.assertNotNull;

@SpringBootTest
public class UserServiceParameterizedTests {

    @Autowired
    private UserRepository userRepository;

    @ParameterizedTest
    @ValueSource(strings = {"ram", "vipul", "shyam"})
    public void testUsersExist(String username) {
        User user = userRepository.findByUsername(username);
        assertNotNull(user, "Failed for user: " + username);
    }
}

Note: In the assertion above, we passed a custom failure message as the last argument: "Failed for user: " + username. If the assertion fails, this custom message is printed in the test console, making debugging much faster.

7. Advanced Parameterized Testing with Custom @ArgumentsSource

When test inputs are complex objects rather than simple primitives or strings, @CsvSource and @ValueSource are insufficient. In such cases, you can use @ArgumentsSource to supply complex object graphs dynamically.

Step 1: Implement ArgumentsProvider

Create a class that implements org.junit.jupiter.params.provider.ArgumentsProvider. This class must implement the provideArguments method, returning a Stream of Arguments.

package com.example.app.provider;

import com.example.app.entity.User;
import org.junit.jupiter.api.extension.ExtensionContext;
import org.junit.jupiter.params.provider.Arguments;
import org.junit.jupiter.params.provider.ArgumentsProvider;

import java.util.stream.Stream;

public class UserArgumentsProvider implements ArgumentsProvider {

    @Override
    public Stream<? extends Arguments> provideArguments(ExtensionContext context) {
        // Creating User instances using the Builder pattern
        User user1 = User.builder().username("ram").password("ramPassword").build();
        User user2 = User.builder().username("suraj").password("").build(); // Empty password test case
        
        return Stream.of(
            Arguments.of(user1),
            Arguments.of(user2)
        );
    }
}

Step 2: Reference the Provider in Your Test Class

Annotate your parameterized test with @ArgumentsSource and pass the provider class.

package com.example.app.service;

import com.example.app.entity.User;
import com.example.app.provider.UserArgumentsProvider;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ArgumentsSource;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import static org.junit.jupiter.api.Assertions.assertTrue;

@SpringBootTest
public class UserServiceArgumentsTest {

    @Autowired
    private UserService userService;

    @ParameterizedTest
    @ArgumentsSource(UserArgumentsProvider.class)
    public void testSaveNewUser(User user) {
        // Asserts that saving the user returns true (success)
        assertTrue(userService.saveNewUser(user));
    }
}

8. Running Tests via Maven Wrapper & Surefire Reports

While running tests directly from an IDE (like IntelliJ IDEA or Eclipse) is convenient during development, automated build systems and CI/CD pipelines require a command-line interface.

Running Tests via Command Line

You can execute your entire test suite using the Maven Wrapper (mvnw) or a local Maven installation.

# If Maven is installed globally
mvn test

# If using the Maven Wrapper (recommended for project portability)
./mvnw test

The Role of the Maven Surefire Plugin

When you run mvn test, Maven delegates test execution to the Maven Surefire Plugin.

• This plugin is pre-configured in the Spring Boot Parent POM, so you do not need to declare it explicitly in your pom.xml.
• It automatically scans src/test/java for classes matching naming patterns like *Test or *Tests and executes them.

Surefire Reports

After running mvn test, the Surefire plugin generates detailed reports in the target/surefire-reports directory:

• XML Reports: Used by CI/CD tools (like Jenkins, GitHub Actions, or GitLab CI) to parse test results.
• TXT Reports: Human-readable summaries of test executions, failures, and execution times.

9. Code Coverage Analysis & Exporting HTML Reports

Code Coverage measures the percentage of your production code executed during test runs. High code coverage reduces the likelihood of undetected bugs reaching production.

Analyzing Coverage in IntelliJ IDEA

IntelliJ IDEA includes a built-in coverage engine.

1. Right-click on your test folder or a specific test class.
2. Select Run 'All Tests' with Coverage.
3. The IDE will execute the tests and display a Coverage Suite panel.

Exporting Coverage Reports

To share coverage metrics with tech leads, managers, or QA teams, you can export the results as an interactive HTML report:

1. In the IntelliJ Coverage tool window, click the Export Suite Results button (or select Analyze -> Show Coverage Data).
2. Choose HTML as the export format and specify a target directory.
3. Open the generated index.html file in any browser to view an interactive, line-by-line breakdown of your code coverage.

10. JUnit Test Lifecycle Annotations

JUnit 5 provides lifecycle annotations to run setup and teardown operations. These are useful for initializing test data, mocking external services, or cleaning up resources (like temporary files or database states).

Lifecycle Annotations Summary

Code Example: Managing Temporary Resources

package com.example.app.service;

import org.junit.jupiter.api.*;

public class ResourceLifecycleTest {

    @BeforeAll
    public static void initAll() {
        System.out.println("Initializing shared heavy resource (e.g., Database Connection)...");
    }

    @BeforeEach
    public void init() {
        System.out.println("Creating temporary test file...");
    }

    @Test
    public void testOne() {
        System.out.println("Executing Test One");
    }

    @Test
    public void testTwo() {
        System.out.println("Executing Test Two");
    }

    @AfterEach
    public void tearDown() {
        System.out.println("Deleting temporary test file...");
    }

    @AfterAll
    public static void tearDownAll() {
        System.out.println("Closing shared heavy resource...");
    }
}

11. Summary and Key Takeaways

• Unit Testing isolates and verifies individual components (methods/functions), while Integration Testing verifies how multiple components interact.
• JUnit 5 (Jupiter) is the default testing framework in modern Spring Boot applications, imported transitively via spring-boot-starter-test.
• The <scope>test</scope> tag in pom.xml ensures testing libraries are excluded from production builds.
• @SpringBootTest bootstraps the entire Spring ApplicationContext, enabling dependency injection (@Autowired) within test classes to prevent NullPointerExceptions.
• Parameterized Tests (@ParameterizedTest) eliminate code duplication by running the same test logic with different inputs using @CsvSource, @ValueSource, or custom @ArgumentsSource.
• Maven Wrapper (./mvnw test) executes tests via the command line using the Maven Surefire Plugin, generating XML and TXT reports in target/surefire-reports.
• Code Coverage tools in IDEs help identify untested code paths (highlighted in red) and export interactive HTML reports for quality assurance.
• Lifecycle Annotations (@BeforeAll, @BeforeEach, @AfterEach, @AfterAll) manage setup and teardown operations to keep tests clean and isolated.