Using Quarkus Dev Services for Zero-Config Integration Tests

Problem: Repetitive Test Setup

When integration tests need a real database, teams often write Docker Compose files, start containers in @BeforeAll methods, and tear them down later. This adds boilerplate, slows the test suite, and can cause environment drift between local machines and CI.

How Quarkus Dev Services Help

Dev Services automatically launch a lightweight container the first time a test requests a resource such as a javax.sql.DataSource. The container gets a random port, is wired into the application configuration, and is shut down when the test suite ends. No Docker Compose file or manual lifecycle code is required.

Worked Example: PostgreSQL Dev Service

import io.quarkus.test.junit.QuarkusTest;
import jakarta.inject.Inject;
import org.junit.jupiter.api.Test;
import java.sql.Connection;
import java.sql.Statement;
import java.sql.ResultSet;
import static org.junit.jupiter.api.Assertions.assertTrue;

@QuarkusTest
public class UserResourceTest {
    @Inject
    javax.sql.DataSource ds;

    @Test
    void testSimpleQuery() {
        try (Connection conn = ds.getConnection();
             Statement stmt = conn.createStatement();
             ResultSet rs = stmt.executeQuery("SELECT 1")) {
            assertTrue(rs.next());
        }
    }
}

Add the following dependencies to your pom.xml (or build.gradle):

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-junit5</artifactId>
</dependency>
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-jdbc-postgresql</artifactId>
</dependency>

Run mvn test. The console will show a line similar to:

Starting Dev Service for jdbc-postgresql...

The test executes against a real PostgreSQL instance on a random port, and the container stops after the test suite finishes.

Trade-offs and Limitations

• Dev Services require Docker; if the CI runner lacks Docker, the test will fail to start the container.
• Containers are ephemeral; any data you expect to persist across test runs is lost unless you configure explicit volume mounts, which can mask state-related bugs.
• Startup overhead adds a few seconds to the first test; subsequent tests in the same suite reuse the same container.

To verify that Dev Services are working, check the test logs for the container start message and confirm that the Docker process disappears after the suite ends (e.g., run docker ps before and after mvn test).

Actionable Closing

If you are starting a new Quarkus project or adding integration tests, include the quarkus-junit5 and appropriate Dev Service extensions (e.g., quarkus-jdbc-postgresql, quarkus-reactive-pg-client, quarkus-smallrye-kafka). Let Dev Services handle the container lifecycle locally and in CI, but keep a separate staging-environment test suite for production-specific configurations.