Improve Javadoc of slice test annotations

snicoll · snicoll · commit f1e5108b595a · 2024-08-19T16:19:18.000+02:00
This commit harmonizes the phrasing that we use to describe what components are considered for scanning when a slice test is enabled. This makes the description of the default filter explicit, with an exhaustive description of the annotations and/or base classes. Closes gh-41914
diff --git a/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/data/cassandra/DataCassandraTest.java b/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/data/cassandra/DataCassandraTest.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2020 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -40,8 +40,9 @@
  * Annotation that can be used for a Cassandra test that focuses <strong>only</strong> on
  * Cassandra components.
  * <p>
- * Using this annotation will disable full auto-configuration and instead apply only
- * configuration relevant to Cassandra tests.
+ * Using this annotation only enables auto-configuration that is relevant to Data Casandra
+ * tests. Similarly, component scanning is limited to Cassandra repositories and entities
+ * ({@code @Table}).
  * <p>
  * When using JUnit 4, this annotation should be used in combination with
  * {@code @RunWith(SpringRunner.class)}.
diff --git a/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/data/couchbase/DataCouchbaseTest.java b/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/data/couchbase/DataCouchbaseTest.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2022 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -40,8 +40,9 @@
  * Annotation that can be used for a Data Couchbase test that focuses
  * <strong>only</strong> on Data Couchbase components.
  * <p>
- * Using this annotation will disable full auto-configuration and instead apply only
- * configuration relevant to Data Couchbase tests.
+ * Using this annotation only enables auto-configuration that is relevant to Data
+ * Couchbase tests. Similarly, component scanning is limited to Couchbase repositories and
+ * entities ({@code @Document}).
  * <p>
  * When using JUnit 4, this annotation should be used in combination with
  * {@code @RunWith(SpringRunner.class)}.
diff --git a/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/data/elasticsearch/DataElasticsearchTest.java b/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/data/elasticsearch/DataElasticsearchTest.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2022 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -40,8 +40,9 @@
  * Annotation that can be used for a Data Elasticsearch test that focuses
  * <strong>only</strong> on Data Elasticsearch components.
  * <p>
- * Using this annotation will disable full auto-configuration and instead apply only
- * configuration relevant to Data Elasticsearch tests.
+ * Using this annotation only enables auto-configuration that is relevant to Data
+ * Elasticsearch tests. Similarly, component scanning is limited to Elasticsearch
+ * repositories and entities ({@code @Document}).
  * <p>
  * When using JUnit 4, this annotation should be used in combination with
  * {@code @RunWith(SpringRunner.class)}.
diff --git a/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/data/jdbc/DataJdbcTest.java b/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/data/jdbc/DataJdbcTest.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2022 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -43,9 +43,9 @@
  * Annotation that can be used for a Data JDBC test that focuses <strong>only</strong> on
  * Data JDBC components.
  * <p>
- * Using this annotation will disable full auto-configuration, scan for
- * {@code AbstractJdbcConfiguration} subclasses, and apply only configuration relevant to
- * Data JDBC tests.
+ * Using this annotation only enables auto-configuration that is relevant to Data JDBC
+ * tests. Similarly, component scanning is limited to JDBC repositories and entities
+ * ({@code @Table}), as well as beans that implement {@code AbstractJdbcConfiguration}.
  * <p>
  * By default, tests annotated with {@code @DataJdbcTest} are transactional and roll back
  * at the end of each test. They also use an embedded in-memory database (replacing any
diff --git a/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/data/ldap/DataLdapTest.java b/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/data/ldap/DataLdapTest.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2019 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -40,8 +40,9 @@
  * Annotation that can be used for an LDAP test that focuses <strong>only</strong> on LDAP
  * components.
  * <p>
- * Using this annotation will disable full auto-configuration and instead apply only
- * configuration relevant to LDAP tests.
+ * Using this annotation only enables auto-configuration that is relevant to Data LDAP
+ * tests. Similarly, component scanning is limited to LDAP repositories and entities
+ * ({@code @Entry}).
  * <p>
  * By default, tests annotated with {@code @DataLdapTest} will use an embedded in-memory
  * LDAP process (if available).
diff --git a/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/data/mongo/DataMongoTest.java b/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/data/mongo/DataMongoTest.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2022 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -40,8 +40,9 @@
  * Annotation that can be used for a MongoDB test that focuses <strong>only</strong> on
  * MongoDB components.
  * <p>
- * Using this annotation will disable full auto-configuration and instead apply only
- * configuration relevant to MongoDB tests.
+ * Using this annotation only enables auto-configuration that is relevant to Data Mongo
+ * tests. Similarly, component scanning is limited to Mongo repositories and entities
+ * ({@code @Document}).
  * <p>
  * When using JUnit 4, this annotation should be used in combination with
  * {@code @RunWith(SpringRunner.class)}.
diff --git a/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/data/neo4j/DataNeo4jTest.java b/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/data/neo4j/DataNeo4jTest.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2020 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -41,8 +41,9 @@
  * Annotation that can be used for a Neo4j test that focuses <strong>only</strong> on
  * Neo4j components.
  * <p>
- * Using this annotation will disable full auto-configuration and instead apply only
- * configuration relevant to Neo4j tests.
+ * Using this annotation only enables auto-configuration that is relevant to Data Neo4j
+ * tests. Similarly, component scanning is limited to Neo4j repositories and entities
+ * ({@code @Node} and {@code @RelationshipProperties}).
  * <p>
  * By default, tests annotated with {@code @DataNeo4jTest} are transactional with the
  * usual test-related semantics (i.e. rollback by default). This feature is not supported
diff --git a/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/data/r2dbc/DataR2dbcTest.java b/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/data/r2dbc/DataR2dbcTest.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2020 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -39,8 +39,9 @@
  * Annotation that can be used for a R2DBC test that focuses <strong>only</strong> on Data
  * R2DBC components.
  * <p>
- * Using this annotation will disable full auto-configuration and instead apply only
- * configuration relevant to Data R2DBC tests.
+ * Using this annotation only enables auto-configuration that is relevant to Data R2DBC
+ * tests. Similarly, component scanning is limited to R2DBC repositories and entities
+ * ({@code @Table}).
  * <p>
  * When using JUnit 4, this annotation should be used in combination with
  * {@code @RunWith(SpringRunner.class)}.
diff --git a/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/data/redis/DataRedisTest.java b/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/data/redis/DataRedisTest.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2019 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -40,8 +40,9 @@
  * Annotation for a Data Redis test that focuses <strong>only</strong> on Redis
  * components.
  * <p>
- * Using this annotation will disable full auto-configuration and instead apply only
- * configuration relevant to Redis tests.
+ * Using this annotation only enables auto-configuration that is relevant to Data Redis
+ * tests. Similarly, component scanning is limited to Redis repositories and entities
+ * ({@code @RedisHash}).
  * <p>
  * When using JUnit 4, this annotation should be used in combination with
  * {@code @RunWith(SpringRunner.class)}.
diff --git a/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/jdbc/JdbcTest.java b/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/jdbc/JdbcTest.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2019 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -41,8 +41,9 @@
 /**
  * Annotation for a JDBC test that focuses <strong>only</strong> on JDBC-based components.
  * <p>
- * Using this annotation will disable full auto-configuration and instead apply only
- * configuration relevant to JDBC tests.
+ * Using this annotation only enables auto-configuration that is relevant to JDBC
+ * tests. Similarly, component scanning is configured to skip regular components and
+ * configuration properties.
  * <p>
  * By default, tests annotated with {@code @JdbcTest} are transactional and roll back at
  * the end of each test. They also use an embedded in-memory database (replacing any
diff --git a/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/jooq/JooqTest.java b/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/jooq/JooqTest.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2022 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -41,8 +41,9 @@
 /**
  * Annotation for a jOOQ test that focuses <strong>only</strong> on jOOQ-based components.
  * <p>
- * Using this annotation will disable full auto-configuration and instead apply only
- * configuration relevant to jOOQ tests.
+ * Using this annotation only enables auto-configuration that is relevant to jOOQ
+ * tests. Similarly, component scanning is configured to skip regular components and
+ * configuration properties.
  * <p>
  * By default, tests annotated with {@code @JooqTest} use the configured database. If you
  * want to replace any explicit or usually auto-configured DataSource by an embedded
diff --git a/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/json/JsonTest.java b/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/json/JsonTest.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2023 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -42,9 +42,16 @@
 /**
  * Annotation for a JSON test that focuses <strong>only</strong> on JSON serialization.
  * <p>
- * Using this annotation will disable full auto-configuration and instead apply only
- * configuration relevant to JSON tests (i.e. {@code @JsonComponent}, Jackson
- * {@code Module})
+ * Using this annotation only enables auto-configuration that is relevant to JSON tests.
+ * Similarly, component scanning is limited to beans annotated with:
+ * <ul>
+ * <li>{@code @JsonComponent}</li>
+ * </ul>
+ * <p>
+ * as well as beans that implement:
+ * <ul>
+ * <li>{@code Module}, if Jackson is available</li>
+ * </ul>
  * <p>
  * By default, tests annotated with {@code JsonTest} will also initialize
  * {@link JacksonTester}, {@link JsonbTester} and {@link GsonTester} fields. More
diff --git a/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/orm/jpa/DataJpaTest.java b/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/orm/jpa/DataJpaTest.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2021 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -44,8 +44,9 @@
 /**
  * Annotation for a JPA test that focuses <strong>only</strong> on JPA components.
  * <p>
- * Using this annotation will disable full auto-configuration and instead apply only
- * configuration relevant to JPA tests.
+ * Using this annotation only enables auto-configuration that is relevant to Data JPA
+ * tests. Similarly, component scanning is limited to JPA repositories and entities
+ * ({@code @Entity}).
  * <p>
  * By default, tests annotated with {@code @DataJpaTest} are transactional and roll back
  * at the end of each test. They also use an embedded in-memory database (replacing any
diff --git a/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/web/client/RestClientTest.java b/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/web/client/RestClientTest.java
@@ -34,7 +34,6 @@
 import org.springframework.context.annotation.ComponentScan;
 import org.springframework.core.annotation.AliasFor;
 import org.springframework.core.env.Environment;
-import org.springframework.stereotype.Component;
 import org.springframework.test.context.BootstrapWith;
 import org.springframework.test.context.junit.jupiter.SpringExtension;
 import org.springframework.test.web.client.MockRestServiceServer;
@@ -45,9 +44,16 @@
  * Annotation for a Spring rest client test that focuses <strong>only</strong> on beans
  * that use {@link RestTemplateBuilder} or {@link Builder RestClient.Builder}.
  * <p>
- * Using this annotation will disable full auto-configuration and instead apply only
- * configuration relevant to rest client tests (i.e. Jackson or GSON auto-configuration
- * and {@code @JsonComponent} beans, but not regular {@link Component @Component} beans).
+ * Using this annotation only enables auto-configuration that is relevant to rest client
+ * tests. Similarly, component scanning is limited to beans annotated with:
+ * <ul>
+ * <li>{@code @JsonComponent}</li>
+ * </ul>
+ * <p>
+ * as well as beans that implement:
+ * <ul>
+ * <li>{@code Module}, if Jackson is available</li>
+ * </ul>
  * <p>
  * By default, tests annotated with {@code RestClientTest} will also auto-configure a
  * {@link MockRestServiceServer}. For more fine-grained control the
diff --git a/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/web/reactive/WebFluxTest.java b/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/web/reactive/WebFluxTest.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2020 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -44,11 +44,24 @@
  * Annotation that can be used for a Spring WebFlux test that focuses
  * <strong>only</strong> on Spring WebFlux components.
  * <p>
- * Using this annotation will disable full auto-configuration and instead apply only
- * configuration relevant to WebFlux tests (i.e. {@code @Controller},
- * {@code @ControllerAdvice}, {@code @JsonComponent},
- * {@code Converter}/{@code GenericConverter}, and {@code WebFluxConfigurer} beans but not
- * {@code @Component}, {@code @Service} or {@code @Repository} beans).
+ * Using this annotation only enables auto-configuration that is relevant to WebFlux
+ * tests. Similarly, component scanning is limited to beans annotated with:
+ * <ul>
+ * <li>{@code @Controller}</li>
+ * <li>{@code @ControllerAdvice}</li>
+ * <li>{@code @JsonComponent}</li>
+ * </ul>
+ * <p>
+ * as well as beans that implement:
+ * <ul>
+ * <li>{@code Converter}</li>
+ * <li>{@code GenericConverter}</li>
+ * <li>{@code IDialect}, if Thymeleaf is available</li>
+ * <li>{@code Module}, if Jackson is available</li>
+ * <li>{@code WebExceptionHandler}</li>
+ * <li>{@code WebFluxConfigurer}</li>
+ * <li>{@code WebFilter}</li>
+ * </ul>
  * <p>
  * By default, tests annotated with {@code @WebFluxTest} will also auto-configure a
  * {@link WebTestClient}. For more fine-grained control of WebTestClient the
diff --git a/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/web/servlet/WebMvcTest.java b/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/web/servlet/WebMvcTest.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2020 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -43,12 +43,32 @@
  * Annotation that can be used for a Spring MVC test that focuses <strong>only</strong> on
  * Spring MVC components.
  * <p>
- * Using this annotation will disable full auto-configuration and instead apply only
- * configuration relevant to MVC tests (i.e. {@code @Controller},
- * {@code @ControllerAdvice}, {@code @JsonComponent},
- * {@code Converter}/{@code GenericConverter}, {@code Filter}, {@code WebMvcConfigurer}
- * and {@code HandlerMethodArgumentResolver} beans but not {@code @Component},
- * {@code @Service} or {@code @Repository} beans).
+ * Using this annotation only enables auto-configuration that is relevant to MVC tests.
+ * Similarly, component scanning is limited to beans annotated with:
+ * <ul>
+ * <li>{@code @Controller}</li>
+ * <li>{@code @ControllerAdvice}</li>
+ * <li>{@code @JsonComponent}</li>
+ * </ul>
+ * <p>
+ * as well as beans that implement:
+ * <ul>
+ * <li>{@code Converter}</li>
+ * <li>{@code DelegatingFilterProxyRegistrationBean}</li>
+ * <li>{@code ErrorAttributes}</li>
+ * <li>{@code Filter}</li>
+ * <li>{@code FilterRegistrationBean}</li>
+ * <li>{@code GenericConverter}</li>
+ * <li>{@code HandlerInterceptor}</li>
+ * <li>{@code HandlerMethodArgumentResolver}</li>
+ * <li>{@code HttpMessageConverter}</li>
+ * <li>{@code IDialect}, if Thymeleaf is available</li>
+ * <li>{@code Module}, if Jackson is available</li>
+ * <li>{@code SecurityFilterChain}</li>
+ * <li>{@code WebMvcConfigurer}</li>
+ * <li>{@code WebMvcRegistrations}</li>
+ * <li>{@code WebSecurityConfigurer}</li>
+ * </ul>
  * <p>
  * By default, tests annotated with {@code @WebMvcTest} will also auto-configure Spring
  * Security and {@link MockMvc} (include support for HtmlUnit WebClient and Selenium
diff --git a/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/webservices/server/WebServiceServerTest.java b/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/webservices/server/WebServiceServerTest.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2021 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -39,10 +39,16 @@
  * Annotation that can be used for a typical Spring web service server test. Can be used
  * when a test focuses <strong>only</strong> on Spring WS endpoints.
  * <p>
- * Using this annotation will disable full auto-configuration and instead apply only
- * configuration relevant to Web Service server tests (i.e. {@code Endpoint} and
- * {@code EndpointInterceptor} beans but not {@code @Component}, {@code @Service} or
- * {@code @Repository} beans).
+ * Using this annotation only enables auto-configuration that is relevant to Web Service
+ * Server tests. Similarly, component scanning is limited to beans annotated with:
+ * <ul>
+ * <li>{@code @Endpoint}</li>
+ * </ul>
+ * <p>
+ * as well as beans that implement:
+ * <ul>
+ * <li>{@code EndpointInterceptor}</li>
+ * </ul>
  * <p>
  * Typically {@code WebServiceServerTest} is used in combination with
  * {@link org.springframework.boot.test.mock.mockito.MockBean @MockBean} or
