Spring JUnit Jupiter 测试注解

DeepSeek V3 中英对照 Spring JUnit Jupiter Testing Annotations

以下是与 SpringExtension 和 JUnit Jupiter（即 JUnit 5 中的编程模型）结合使用时支持的注解：

• @SpringJUnitConfig

• @SpringJUnitWebConfig

• @TestConstructor

• @NestedTestConfiguration

• @EnabledIf

• @DisabledIf

• @DisabledInAotMode

@SpringJUnitConfig

@SpringJUnitConfig 是一个用于集成测试的注解，结合了 JUnit Jupiter 和 Spring 测试框架的功能。它允许你在 JUnit 5 测试中使用 Spring 的配置类或 XML 配置文件来初始化 Spring 应用程序上下文。通过这个注解，你可以轻松地将 Spring 的依赖注入和配置管理集成到 JUnit 测试中，从而简化集成测试的编写。

使用 @SpringJUnitConfig 注解时，你可以指定一个或多个 Spring 配置类或 XML 配置文件路径。这些配置将用于创建 Spring 应用程序上下文，并在测试执行期间提供所需的 Bean 实例。

例如：

@SpringJUnitConfig(TestConfig.class)
public class MyIntegrationTest {

    @Autowired
    private MyService myService;

    @Test
    void testService() {
        assertNotNull(myService);
        // 测试逻辑
    }
}

java

在这个例子中，TestConfig.class 是一个 Spring 配置类，MyService 是一个 Spring Bean，通过 @Autowired 注解注入到测试类中。

@SpringJUnitConfig 是一个组合注解，它将 JUnit Jupiter 中的 @ExtendWith(SpringExtension.class) 与 Spring TestContext Framework 中的 @ContextConfiguration 结合起来。它可以在类级别上作为 @ContextConfiguration 的直接替代品使用。在配置选项方面，@ContextConfiguration 和 @SpringJUnitConfig 之间的唯一区别是，@SpringJUnitConfig 中可以使用 value 属性来声明组件类。

以下示例展示了如何使用 @SpringJUnitConfig 注解来指定配置类：

Java

@SpringJUnitConfig(TestConfig.class) 1
class ConfigurationClassJUnitJupiterSpringTests {
    // class body...
}

java

• 指定配置类。

Kotlin

@SpringJUnitConfig(TestConfig::class) 1
class ConfigurationClassJUnitJupiterSpringTests {
    // class body...
}

kotlin

• 指定配置类。

以下示例展示了如何使用 @SpringJUnitConfig 注解来指定配置文件的位置：

Java

@SpringJUnitConfig(locations = "/test-config.xml") 1
class XmlJUnitJupiterSpringTests {
    // class body...
}

java

• 指定配置文件的位置。

Kotlin

@SpringJUnitConfig(locations = ["/test-config.xml"]) 1
class XmlJUnitJupiterSpringTests {
    // class body...
}

kotlin

• 指定配置文件的位置。

请参阅 Context Management 以及 @SpringJUnitConfig 和 @ContextConfiguration 的 javadoc 以获取更多详细信息。

@SpringJUnitWebConfig

@SpringJUnitWebConfig 是一个组合注解，它将 JUnit Jupiter 中的 @ExtendWith(SpringExtension.class) 与 Spring TestContext Framework 中的 @ContextConfiguration 和 @WebAppConfiguration 结合在一起。你可以在类级别上使用它，作为 @ContextConfiguration 和 @WebAppConfiguration 的直接替代品。在配置选项方面，@ContextConfiguration 和 @SpringJUnitWebConfig 的唯一区别是，你可以通过 @SpringJUnitWebConfig 中的 value 属性声明组件类。此外，你只能通过 @SpringJUnitWebConfig 中的 resourcePath 属性来覆盖 @WebAppConfiguration 中的 value 属性。

以下示例展示了如何使用 @SpringJUnitWebConfig 注解来指定配置类：

Java

@SpringJUnitWebConfig(TestConfig.class) 1
class ConfigurationClassJUnitJupiterSpringWebTests {
    // class body...
}

java

• 指定配置类。

Kotlin

@SpringJUnitWebConfig(TestConfig::class) 1
class ConfigurationClassJUnitJupiterSpringWebTests {
    // class body...
}

kotlin

• 指定配置类。

以下示例展示了如何使用 @SpringJUnitWebConfig 注解来指定配置文件的位置：

Java

@SpringJUnitWebConfig(locations = "/test-config.xml") 1
class XmlJUnitJupiterSpringWebTests {
    // class body...
}

java

• 指定配置文件的位置。

Kotlin

@SpringJUnitWebConfig(locations = ["/test-config.xml"]) 1
class XmlJUnitJupiterSpringWebTests {
    // class body...
}

kotlin

• 指定配置文件的位置。

请参阅 Context Management 以及 @SpringJUnitWebConfig、@ContextConfiguration 和 @WebAppConfiguration 的 Javadoc 以获取更多详细信息。

@TestConstructor

@TestConstructor 是一个可以应用于测试类的注解，用于配置如何从测试的 ApplicationContext 中的组件自动装配测试类构造函数的参数。

如果 @TestConstructor 未在测试类上出现或元出现，将使用默认的 测试构造函数自动装配模式。有关如何更改默认模式的详细信息，请参阅下面的提示。但是请注意，构造函数上的 @Autowired、@jakarta.inject.Inject 或 @javax.inject.Inject 的本地声明优先于 @TestConstructor 和默认模式。

提示

更改默认的测试构造函数自动装配模式

可以通过将 spring.test.constructor.autowire.mode JVM 系统属性设置为 all 来更改默认的测试构造函数自动装配模式。或者，也可以通过 SpringProperties 机制来设置默认模式。

默认模式也可以配置为 JUnit 平台配置参数。

如果未设置 spring.test.constructor.autowire.mode 属性，则测试类构造函数将不会自动装配。

备注

@TestConstructor 仅在与 JUnit Jupiter 的 SpringExtension 一起使用时受支持。请注意，SpringExtension 通常会为您自动注册——例如，在使用 @SpringJUnitConfig 和 @SpringJUnitWebConfig 等注解时，或使用 Spring Boot Test 中的各种测试相关注解时。

@NestedTestConfiguration

@NestedTestConfiguration 是一个可以应用于测试类的注解，用于配置在内部测试类的封闭类层次结构中如何处理 Spring 测试配置注解。

如果 @NestedTestConfiguration 注解没有出现在测试类、其超类层次结构或其封闭类层次结构中，则将使用默认的封闭配置继承模式。有关如何更改默认模式的详细信息，请参阅下面的提示。

提示

更改默认的封闭配置继承模式

默认的封闭配置继承模式是 INHERIT，但可以通过将 spring.test.enclosing.configuration JVM 系统属性设置为 OVERRIDE 来更改。或者，也可以通过 SpringProperties 机制来设置默认模式。

Spring TestContext 框架 对于以下注解遵循 @NestedTestConfiguration 语义。

• @BootstrapWith

• @ContextConfiguration

• @WebAppConfiguration

• @ContextHierarchy

• @ContextCustomizerFactories

• @ActiveProfiles

• @TestPropertySource

• @DynamicPropertySource

• @DirtiesContext

• @TestExecutionListeners

• @RecordApplicationEvents

• @Transactional

• @Commit

• @Rollback

• @Sql

• @SqlConfig

• @SqlMergeMode

• @TestConstructor

备注

@NestedTestConfiguration 的使用通常只在与 JUnit Jupiter 中的 @Nested 测试类结合时才有意义；然而，可能还有其他支持 Spring 和嵌套测试类的测试框架会使用此注解。

请参阅 @Nested 测试类配置 以获取示例和更多详细信息。

@EnabledIf

@EnabledIf 用于表示被注解的 JUnit Jupiter 测试类或测试方法已启用，如果提供的 expression 计算结果为 true，则应运行该测试。具体来说，如果表达式计算结果为 Boolean.TRUE 或等于 true（忽略大小写）的 String，则测试被启用。当在类级别应用时，该类中的所有测试方法默认也会自动启用。

表达式可以是以下任意一种：

• Spring 表达式语言 (SpEL) 表达式。例如：@EnabledIf("#{systemProperties['os.name'].toLowerCase().contains('mac')}")

• Spring 环境 中可用属性的占位符。例如：@EnabledIf("${smoke.tests.enabled}")

• 文本字面量。例如：@EnabledIf("true")

需要注意的是，一个不是属性占位符动态解析结果的文本字面量实际上没有实用价值，因为 @EnabledIf("false") 等同于 @Disabled，而 @EnabledIf("true") 在逻辑上是没有意义的。

你可以使用 @EnabledIf 作为元注解来创建自定义的组合注解。例如，你可以创建一个自定义的 @EnabledOnMac 注解，如下所示：

Java

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@EnabledIf(
    expression = "#{systemProperties['os.name'].toLowerCase().contains('mac')}",
    reason = "Enabled on Mac OS"
)
public @interface EnabledOnMac {}

java

Kotlin

@Target(AnnotationTarget.TYPE, AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
@EnabledIf(
        expression = "#{systemProperties['os.name'].toLowerCase().contains('mac')}",
        reason = "Enabled on Mac OS"
)
annotation class EnabledOnMac {}

kotlin

备注

@EnabledOnMac 仅作为可能性的示例。如果你有完全相同的用例，请使用 JUnit Jupiter 中内置的 @EnabledOnOs(MAC) 支持。

注意

自 JUnit 5.7 起，JUnit Jupiter 也有一个名为 @EnabledIf 的条件注解。因此，如果您希望使用 Spring 的 @EnabledIf 支持，请确保从正确的包中导入注解类型。

@DisabledIf

这是一个用于集成测试的 JUnit Jupiter 注解，用于在某些条件下禁用测试方法或测试类。@DisabledIf 允许你指定一个条件表达式，如果该表达式的结果为 true，则相关的测试将被禁用。

@DisabledIf 用于标记被注解的 JUnit Jupiter 测试类或测试方法为禁用状态，如果提供的 expression 计算结果为 true，则不应运行该测试。具体来说，如果表达式计算结果为 Boolean.TRUE 或与 true（忽略大小写）相等的 String，则测试将被禁用。当在类级别应用时，该类中的所有测试方法也会自动被禁用。

表达式可以是以下任意一种：

• Spring 表达式语言 (SpEL) 表达式。例如：@DisabledIf("#{systemProperties['os.name'].toLowerCase().contains('mac')}")

• Spring 环境 中可用属性的占位符。例如：@DisabledIf("${smoke.tests.disabled}")

• 文本字面量。例如：@DisabledIf("true")

需要注意的是，如果文本字面量不是属性占位符动态解析的结果，那么它实际上没有实用价值，因为 @DisabledIf("true") 等同于 @Disabled，而 @DisabledIf("false") 在逻辑上是没有意义的。

你可以使用 @DisabledIf 作为元注解来创建自定义的组合注解。例如，你可以创建一个自定义的 @DisabledOnMac 注解，如下所示：

Java

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@DisabledIf(
    expression = "#{systemProperties['os.name'].toLowerCase().contains('mac')}",
    reason = "Disabled on Mac OS"
)
public @interface DisabledOnMac {}

java

Kotlin

@Target(AnnotationTarget.TYPE, AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
@DisabledIf(
        expression = "#{systemProperties['os.name'].toLowerCase().contains('mac')}",
        reason = "Disabled on Mac OS"
)
annotation class DisabledOnMac {}

kotlin

备注

@DisabledOnMac 仅作为一个可能性的示例。如果你有完全相同的用例，请使用 JUnit Jupiter 内置的 @DisabledOnOs(MAC) 支持。

注意

自 JUnit 5.7 起，JUnit Jupiter 也有一个名为 @DisabledIf 的条件注解。因此，如果你想使用 Spring 的 @DisabledIf 支持，请确保从正确的包中导入注解类型。