How to Load a JSON File in Spring Boot for Unit Testing

Objective

This is a practical guide to loading a JSON file in Spring Boot unit tests, using Junit 5 and a custom @LoadJsonFile annotation. I couldn’t find an existing solution in Junit 5 or Spring Boot, so I decided to create and share one.

Prerequisites

To follow this article, you need to have installed:

Implementation

The goal is to use a custom annotation @LoadJsonFile that allows loading a JSON file into a field of a test class. To achieve this, you need to use the TestInstancePostProcessor interface from Junit 5, which lets you modify the test instance before it runs.

You can then add the customization to your test class using the @ExtendWith annotation, which registers custom extensions.

Directory and File Structure

The files will be placed in the following structure under test:

src/
├── test
    ├── java
       ├── resources
       └── utilites
           ├── LoadJsonFile.java
           └── LoadJsonFilePostProcessor.java

Defining the @LoadJsonFile Annotation

package utilites;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface LoadJsonFile {
    String value();
}

Annotation Explanation

• @Retention(RetentionPolicy.RUNTIME): The annotation is available at runtime.
• @Target(ElementType.FIELD): The annotation can only be applied to class fields.
• String value(): Accepts the JSON file path as a string value. Using value allows omitting the attribute name.

Implementing the LoadJsonFilePostProcessor Class

package utilites;
public class LoadJsonFilePostProcessor implements TestInstancePostProcessor {
        private final ResourceLoader resourceLoader = new DefaultResourceLoader();
        private final ObjectMapper objectMapper = new ObjectMapper();
    @Override
    public void postProcessTestInstance(final Object testInstance, final ExtensionContext context) throws Exception {
        final Class<?> testClass = testInstance.getClass();
        for (final Field field : testClass.getDeclaredFields()) {
            final LoadJsonFile annotation = field.getAnnotation(LoadJsonFile.class);
            if (annotation != null) {
                field.setAccessible(true);
                final Object value = loadJsonFile(annotation.value(), field.getType());
                field.set(testInstance, value);
            }
        }
    }

    private <T> T loadJsonFile(final String filePath, final Class<T> type) {
        final Resource resource = resourceLoader.getResource(filePath);
        try (final InputStream inputStream = resource.getInputStream()) {
            return objectMapper.readValue(filePath, type);
        } catch (Exception e) {
            throw new RuntimeException("Failed to load JSON file: " + filePath, e);
        }
    }
}

Class Explanation

• TestInstancePostProcessor: JUnit 5 interface to modify the test instance before execution.
• ResourceLoader: Used to load resources (files) from the classpath. This ties the solution to Spring.
• ObjectMapper: Jackson class used to deserialize JSON into Java objects.
• postProcessTestInstance: Iterates over the test class fields and looks for the @LoadJsonFile annotation.
• loadJsonFile: Loads the JSON file from the provided path and converts it to the specified type.

You can find more information about TestInstancePostProcessor in the official JUnit 5 documentation.

Usage Example

@ExtendWith(MockitoExtension.class, LoadJsonFilePostProcessor.class)
public class ExampleTest {
    @LoadJsonFile("sample-data.json")
    private SampleData sampleData;

    @Test
    public void testLoadJsonFile() {
        assertNotNull(sampleData);
        assertEquals("John Doe", sampleData.getName());
        assertEquals(30, sampleData.getAge());
    }
}