quarkus-dev-services-and-testing

Quarkus Dev Services and Testing

Check the project's Quarkus version first. Framework-neutral Testcontainers usage can use the optional java-testcontainers skill if installed (otherwise see https://java.testcontainers.org/); this skill covers only Quarkus-specific features.

Dev Services

In dev and test modes Quarkus starts containers (PostgreSQL, MySQL, Kafka, Redis, Keycloak, ...) automatically when the related extension is present and no connection is configured (Docker or Podman required).

# Global switch
quarkus.devservices.enabled=true
%dev.quarkus.datasource.devservices.image-name=postgres:17
# Reuse container across restarts (also requires testcontainers.reuse.enable=true in ~/.testcontainers.properties)
quarkus.datasource.devservices.reuse=true
# Fixed port (optional)
quarkus.datasource.devservices.port=5432
# Share between apps in dev mode
quarkus.kafka.devservices.shared=true

Disable one with quarkus.<ext>.devservices.enabled=false; configuring a URL/host explicitly also disables it. Dev UI (/q/dev-ui) lists running services.

Tests

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

Dependencies, test scope: io.quarkus:quarkus-junit (3.31+, what the 3.40 template generates) or quarkus-junit5 (3.27 template; still published and resolvable on 3.40) and io.rest-assured:rest-assured. Keep whichever the project already uses.

• Inject beans in tests with @Inject; mock CDI beans with io.quarkus.test.InjectMock (quarkus-junit-mockito, formerly quarkus-junit5-mockito; verified mocking a PanacheRepository bean on 3.40.1).
• Security: @TestSecurity(user="alice", roles="admin") (quarkus-test-security).
• Profiles: @TestProfile(MyProfile.class) with QuarkusTestProfile#getConfigOverrides(); restarts the app, so use sparingly.
• Transactions: @TestTransaction rolls back after the test.
• @QuarkusIntegrationTest runs against the packaged artifact (jar, native binary or container); you cannot inject beans there, only call it over HTTP.

Test resources

public class WireMockResource implements QuarkusTestResourceLifecycleManager {
    public Map<String,String> start() { /* start, return config overrides */ return Map.of(); }
    public void stop() { }
}

@QuarkusTest
@WithTestResource(WireMockResource.class)   // io.quarkus.test.common.WithTestResource
class MyTest { }

@WithTestResource (verified on 3.40.1) applies to the annotated test class; Quarkus restarts the app when the set of resources changes. The older @QuarkusTestResource still compiles and runs on 3.40.1 but applies globally to all tests unless restrictToAnnotatedClass = true. Do not put @ConfigProperty injection points for resource-supplied values in a test class: test classes are scanned as beans, and the app fails to start for other test classes that lack the resource. Prefer Dev Services over custom resources when an extension supports it.

Running

./mvnw test                 # unit/@QuarkusTest
./mvnw verify -DskipITs=false  # also runs *IT via maven-failsafe-plugin

Gotcha: *IT classes (@QuarkusIntegrationTest) are run by Failsafe in the verify phase, and need the quarkus-maven-plugin build goal and the failsafe config (with java.util.logging.manager and maven.home system properties) generated by the project template. ./mvnw test silently skips them, and the 3.27 and 3.40 templates also set <skipITs>true</skipITs>, so plain ./mvnw verify skips them too (verified): pass -DskipITs=false (or -Dnative, whose profile flips it). With -Dnative and a container build on macOS or Windows, the binary is a Linux ELF and the IT fails with Exit code is: '126'; use a local Mandrel/GraalVM build for those.

Continuous testing: run ./mvnw quarkus:dev and press r to start or re-run tests and p to pause them (h lists the hotkeys); once running, tests re-run on code changes (quarkus.test.continuous-testing=enabled|paused|disabled).

Verified on Quarkus 3.40.1 (JDK 26, Docker Desktop): @QuarkusTest with Dev Services PostgreSQL (postgres:18 by default), @TestTransaction, @TestProfile, @TestSecurity, @InjectMock, *IT via Failsafe. @QuarkusTest and Dev Services on 3.27.6 as well.

Checklist

• Use Dev Services before writing a custom resource.
• Keep @QuarkusTest classes sharing the same profile/resources to avoid restarts.
• Do not hard-code ports; RestAssured uses quarkus.http.test-port automatically.

See also: https://quarkus.io/guides/dev-services, https://quarkus.io/guides/getting-started-testing; for upgrades use quarkus update (https://quarkus.io/guides/update-quarkus).