Skip to content
javahacks.dev
Quarkus

How to Test Quarkus Applications With QuarkusTest Well

Write Quarkus tests with @QuarkusTest: how the application boots once per run, REST Assured, injecting beans, test profiles, resources and continuous testing.

5 min read
Summarize in AI
Flat illustration of a test report with one failing test, with the Quarkus, GitHub Actions, JUnit5 and Jenkins logos.

Quarkus tests run the application, not a mock of it. That gives realistic results and costs a few seconds of startup, paid once. This uses Quarkus 3, JUnit Jupiter 6 and JDK 25. If you are new to the framework, start with the Quarkus tutorial.

A first test

java
@QuarkusTest
class GreetingResourceTest {

    @Test
    void helloEndpoint() {
        given()
          .when().get("/hello")
          .then()
             .statusCode(200)
             .body(is("Hello"));
    }
}

given() comes from REST Assured. Quarkus configures it with the test port, which is 8081 by default so it does not clash with a dev instance, so no host is written in the test.

Injecting beans

java
@QuarkusTest
class PriceServiceTest {

    @Inject PriceService service;

    @Test
    void appliesDiscount() {
        assertEquals(new BigDecimal("90.00"), service.priceWithDiscount("A-1", 10));
    }
}

The test class is itself a bean in the running application, which is why @Inject works. This differs from Spring Boot tests, where @SpringBootTest also loads the context but injection uses @Autowired.

Database and Dev Services

With a datasource extension and no URL configured, the test profile starts a throwaway container through Dev Services. Tests then use a real PostgreSQL, matching production, instead of a different database engine. The first run pulls the image, so allow time on CI. The container problems that follow are in could not find a valid Docker environment.

Profiles and resources

Changing configuration for a group of tests means a different application instance:

java
public class StrictProfile implements QuarkusTestProfile {
    @Override public Map<String, String> getConfigOverrides() {
        return Map.of("pricing.mode", "strict");
    }
}

@QuarkusTest
@TestProfile(StrictProfile.class)
class StrictPricingTest { /* ... */ }

Quarkus stops and restarts the application when the profile changes between classes. A handful of profiles is fine, and one per test class makes the suite slow. External systems that Dev Services does not cover, such as a mock server, use @QuarkusTestResource with a lifecycle manager.

Transactions in tests

@TestTransaction rolls back a test method's database changes at the end, which keeps tests independent without cleanup code.

Continuous testing

In dev mode press r to run tests continuously, and only affected tests rerun after a change, see dev mode.

Testing the built artifact

@QuarkusIntegrationTest runs the packaged application, native or jar, as a separate process and sends real HTTP to it. It cannot inject beans. Use it for a few smoke tests, since it proves the artifact works, a native build especially.

Security and authenticated endpoints

Endpoints behind authentication need a user in tests, and the quarkus-test-security dependency provides @TestSecurity:

java
@Test
@TestSecurity(user = "ann", roles = "admin")
void adminCanListOrders() {
    given().when().get("/orders").then().statusCode(200);
}

The annotation installs a security identity for the call, so the test needs no token and no identity provider. Add a second test with no annotation and assert 401, and a third with a different role and assert 403. When the real application uses OIDC, Dev Services can start a Keycloak container, which is slower and closer to production, so keep that for a handful of end-to-end tests.

Startup cost and how to keep it small

The application starts once per test run, and every @TestProfile change adds another start. On a laptop a small application starts in about a second or two in JVM mode, while one with a database container adds the time to start that container, typically several seconds after the first image pull. The two habits that keep a suite fast are reusing profiles and keeping the number of distinct ones small, and enabling container reuse for Dev Services in development with quarkus.devservices.reuse=true so the database is not recreated for every run.

Time, randomness and other hidden inputs

Tests that depend on the clock or on random values are flaky tests in waiting. Inject a java.time.Clock into the code that needs the current time, and replace it in the test, either with @InjectMock on the provider or with a producer in the test source set. Ids and tokens that the code generates can be asserted by shape, such as matching a UUID pattern, instead of by value.

Common failures and their causes

A test that passes alone and fails in the suite almost always shares state: a static field, a row left in the database, or a bean with application scope that remembers something. @TestTransaction fixes the database case, and the others need cleanup in @AfterEach. A Port 8081 already in use error means a previous run or dev mode is still alive, so stop it, or set quarkus.http.test-port=0 to pick a free port. A test that hangs on CI and finishes locally is usually waiting for a container image to download, which the CI cache should remove.

Testing messaging and scheduled work

A Quarkus service that consumes from Kafka or RabbitMQ gets a broker from Dev Services in tests, and with the in-memory connector for SmallRye Reactive Messaging you can skip the broker entirely. Send a message into the channel, wait for the effect with Awaitility, and assert on the database or on an outgoing channel. Never use Thread.sleep for this. await().atMost(5, SECONDS).untilAsserted(...) finishes as soon as the condition holds and fails with a useful message when it does not.

For scheduled methods, disable the scheduler in the test profile with quarkus.scheduler.enabled=false and call the method directly. Otherwise the job fires at some point during an unrelated test, and the test fails once a week for no visible reason.

Keeping tests readable

Put request bodies in small helper methods or text blocks instead of string concatenation, and keep one assertion topic per test. REST Assured reads well for status and body, and when a response gets complicated, extract it to a record with .extract().as(OrderResponse.class) and assert with AssertJ. A test that a stranger can read in thirty seconds is worth more than one that covers an extra branch.

What to put in the suite, and what to leave out

Spend @QuarkusTest on behavior that crosses the container: an endpoint with validation and an exception mapper, a transaction boundary, a configuration property that changes a result. Leave arithmetic, formatting and parsing to plain unit tests that run in a few milliseconds and need no container. A healthy balance is many small unit tests, a modest number of @QuarkusTest classes that each cover one slice of the application, and a few @QuarkusIntegrationTest smoke tests against the packaged artifact, run only on the main branch to keep pull requests quick.

Where this does not apply

Pure logic needs no container: test it as plain Java with no annotation. A mock based approach is described in mocking beans. See the Quarkus testing guide and the REST Assured usage.

Also inTesting
Taggedhow to
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.