Document that spring.profiles.active is ignored by @ActiveProfiles

framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-activeprofiles.adoc

@@ -72,6 +72,12 @@ bean definition profiles programmatically by implementing a custom
 xref:testing/testcontext-framework/ctx-management/env-profiles.adoc#testcontext-ctx-management-env-profiles-ActiveProfilesResolver[`ActiveProfilesResolver`]
 and registering it by using the `resolver` attribute of `@ActiveProfiles`.
 
+NOTE: The `spring.profiles.active` system property is not taken into account by the
+Test Context Framework when determining active profiles for a test class. If you need
+to override the profiles configured via `@ActiveProfiles`, you can implement a custom
+`ActiveProfilesResolver` as described in
+xref:testing/testcontext-framework/ctx-management/env-profiles.adoc[Context Configuration with Environment Profiles].
+
 See xref:testing/testcontext-framework/ctx-management/env-profiles.adoc[Context Configuration with Environment Profiles],
 xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-nested-test-configuration[`@Nested` test class configuration], and the
 {spring-framework-api}/test/context/ActiveProfiles.html[`@ActiveProfiles`] javadoc for

framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/env-profiles.adoc

@@ -543,3 +543,74 @@ Kotlin::
 ----
 ======
 
+The following example demonstrates how to implement and register a custom
+`SystemPropertyActiveProfilesResolver` that allows the `spring.profiles.active`
+system property to override profiles configured via `@ActiveProfiles`:
+
+[tabs]
+======
+Java::
++
+[source,java,indent=0,subs="verbatim,quotes",role="primary"]
+----
+	// profiles resolved programmatically via a custom resolver that
+	// allows "spring.profiles.active" to override @ActiveProfiles
+	@ActiveProfiles(
+			resolver = SystemPropertyActiveProfilesResolver.class,
+			inheritProfiles = false)
+	class TransferServiceTest extends AbstractIntegrationTest {
+		// test body
+	}
+----
+
+Kotlin::
++
+[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
+----
+	// profiles resolved programmatically via a custom resolver that
+	// allows "spring.profiles.active" to override @ActiveProfiles
+	@ActiveProfiles(
+			resolver = SystemPropertyActiveProfilesResolver::class,
+			inheritProfiles = false)
+	class TransferServiceTest : AbstractIntegrationTest() {
+		// test body
+	}
+----
+======
+
+[tabs]
+======
+Java::
++
+[source,java,indent=0,subs="verbatim,quotes",role="primary"]
+----
+	public class SystemPropertyActiveProfilesResolver implements ActiveProfilesResolver {
+
+		@Override
+		public String[] resolve(Class<?> testClass) {
+			String profiles = System.getProperty("spring.profiles.active");
+			if (profiles != null && !profiles.isBlank()) {
+				return profiles.split(",");
+			}
+			return new DefaultActiveProfilesResolver().resolve(testClass);
+		}
+	}
+----
+
+Kotlin::
++
+[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
+----
+	class SystemPropertyActiveProfilesResolver : ActiveProfilesResolver {
+
+		override fun resolve(testClass: Class<*>): Array<String> {
+			val profiles = System.getProperty("spring.profiles.active")
+			if (!profiles.isNullOrBlank()) {
+				return profiles.split(",").toTypedArray()
+			}
+			return DefaultActiveProfilesResolver().resolve(testClass)
+		}
+	}
+----
+======
+

spring-test/src/main/java/org/springframework/test/context/ActiveProfiles.java

@@ -37,6 +37,14 @@
  * <p>This annotation will be inherited from an enclosing test class by default.
  * See {@link NestedTestConfiguration @NestedTestConfiguration} for details.
  *
+ * <p>Note that the {@code spring.profiles.active} system property is not taken
+ * into account by the Test Context Framework when determining active profiles for
+ * a test class. If you need to override the profiles configured via
+ * {@code @ActiveProfiles}, you can implement a custom {@link ActiveProfilesResolver}
+ * and register it via the {@link #resolver} attribute. See
+ * <em>Context Configuration with Environment Profiles</em> in the reference manual
+ * for further details and examples.
+ *
  * @author Sam Brannen
  * @since 3.1
  * @see SmartContextLoader

spring-test/src/main/java/org/springframework/test/context/support/DefaultActiveProfilesResolver.java

@@ -32,6 +32,13 @@
  * configured declaratively via {@link ActiveProfiles#profiles} or
  * {@link ActiveProfiles#value}.
  *
+ * <p>Note that the {@code spring.profiles.active} system property is not taken
+ * into account by this resolver. If you need to allow the
+ * {@code spring.profiles.active} system property to override profiles configured
+ * via {@link ActiveProfiles}, you can implement a custom
+ * {@link ActiveProfilesResolver} and register it via
+ * {@link ActiveProfiles#resolver}.
+ *
  * @author Sam Brannen
  * @since 4.1
  * @see ActiveProfiles