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

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

@@ -72,6 +72,13 @@ 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: When `@ActiveProfiles` is declared on a test class, the `spring.profiles.active`
+property (whether configured as a JVM system property or environment variable) is not
+taken into account by the Test Context Framework when determining active profiles. If
+you need to allow `spring.profiles.active` 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,75 @@ Kotlin::
 ----
 ======
 
+The following example demonstrates how to implement and register a custom
+`SystemPropertyOverrideActiveProfilesResolver` that allows the `spring.profiles.active`
+property (whether configured as a JVM system property or environment variable) 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 = SystemPropertyOverrideActiveProfilesResolver.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 = SystemPropertyOverrideActiveProfilesResolver::class,
+			inheritProfiles = false)
+	class TransferServiceTest : AbstractIntegrationTest() {
+		// test body
+	}
+----
+======
+
+[tabs]
+======
+Java::
++
+[source,java,indent=0,subs="verbatim,quotes",role="primary"]
+----
+	public class SystemPropertyOverrideActiveProfilesResolver 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 SystemPropertyOverrideActiveProfilesResolver : 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,16 @@
  * <p>This annotation will be inherited from an enclosing test class by default.
  * See {@link NestedTestConfiguration @NestedTestConfiguration} for details.
  *
+ * <p>Note that when {@code @ActiveProfiles} is declared on a test class, the
+ * {@code spring.profiles.active} property (whether configured as a JVM system
+ * property or environment variable) is not taken into account by the Test Context
+ * Framework when determining active profiles. If you need to allow
+ * {@code spring.profiles.active} 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,12 @@
  * configured declaratively via {@link ActiveProfiles#profiles} or
  * {@link ActiveProfiles#value}.
  *
+ * <p>Note that the {@code spring.profiles.active} property (whether configured
+ * as a JVM system property or environment variable) is not taken into account by
+ * this resolver. If you need to allow {@code spring.profiles.active} 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