Profile Your Tests. Speed Up Your Build. Ship Faster 🚤

Spring's TestContext Context Caching is one of the most unknown hidden gems of testing with Spring Boot - it can cut your build times in half, and often even more. Yet most developers aren't aware of it, and once they discover it, they need a tool to tell them how to optimize their test suite. That's where the Spring Test Profiler comes in.

The Spring Test Profiler is a Spring Test utility that provides visualization and insights for Spring Test execution, with a focus on Spring context caching. It helps you identify optimization opportunities in your Spring Test suite to speed up your builds and ship to production faster and with more confidence.

Fast build times = fast feedback and accelerated feature delivery!

Find more information about the profiler on our website.

Features

Overall goal: Identify optimization opportunities in your Spring Test suite to speed up your builds and ship to production faster and with more confidence 🚤

This profiler helps you:

• Track Spring Test context caching statistics for your test suite
• Show context reuse metrics and cache hit/miss ratios
• Identify tests that couldn't reuse contexts and explain why
• Easy integration with a spring.factories file or @TestExecutionListeners annotation
• Works with both Maven Surefire/Failsafe and Gradle test tasks

Requirements

This profiler works with Java 17+ and is compatible with:

• Spring Framework 5 (Spring Boot 2)
• Spring Framework 6 (Spring Boot 3)
• Spring Framework 7 (Spring Boot 4)

Prototype Phase

[!WARNING] This project is highly work-in-progress and should be considered a prototype to gather feedback and ideas for future development.

What's currently not working or missing:

• Support for parallel test execution
• Fully-fledged visualization of the contexts on a timeline
• For each Gradle test task, a separate HTML report is generated
• For Surefire and Failsafe, a separate HTML report is generated

Usage

1. Add the Dependency

Quick Start Maven

Add the dependency to your project:

<dependency>
  <groupId>digital.pragmatech.testing</groupId>
  <artifactId>spring-test-profiler</artifactId>
  <version>0.1.1</version>
  <scope>test</scope>
</dependency>

Quick Start Gradle

Add the dependency to your project:

testRuntimeOnly("digital.pragmatech.testing:spring-test-profiler:0.1.1")

2. Activate the Profiler

Pick either one of the following methods to activate the profiler in your tests.

Automatically for all Your Tests (Recommended)

Add a file named META-INF/spring.factories to your resources directory with the following content:

org.springframework.test.context.TestExecutionListener=\
digital.pragmatech.testing.SpringTestProfilerListener
org.springframework.context.ApplicationContextInitializer=\
digital.pragmatech.testing.diagnostic.ContextDiagnosticApplicationInitializer

Manually for Specific Tests

Add the @TestExecutionListeners and @ContextConfiguration annotations to your test classes:

@TestExecutionListeners(
  value = {SpringTestProfilerListener.class},
  mergeMode = TestExecutionListeners.MergeMode.MERGE_WITH_DEFAULTS
)
@ContextConfiguration(initializers = ContextDiagnosticApplicationInitializer.class)

This needs to be done for each test class where you want to use the profiler. Preferably, use this on a central abstract integration test class or use the automatic activation method above.

3. Run Your Tests

Execute your tests:

# Maven
./mvnw verify

# Gradle
./gradlew build

4. Analyze the Generated Report

After test execution, find the HTML report at:

• Maven: target/spring-test-profiler/latest.html
• Gradle: build/spring-test-profiler/latest.html

5. Add Custom Context Customizer Descriptions

Spring Test Profiler can show richer context customizer details when your project exposes a ContextCustomizerExtension bean. This is useful when a customizer class is the same across test contexts, but its internal configuration is different. A common example is a WireMock WireMockContextCustomizer: two tests can both use the same customizer class, while each test configures different mock names, ports, files, or properties.

Create a Spring bean in your test application context, for example with @Component or a test @Bean method:

package com.example.testing;

import digital.pragmatech.testing.extensions.ContextCustomizerExtension;
import org.springframework.stereotype.Component;

@Component
class ExampleContextCustomizerExtension implements ContextCustomizerExtension {

  @Override
  public boolean supports(Object contextCustomizer) {
    // Return true only for the customizer type this extension knows how to describe.
    return contextCustomizer.getClass().getName().contains("ExampleContextCustomizer");
  }

  @Override
  public String describe(Object contextCustomizer) {
    // Return a stable, human-readable summary of the fields that make contexts differ.
    return contextCustomizer.getClass().getSimpleName() + "[configuration=custom]";
  }
}

The supports(...) method should be narrow: check the exact customizer class or a known interface. The describe(...) method should include only deterministic configuration values that help explain why Spring created a separate context. Avoid identity hashes, timestamps, random ports, or other values that change between runs unless they are the actual configuration you want to compare.

If no extension supports a customizer, the report falls back to the customizer class simple name.

Demo Report

Access a demo Spring Test Profiler report here.

Bug Reports

Found a bug? Please help us improve by reporting it:

1. Search existing issues at https://github.com/PragmaTech-GmbH/spring-test-profiler/issues
2. Create a new issue with:
3. Clear description of the problem
4. Steps to reproduce
5. Expected vs actual behavior
6. Java/Spring/JUnit versions
7. Relevant log output or screenshots

Contributing

We welcome contributions! Here's how to get started:

Development Setup

1. Fork and clone the repository
2. Activate pre-commit hooks (this ensures compliant code formatting): pre-commit install (pre-commit download)
3. Build the project:

./mvnw install

1. Run tests:

./mvnw test

1. Use conventional commit messages for your changes (e.g., feat: add new feature, fix: resolve issue #123)