quarkus-dev-services-and-testing - Claude MCP Skill

# 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).

```properties
# 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

```java
@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

```java
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

```bash
./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>).