quarkus-dev-services-and-testing

用途

本技能面向 Quarkus 应用的开发期依赖服务与自动化测试，重点在于减少手工配置容器和测试基础设施的成本。文档开头要求先检查项目的 Quarkus 版本；框架中立的 Testcontainers 用法可参考可选的 java-testcontainers 技能（未安装时见 https://java.testcontainers.org/），本技能只覆盖 Quarkus 特有功能。

Dev Services

在 dev 和 test 模式下，当相关扩展存在且未配置连接信息时，Quarkus 会自动启动容器（PostgreSQL、MySQL、Kafka、Redis、Keycloak 等），需要 Docker 或 Podman。

# 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

可通过 quarkus.<ext>.devservices.enabled=false 单独禁用；显式配置 URL/host 也会使其禁用。Dev UI（/q/dev-ui）会列出正在运行的服务。

测试

@QuarkusTest 示例：

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

测试作用域依赖：io.quarkus:quarkus-junit（3.31+，3.40 模板生成）或 quarkus-junit5（3.27 模板；在 3.40 上仍发布且可解析），以及 io.rest-assured:rest-assured。保持项目已使用的那一个。

在测试中用 @Inject 注入 bean；用 io.quarkus.test.InjectMock 模拟 CDI bean（quarkus-junit-mockito，原 quarkus-junit5-mockito；已在 3.40.1 上验证模拟 PanacheRepository bean）。

安全：@TestSecurity(user="alice", roles="admin")（quarkus-test-security）。

配置档：@TestProfile(MyProfile.class) 配合 QuarkusTestProfile#getConfigOverrides()；会重启应用，应少用。

事务：@TestTransaction 在测试后回滚。

@QuarkusIntegrationTest 针对打包产物（jar、原生二进制或容器）运行；其中不能注入 bean，只能通过 HTTP 调用。

测试资源

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（已在 3.40.1 验证）作用于被注解的测试类；资源集合变化时 Quarkus 会重启应用。较旧的 @QuarkusTestResource 在 3.40.1 上仍可编译运行，但除非 restrictToAnnotatedClass = true，否则全局作用于所有测试。不要在测试类中为资源提供的值放置 @ConfigProperty 注入点：测试类会被扫描为 bean，缺少该资源的其他测试类会启动失败。当扩展支持时，优先使用 Dev Services 而非自定义资源。

运行

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

注意：*IT 类（@QuarkusIntegrationTest）由 Failsafe 在 verify 阶段运行，需要项目模板生成的 quarkus-maven-plugin build goal 和 failsafe 配置（含 java.util.logging.manager 和 maven.home 系统属性）。./mvnw test 会静默跳过它们，3.27 和 3.40 模板也设置了 <skipITs>true</skipITs>，因此普通 ./mvnw verify 也会跳过（已验证）：需传 -DskipITs=false（或 -Dnative，其 profile 会翻转它）。在 macOS 或 Windows 上使用 -Dnative 和容器构建时，二进制是 Linux ELF，IT 会失败并报 Exit code is: '126'；这些平台应使用本地 Mandrel/GraalVM 构建。

持续测试：运行 ./mvnw quarkus:dev，按 r 启动或重跑测试，按 p 暂停（h 列出热键）；运行后测试会在代码变更时自动重跑（quarkus.test.continuous-testing=enabled|paused|disabled）。

已验证于 Quarkus 3.40.1（JDK 26、Docker Desktop）：@QuarkusTest 配合 Dev Services PostgreSQL（默认 postgres:18）、@TestTransaction、@TestProfile、@TestSecurity、@InjectMock、经 Failsafe 的 *IT；@QuarkusTest 和 Dev Services 也在 3.27.6 上验证。

检查清单

在编写自定义资源前先使用 Dev Services。
让 @QuarkusTest 类共享相同的 profile/资源，以避免重启。
不要硬编码端口；RestAssured 会自动使用 quarkus.http.test-port。

延伸阅读：https://quarkus.io/guides/dev-services、https://quarkus.io/guides/getting-started-testing；升级使用 quarkus update（https://quarkus.io/guides/update-quarkus）。

技能介绍

用途

Dev Services

测试

测试资源

运行

检查清单