WG – Spring-Style Testing Compatibility for Quarkus

[cescoffier]

Objective

Enable Spring developers to migrate to Quarkus with minimal friction by exploring and providing compatibility layers for the most common Spring testing patterns. So they don’t need to rewrite their existing tests.

Problem Statement

• Spring developers rely heavily on testing constructs like @SpringBootTest, MockMvc, TestRestTemplate, and slice-based testing.
• Quarkus, while offering its own solid testing ecosystem (e.g., @QuarkusTest, RestAssured, and Continuous Testing), doesn’t align with Spring-style testing by default.
• This mismatch forces developers to rewrite or adapt tests when switching to Quarkus.
• Reducing this friction aligns with Quarkus’s goal of enabling Spring developers to migrate without starting from scratch.

Proposed Solution

1. Survey and identify the Spring testing APIs and techniques most widely used, across unit, controller (HTTP), and integration tests.
2. Map these to their closest equivalents in Quarkus testing infrastructure (e.g., @QuarkusTest, @QuarkusIntegrationTest, RestAssured).
3. Prototype mechanisms that allow Spring-style tests to run with minimal or no modifications in Quarkus (e.g., helper annotations, compatibility layer, quarkiverse library, tooling adaptation).
4. Define a realistic scope—supporting the most used constructs only (not all of Spring’s testing API).

Definition of Done

The WG will be considered complete when the following are delivered:

• A prioritized list of Spring testing patterns (usage-informed).
• A mapping document detailing how each pattern corresponds to Quarkus approaches.
• A working prototype or POC illustrating compatibility (e.g., a mini-project demonstrating Spring tests running in Quarkus).
• PRs to Quarkus implementing support or helper utilities.
• A migration-style guide/documentation (“How to run your Spring tests in Quarkus”).
• A community-facing artifact (e.g., blog post, talk, or demo).

Scope

In Scope

• Inventory & prioritization of widely-used Spring testing APIs (unit, HTTP controller, integration).
• Feasibility analysis and prototyping for compatibility.
• Documentation drafting and an example project.
• Coordination and communication (issues, discussion threads, milestones).

⠀

Out of Scope

• Full support for the entire Spring testing API surface; treating edge cases is not critical.
• Deep re-architecting of Quarkus’s testing engine.
• UI-level or highly niche Spring testing scenarios.

Organization & Workflow

• Coordination channels: GitHub Discussions for design, Issues for tracking, GitHub Projects for progress management.
• Workgroup communication: Zulip and/or Quarkus mailing lists.
• Points of Contact: @aureamunoz and @edeandrea

⠀

[edeandrea]

I scheduled a kickoff meeting for Wednesday September 17 10:30am - 11:30am EDT.

I'll use https://docs.google.com/document/d/1lyZnSBrBpAgW8TEhGXMvWMK9NxMvHRhXJK2ueb3ULJA/edit?usp=sharing to track meeting notes, but will post a comment back here after the meeting containing all the meeting notes.

[cescoffier]

Board created: WG - Spring-Style Testing (view)

[edeandrea]

Some of my initial thoughts based on my familiarities with both Spring & Quarkus

Spring ApplicationContext slicing

Spring developers rely heavily on testing constructs like @SpringBootTest, MockMvc, TestRestTemplate, and slice-based testing, among other things.

The slice-based testing I think is the hardest/most complicated thing here due to different schools of thought between Quarkus & Spring. Most Spring tests "slice" the application context down to just what is necessary for the component under test to operate correctly, and then mocking/stubbing out the remainder of the required infrastructure.

To me, this would be similar to testing components in Quarkus, but in all honesty I've never actually been able to get it to work correctly. Maybe my Spring background is leading me down a different path so it doesn't work the way I think it should?

Spring provides a way for users to build a custom ApplicationContext for a given test class via the @TestConfiguration annotation. This would allow a user to build a test that looks like this:

// @SpringBootTest will automatically find the @TestConfiguration
@SpringBootTest
class MyTest {
  @Autowired
  private SomeBean someBean;

  @TestConfiguration
  static class TestConfigForMyTest {
    @Bean
    public SomeBean someBean() {
      // create & return an instance of the `SomeBean` class
    }

      // You could define/override other bean definitions here too
  }
}

This allows the user to build a custom ApplicationContext specific to just the components they need to test in isolation, which differs from the basic theory of how Quarkus users test their applications.

Spring Boot also provides many out-of-the-box test slicing annotations that pre-define layers within the application. The most commonly used ones (IMO) are

• @DataJdbcTest
• @DataJpaTest
• @JdbcTest
• @JsonTest
• @WebFluxTest
• @WebMvcTest

For example, when using MockMvc in conjunction with @WebMvcTest, interactions with MockMvc don't perform a "real" http request into the application. Instead, it applies mocks to the underlying DispatcherServlet infrastructure in order to bootstrap a "working" controller layer.

@WebMvcTest
class MyTest {
  @Autowired
  private MockMvc mockMvc;
}

In this case you don't get a "full" ApplicationContext. You only get things necessary for the web layer to work.

This is similar when using the @SpringBootTest annotation. When doing something like this:

@SpringBootTest
@AutoConfigureMockMvc
class MyTest {
  @Autowired
  private MockMvc mockMvc;
}

you also get the same behavior, except you get the entire application bootstrapped, albeit with "mocks" in place. The @SpringBootTest annotation has an attribute, webEnvironment, that defines how the application should be bootstrapped. The default value if unspecified is MOCK which will provide mocks of the entire web layer (servlet or reactive, depending on which libraries are on the classpath).

Currently I don't believe Quarkus has anything similar. It also stems from the paradigm shift between what Quarkus considers a unit test vs what Spring considers a unit test.

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
@AutoConfigureMockMvc
class MyTest {
  @Autowired
  private MockMvc mockMvc;
}

would give you the most equivalent to @QuarkusTest - a "real" application with "real" layers.

I find that I rely on Quarkus test profiles when I want to achieve similar functionality to Spring slices. The drawback to this is that for each different profile, Quarkus needs to restart the application with the alternate configuration.

You can also create (& test!) your own custom slicing annotations as well as your own custom @AutoConfiguration classes.

@QuarkusTest equivalent(s)

The major premise behind the way Quarkus does testing was always about scaffolding the entire application, which in the Spring ecosystem would be considered integration testing. Spring does not have a similar capability to what Quarkus has with @QuarkusIntegrationTest. The only thing you can do in Spring is test the output of a native binary, but even that Spring is relying directly on GraalVM's maven/gradle plugins/code/annotations.

@QuarkusIntegrationTest is far more powerful, being able to run the tests against the type of application being built (JVM, JVM in container, native, native in container).

Using @SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT), the Spring testing infrastructure will create a full web environment (servlet or reactive based on what is on the classpath). Then you can interact with the application in your test as a "black box", but still have full mocking capabilities.

This is an important point, as currently in @QuarkusIntegrationTests you can not mock/do bean injection/etc.

Testing http client apps

Spring also includes a built-in convention for testing code that uses http clients (RestTemplate/RestClient) - MockRestServiceServer, although they are now recommending using Wiremock or OkHttp MockWebServer

Database

Another commonly used feature in Spring tests (mostly integration-style tests) is the @Sql annotation, which can automatically change the DB schema/data on a per-test basis.

There was also a Zulip thread about this (thanks @sivaprasadreddy!). This is something that should at least be discussed as well.

DirtiesContext

What about the @DirtiesContext? @mkouba has a POC (https://quarkusio.zulipchat.com/#narrow/channel/187030-users/topic/The.20need.20for.20feedback.20-.20POC.20for.20TestState.20and.20ResetTestState/with/539896985). I feel this is way overused and not fully understood by Spring developers.

In any event, it should be part of the discussion.

[sivaprasadreddy]

This is a great initiative that helps people who are coming from Spring Boot background.

I would like to share my thoughts on how I usually approach testing in my Spring Boot applications.

1. Unit Tests: I write very small set of unit tests that doesn't depend on any Spring features using Mockito only if it is absolutely necessary.

2. Slice Tests: Spring provides slice test annotations such as @DataJpaTest, @WebMvcTest, @JsonTest, etc. Among them I use @WebMvcTest for testing all corner cases by simulating backend error scenarios.
I prefer not to use @JsonTest, @DataJpaTest etc as those scenarios will be anyway covered in integration tests.

3. Integration Tests: I write bulk of my tests using @SpringBootTest by loading the entire ApplicationContext and use Testcontainers to provision DB, MessageBrokers, etc.
When it comes to test data setup there are different schools of thought.

• The database schema initialization is usually done with Flyway or Liquibase.
• But for test data setup, I usually use SQL scripts using @Sql support.
• Using EntityManager, Repository or Service to setup test data looks good in the beginning, but soon we start creating methods only for testing and also tests start failing due to bugs unrelated to the usecase.

So, I prefer setting up test data using SQL scripts.

Another important part of testing is mocking the 3rd party API calls. I usually use WireMock for stubbing those API calls.

Now, coming to Quarkus, I like the test infra setup:

• Testcontainers Dev Services already configured
• RestAssured already configured
• QuarkusMock to mock any dependencies

From my point of view, the important piece missing from Quarkus are:

• Ability to initialize data thru SQL scripts
• Counterpart of @WebMvcTest where only web layer is loaded

Once again, thanks for this initiative. It really helps to adopt and migrate to Quarkus.

[mkouba]

To me, this would be similar to testing components in Quarkus, but in all honesty I've never actually been able to get it to work correctly. Maybe my Spring background is leading me down a different path so it doesn't work the way I think it should?

It's quite similar but the main difference is that currently there's no way how extensions can contribute the "mocks" (i.e. an alternative to @WebMvcTest). It's up to the developer to mock everything what is needed (using the Mockito API). And we should definitely try to improve this...

[edeandrea]

@sivaprasadreddy when you mention

3. Integration Tests: I write bulk of my tests using @SpringBootTest by loading the entire ApplicationContext and use Testcontainers to provision DB, MessageBrokers, etc.

Are you using @SpringBootTest? Or @SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)/@SpringBootTest(webEnvironment = WebEnvironment.DEFINED_PORT)?

I ask because there is a very important difference between what happens when webEnvironment = WebEnvironment.RANDOM_PORT/webEnvironment = WebEnvironment.RANDOM_PORT that I want to be sure is clear as part of this overall conversation because it is very important:

@SpringBootTest on its own is NOT an integration test. There is still a large amount of mocking that is going on under the covers. There isn't a "real" web layer among other things. Only when you use webEnvironment = WebEnvironment.RANDOM_PORT/webEnvironment = WebEnvironment.RANDOM_PORT do you get a "full" application with a complete ApplicationContext.

[sivaprasadreddy]

I use @SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)

[hantsy]

@sivaprasadreddy

Testcontainers Dev Services already configured

I do not know if possible to run the exact dev service for every test like testcontainers in Quarkus, eg, only run Postgres, or Kafka in one test.

In before experience, I understand Dev services is a global service to run the Quarkus application in dev and tests. Not like testocntainers, we can select which container service to run, and container lifecycle is per test method or test class.

[hantsy]

Really like this feature, slice test and a mock env autoconfigured for it is good to test small functions but not need to load all resources and dependencies as Quarkus test.

[edeandrea]

Notes from Working Group kickoff meeting on September 17, 2025:

• Notes (taken by Gemini): https://docs.google.com/document/d/1H6e-GetV82MxBiAv622zHS07WKtW0686Ta8Sl3U_U-I/edit?usp=sharing
• Transcript (taken by Gemini): https://docs.google.com/document/d/1UvnOPzbzAF_KUEYJLyAxWEnf_AVd0BuWxRf2Lln8N7s/edit?usp=sharing
• Recording: https://drive.google.com/file/d/1O-sQy2LTbUF_qMCJtlVXGdwD2UmqJBbh/view?usp=sharing

Notes (taken by Eric):

Agenda

1. Introduce group objectives, scope, organization, & workflow
   • Make life of Spring devs easier when using Quarkus, no matter whats going on under the covers?
   • Make it so tests written with Spring “stuff” still works
2. Open conversation about fundamental differences between test “slicing” in Spring vs the Quarkus school of though of “its so fast just start the whole thing”
   • What are we actually trying to accomplish? Simply emulate the slicing annotations so code compiles and works, even if under the covers the behavior is a bit different?
     • And if thats the case, what do we do about @SpringBootTest(webEnvironment = MOCK) vs @SpringBootTest(webEnvironment = RANDOM_PORT)?
   • Is there a way Quarkus can emulate these slicing annotations without changing the underlying premise of how @QuarkusTest works?

Notes

• Bruno Baptista - do we need some kind of tck? Maybe not as a TCK, but something
• How/when do current spring versions get updated?
  • No frequency defined - (ad-hoc)
• Can we solve the @SpringBootTest thing first then get to the web layer?
• Then look at the data layer (@SQL)
  • We need test class/method isolation
• Holly Cummins
  • Could we visualize all this in test mode somehow?
  • How do we do test isolation? How do users know if one test pollutes another
• Aurea Munoz Hernandez - has a spreadsheet of spring things most used (Quarkus support for Spring Annotations #44987)
• Should be in Quarkus core
• Live under a new spring-test
  • Separate by function (i.e. web/data/etc)
• Is it worthwhile building something similar to Spring's @Sql annotation that allows db updates per test/test class?
  • If so, Spring lets users live dangerously by not cleaning up things between methods/classes. We'd want to ensure some additional safety.

Action Items

• @edeandrea to start creating initial tracking items in the project tracker

[edeandrea]

I've created an initial set of issues for foundational work:

#50148 #50149 #50150 #50151 #50152