This is an automated email from the ASF dual-hosted git repository.
gnodet pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven.git
The following commit(s) were added to refs/heads/master by this push:
new 53230b5a1b Lifecycle execution filter (maven.lifecycle.filter) (#13392)
53230b5a1b is described below
commit 53230b5a1bd7292482cfbf496ebca3bfd7a50553
Author: Guillaume Nodet <[email protected]>
AuthorDate: Fri Nov 6 16:02:01 2026 +0100
Lifecycle execution filter (maven.lifecycle.filter) (#13392)
* [MNG-12535,MNG-12536] Add lifecycle execution filter
(maven.lifecycle.filter)
Add a -Dmaven.lifecycle.filter user property that skips mojo executions
matching coordinate or phase predicates at runtime.
Supported predicate forms (comma-separated, OR-ed):
* skip every mojo execution
:A skip by artifactId
G:A skip by groupId:artifactId
P skip by plugin prefix
P:v:g skip by prefix + version + goal
P:v:g@e skip by prefix + version + goal + executionId
phase(name) skip all mojos bound to the named phase
Implementation: MojoExecutionFilter (parser) + CoordinatePredicate /
PhasePredicate (matchers). Applied in MojoExecutor before each mojo
execution; skipped mojos are logged at INFO level.
ITs: mng-12535-lifecycle-filter-phase, mng-12536-lifecycle-filter-coordinate
Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
* fix: use Maven 4 API noun-style accessors and session-free adapter in
filter
- CoordinatePredicate: getPlugin() → plugin(), getGoal() → goal(),
getExecutionId() → executionId().orElse(null)
- PhasePredicate: getLifecyclePhase() →
lifecyclePhase().map(...).orElse(false)
- MojoExecutionFilter.matches(): replace DefaultMojoExecution(null, ...)
(NPE)
with a lightweight session-free adapter that reads directly from the
legacy
MojoExecution — no InternalMavenSession needed
- Update unit tests to stub the correct API methods (plugin(), goal(),
executionId(), lifecyclePhase() returning Optional)
- IT test classes: package-private → public to match suite convention
* Address review: fire MojoSkipped event for filter-skipped mojos, fix
Javadoc
* Address review: fix FilterPredicate Javadoc accuracy and Plugin adapter
getClassLoader
- FilterPredicate class/method Javadoc: replace 'from the lifecycle
build plan'/'excluded from the plan' with 'at execution time'/'skipped
at execution time' — filtering happens in MojoExecutor.execute(), not
during build plan construction
- MojoExecutionFilter.adapt(): Plugin.getClassLoader() now throws
UnsupportedOperationException instead of returning null, honoring
the @Nonnull contract and failing loudly if misused outside the filter
* nit: add inline comment explaining @Nullable on getDescriptor() adapter
override
* fix: guard ExecutionEventLogger.mojoSkipped() offline warning behind
session.isOffline()
MojoExecutor now fires MojoSkipped for filter-skipped mojos (in addition
to offline-skipped mojos). Without this guard, users running
-Dmaven.lifecycle.filter would see a misleading WARN:
'Goal X requires online mode but Maven is currently offline, skipping'
-- even in a fully online build.
Guard the message with event.getSession().isOffline() so it is only
printed for the original offline-skip case. Filter-skipped mojos are
already logged at INFO level by MojoExecutor before the event is fired.
Applied to both ExecutionEventLogger implementations:
- impl/maven-cli (MavenCling)
- compat/maven-embedder (legacy MavenCli)
* Address review: fix @since tags, revert mojoSkipped regression, improve
filter log
- Change @since 4.1.0 → @since 4.2.0 on all 5 new types (Constants,
CoordinatePredicate, FilterPredicate, MojoExecutionFilter, PhasePredicate) —
this PR targets master (4.2.0)
- Revert ExecutionEventLogger.mojoSkipped() guard: remove the erroneous '&&
event.getSession().isOffline()' added to both compat/maven-embedder and
impl/maven-cli — the offline condition is what causes the skip; guarding on it
is redundant and misleads about the semantics
- Change MojoExecutionFilter.matches() return type from boolean to
Optional<FilterPredicate> so callers can log which specific predicate matched
(e.g. 'phase(test)' or 'surefire') instead of just the property name
- Update MojoExecutor to use Optional<FilterPredicate>; log matched
predicate; remove unused Properties import; simplify getUserProperties() call
* fix: guard mojoSkipped() warning on session.isOffline() to avoid
misleading message for filter-skipped mojos
Both ExecutionEventLogger.mojoSkipped() implementations previously logged
"requires online mode for execution but Maven is currently offline,
skipping"
unconditionally. Since MojoSkipped is now also fired for filter-skip paths
(not just offline paths), this produces a misleading warning for every
filtered mojo even when the build is online.
Add && event.getSession().isOffline() so the offline warning only fires
when the skip was actually caused by being offline. Filter-skipped mojos
already emit an INFO message in MojoExecutor with the matched predicate.
* fix: revert isOffline() guard from mojoSkipped() and remove filter-path
MojoSkipped event
The isOffline() guard was added to prevent the offline warning from firing
for filter-skipped mojos, but gnodet notes the guard leaks an incorrect
mental model: mojoSkipped() is only called from the offline path, so the
offline condition is always true when the warning fires.
The correct fix is to not fire ExecutionEvent.Type.MojoSkipped from the
filter skip path at all. The INFO log in MojoExecutor already provides
user-visible feedback on filter-triggered skips. This keeps the original
mojoSkipped() handler semantics intact (offline warning fires iff
session is offline).
---------
Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>
---
.../main/java/org/apache/maven/api/Constants.java | 10 +
.../maven/lifecycle/internal/MojoExecutor.java | 30 ++-
.../internal/filter/CoordinatePredicate.java | 249 +++++++++++++++++++++
.../lifecycle/internal/filter/FilterPredicate.java | 41 ++++
.../internal/filter/MojoExecutionFilter.java | 218 ++++++++++++++++++
.../lifecycle/internal/filter/PhasePredicate.java | 49 ++++
.../internal/filter/CoordinatePredicateTest.java | 188 ++++++++++++++++
.../internal/filter/MojoExecutionFilterTest.java | 143 ++++++++++++
.../internal/filter/PhasePredicateTest.java | 68 ++++++
.../MavenITmng12535LifecycleFilterPhaseTest.java | 62 +++++
...venITmng12536LifecycleFilterCoordinateTest.java | 62 +++++
.../mng-12535-lifecycle-filter-phase/pom.xml | 25 +++
.../org/apache/maven/its/mng12535/SampleTest.java | 30 +++
.../mng-12536-lifecycle-filter-coordinate/pom.xml | 17 ++
.../org/apache/maven/its/mng12536/SampleTest.java | 30 +++
15 files changed, 1220 insertions(+), 2 deletions(-)
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/Constants.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/Constants.java
index 08ffef90e0..f7d82ba4ec 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/Constants.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/Constants.java
@@ -888,6 +888,16 @@ public final class Constants {
@Config(type = "java.lang.Boolean", defaultValue = "false", source =
Config.Source.SYSTEM_PROPERTIES)
public static final String MAVEN_TEMPFILE_KEEP = "maven.tempfile.keep";
+ /**
+ * Comma-separated list of mojo execution filter predicates. Matching
executions are skipped at runtime.
+ * Supported forms: {@code *}, {@code :A}, {@code G:A}, {@code
G:A:v:g[@e]}, {@code P}, {@code P:v:g},
+ * {@code P:v:g@e}, {@code phase(name)}.
+ *
+ * @since 4.2.0
+ */
+ @Config
+ public static final String MAVEN_LIFECYCLE_FILTER =
"maven.lifecycle.filter";
+
/**
* System property to disable the {@code site} lifecycle.
* When set to {@code true} via {@code
-Dmaven.site.lifecycle.disabled=true}, the {@code site}
diff --git
a/impl/maven-core/src/main/java/org/apache/maven/lifecycle/internal/MojoExecutor.java
b/impl/maven-core/src/main/java/org/apache/maven/lifecycle/internal/MojoExecutor.java
index 21866d29d2..8576963171 100644
---
a/impl/maven-core/src/main/java/org/apache/maven/lifecycle/internal/MojoExecutor.java
+++
b/impl/maven-core/src/main/java/org/apache/maven/lifecycle/internal/MojoExecutor.java
@@ -29,6 +29,7 @@
import java.util.Collections;
import java.util.List;
import java.util.Map;
+import java.util.Optional;
import java.util.Set;
import java.util.TreeSet;
import java.util.concurrent.ConcurrentHashMap;
@@ -47,6 +48,8 @@
import org.apache.maven.internal.MultilineMessageHelper;
import org.apache.maven.lifecycle.LifecycleExecutionException;
import org.apache.maven.lifecycle.MissingProjectException;
+import org.apache.maven.lifecycle.internal.filter.FilterPredicate;
+import org.apache.maven.lifecycle.internal.filter.MojoExecutionFilter;
import org.apache.maven.plugin.BuildPluginManager;
import org.apache.maven.plugin.MavenPluginManager;
import org.apache.maven.plugin.MojoExecution;
@@ -164,20 +167,43 @@ public void execute(final MavenSession session, final
List<MojoExecution> mojoEx
final PhaseRecorder phaseRecorder = new
PhaseRecorder(session.getCurrentProject());
+ // Resolve the mojo execution filter once per project execution.
+ final List<FilterPredicate> filterPredicates =
resolveFilterPredicates(session);
+
mojosExecutionStrategy.get().execute(mojoExecutions, session, new
MojoExecutionRunner() {
@Override
public void run(MojoExecution mojoExecution) throws
LifecycleExecutionException {
- MojoExecutor.this.execute(session, mojoExecution,
dependencyContext, phaseRecorder);
+ MojoExecutor.this.execute(session, mojoExecution,
dependencyContext, phaseRecorder, filterPredicates);
}
});
}
+ /**
+ * Resolves the mojo execution filter predicates for this build.
+ * Uses {@code -Dmaven.lifecycle.filter} user property; returns an empty
list if absent.
+ */
+ private List<FilterPredicate> resolveFilterPredicates(MavenSession
session) throws LifecycleExecutionException {
+ String filterExpression =
session.getUserProperties().getProperty(MojoExecutionFilter.PROPERTY_NAME);
+ try {
+ return MojoExecutionFilter.parse(filterExpression);
+ } catch (IllegalArgumentException e) {
+ throw new LifecycleExecutionException(
+ "Invalid value for '" + MojoExecutionFilter.PROPERTY_NAME
+ "': " + e.getMessage(), e);
+ }
+ }
+
private void execute(
MavenSession session,
MojoExecution mojoExecution,
DependencyContext dependencyContext,
- PhaseRecorder phaseRecorder)
+ PhaseRecorder phaseRecorder,
+ List<FilterPredicate> filterPredicates)
throws LifecycleExecutionException {
+ Optional<FilterPredicate> matchedFilter =
MojoExecutionFilter.matches(mojoExecution, filterPredicates);
+ if (matchedFilter.isPresent()) {
+ LOGGER.info("Skipping {} (matched filter: {})", mojoExecution,
matchedFilter.get());
+ return;
+ }
execute(session, mojoExecution, dependencyContext);
phaseRecorder.observeExecution(mojoExecution);
}
diff --git
a/impl/maven-core/src/main/java/org/apache/maven/lifecycle/internal/filter/CoordinatePredicate.java
b/impl/maven-core/src/main/java/org/apache/maven/lifecycle/internal/filter/CoordinatePredicate.java
new file mode 100644
index 0000000000..0bdc23ed4f
--- /dev/null
+++
b/impl/maven-core/src/main/java/org/apache/maven/lifecycle/internal/filter/CoordinatePredicate.java
@@ -0,0 +1,249 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.lifecycle.internal.filter;
+
+import org.apache.maven.api.MojoExecution;
+import org.apache.maven.api.plugin.descriptor.PluginDescriptor;
+
+/**
+ * A {@link FilterPredicate} that matches {@link MojoExecution}s by plugin
coordinate or prefix.
+ *
+ * <h2>Syntax: {@code ([G[:A]]|P)[:v][:g[@e]]}</h2>
+ *
+ * <p>The {@code @} separator for execution ID is compatible with Maven's
existing
+ * {@code plugin:version:goal@executionId} notation used in
+ * {@code DefaultLifecycleExecutionPlanCalculator} for goal tasks.
+ *
+ * <p>Matching uses {@link MojoExecution#descriptor()} for goal-level fields
and
+ * {@link MojoExecution#plugin()} for plugin-level coordinates (groupId,
artifactId, version,
+ * goal prefix).
+ *
+ * <p>Forms:
+ * <ul>
+ * <li>{@code *} — matches every mojo execution</li>
+ * <li>{@code :A} — any groupId, specific artifactId (e.g. {@code
:maven-enforcer-plugin})</li>
+ * <li>{@code G:A} — exact groupId:artifactId (e.g. {@code
org.apache.maven.plugins:maven-enforcer-plugin}).
+ * The groupId <strong>must contain at least one {@code '.'}</strong>
for this form to be recognised;
+ * groupIds without a dot (e.g. {@code commons-io}) are routed to
prefix-based matching instead.
+ * Use the {@code :A} form to match by artifactId only when the groupId
has no dot.</li>
+ * <li>{@code P} — plugin prefix (e.g. {@code enforcer}), resolved against
the plugin descriptor's
+ * goal prefix.
+ * The prefix <strong>must not contain a {@code '.'}</strong>; prefixes
with a dot
+ * (e.g. {@code io.smallrye}) are routed to groupId:artifactId matching
instead.</li>
+ * <li>{@code P:v:g} — prefix + version + goal</li>
+ * <li>{@code P:v:g@e} — prefix + version + goal + executionId</li>
+ * </ul>
+ *
+ * <p>When any field is {@code null} or not specified, it is treated as a
wildcard (matches any value).
+ *
+ * @since 4.2.0
+ */
+public class CoordinatePredicate implements FilterPredicate {
+
+ /** Wildcard token — matches any value. */
+ private static final String ANY = null;
+
+ private final boolean matchAll;
+ private final String groupId; // null = any, non-null = exact match
+ private final String artifactId; // null = any, non-null = exact match
+ private final String prefix; // null = not used, non-null = match by goal
prefix
+ private final String version; // null = any
+ private final String goal; // null = any
+ private final String executionId; // null = any
+
+ /** Wildcard predicate — matches everything. */
+ public static final CoordinatePredicate MATCH_ALL = new
CoordinatePredicate();
+
+ private CoordinatePredicate() {
+ this.matchAll = true;
+ this.groupId = ANY;
+ this.artifactId = ANY;
+ this.prefix = ANY;
+ this.version = ANY;
+ this.goal = ANY;
+ this.executionId = ANY;
+ }
+
+ private CoordinatePredicate(
+ String groupId, String artifactId, String prefix, String version,
String goal, String executionId) {
+ this.matchAll = false;
+ this.groupId = groupId;
+ this.artifactId = artifactId;
+ this.prefix = prefix;
+ this.version = version;
+ this.goal = goal;
+ this.executionId = executionId;
+ }
+
+ /**
+ * Parses a coordinate predicate from a string token.
+ *
+ * <p>Supported forms:
+ * <ul>
+ * <li>{@code *} — match all</li>
+ * <li>{@code :A} — by artifactId only</li>
+ * <li>{@code G:A} — by groupId:artifactId. The groupId must contain at
least one {@code '.'} to be
+ * recognised as a G:A form; groupIds without a dot are treated as a
plugin prefix instead.</li>
+ * <li>{@code P} — by prefix</li>
+ * <li>{@code P:v:g} — by prefix + version + goal</li>
+ * <li>{@code P:v:g@e} — by prefix + version + goal + executionId</li>
+ * </ul>
+ *
+ * @param token the filter expression token (not {@code null}, not blank)
+ * @return the parsed predicate
+ */
+ public static CoordinatePredicate parse(String token) {
+ if ("*".equals(token)) {
+ return MATCH_ALL;
+ }
+
+ if (token.startsWith(":")) {
+ // :A form — any groupId, specific artifactId, optional :v:g[@e]
+ // e.g. ":maven-enforcer-plugin" or
":maven-enforcer-plugin:3.0.0:enforce@enforce-id"
+ String rest = token.substring(1); // remove leading ':'
+ String[] parts = rest.split(":", 3);
+ String artifactId = emptyToNull(parts[0]);
+ String version = parts.length > 1 ? emptyToNull(parts[1]) : null;
+ String goalAndExec = parts.length > 2 ? parts[2] : null;
+ String[] ge = splitGoalExecution(goalAndExec);
+ return new CoordinatePredicate(ANY, artifactId, ANY, version,
ge[0], ge[1]);
+ }
+
+ // Try to detect G:A form: the token contains ':' AND the part before
the first ':' looks like a
+ // groupId (contains a '.' suggesting it's a Java package name like
org.apache.maven).
+ // This distinguishes "org.apache.maven.plugins:maven-enforcer-plugin"
from "enforcer:3.1.0:enforce".
+ // Limitation: groupIds that do not contain a '.' (e.g.
"commons-io:commons-io") are misrouted
+ // to prefix-based matching. For such groupIds use the explicit ":A"
form for artifactId-only
+ // matching, or the full "G:A" form only when the groupId contains at
least one '.'.
+ int firstColon = token.indexOf(':');
+ if (firstColon > 0 && token.substring(0, firstColon).contains(".")) {
+ // G:A[:v[:g[@e]]] form
+ String[] parts = token.split(":", 4);
+ String groupId = emptyToNull(parts[0]);
+ String artifactId = parts.length > 1 ? emptyToNull(parts[1]) :
null;
+ String version = parts.length > 2 ? emptyToNull(parts[2]) : null;
+ String goalAndExec = parts.length > 3 ? parts[3] : null;
+ String[] ge = splitGoalExecution(goalAndExec);
+ return new CoordinatePredicate(groupId, artifactId, ANY, version,
ge[0], ge[1]);
+ }
+
+ // P[:v[:g[@e]]] form — prefix-based
+ String[] parts = token.split(":", 3);
+ String prefix = emptyToNull(parts[0]);
+ String version = parts.length > 1 ? emptyToNull(parts[1]) : null;
+ String goalAndExec = parts.length > 2 ? parts[2] : null;
+ String[] ge = splitGoalExecution(goalAndExec);
+ return new CoordinatePredicate(ANY, ANY, prefix, version, ge[0],
ge[1]);
+ }
+
+ /**
+ * Splits a {@code "goal"} or {@code "goal@executionId"} string into a
2-element array
+ * {@code [goal, executionId]}. Either element may be {@code null}.
+ */
+ private static String[] splitGoalExecution(String goalAndExec) {
+ if (goalAndExec == null || goalAndExec.isEmpty()) {
+ return new String[] {null, null};
+ }
+ int atIdx = goalAndExec.indexOf('@');
+ if (atIdx < 0) {
+ return new String[] {emptyToNull(goalAndExec), null};
+ }
+ return new String[] {emptyToNull(goalAndExec.substring(0, atIdx)),
emptyToNull(goalAndExec.substring(atIdx + 1))
+ };
+ }
+
+ private static String emptyToNull(String s) {
+ return (s == null || s.isEmpty()) ? null : s;
+ }
+
+ @Override
+ public boolean matches(MojoExecution execution) {
+ if (matchAll) {
+ return true;
+ }
+
+ PluginDescriptor descriptor = execution.plugin().getDescriptor();
+
+ // prefix-based matching
+ if (prefix != null) {
+ String execPrefix = descriptor != null ?
descriptor.getGoalPrefix() : null;
+ if (!prefix.equals(execPrefix)) {
+ return false;
+ }
+ } else {
+ // coordinate-based matching
+ if (groupId != null) {
+ String execGroupId = descriptor != null ?
descriptor.getGroupId() : null;
+ if (!groupId.equals(execGroupId)) {
+ return false;
+ }
+ }
+ if (artifactId != null) {
+ String execArtifactId = descriptor != null ?
descriptor.getArtifactId() : null;
+ if (!artifactId.equals(execArtifactId)) {
+ return false;
+ }
+ }
+ }
+
+ if (version != null) {
+ String execVersion = descriptor != null ? descriptor.getVersion()
: null;
+ if (!version.equals(execVersion)) {
+ return false;
+ }
+ }
+ if (goal != null && !goal.equals(execution.goal())) {
+ return false;
+ }
+ if (executionId != null &&
!executionId.equals(execution.executionId().orElse(null))) {
+ return false;
+ }
+
+ return true;
+ }
+
+ @Override
+ public String toString() {
+ if (matchAll) {
+ return "*";
+ }
+ StringBuilder sb = new StringBuilder();
+ if (prefix != null) {
+ sb.append(prefix);
+ } else {
+ if (groupId != null) {
+ sb.append(groupId);
+ }
+ sb.append(':');
+ if (artifactId != null) {
+ sb.append(artifactId);
+ }
+ }
+ if (version != null) {
+ sb.append(':').append(version);
+ }
+ if (goal != null) {
+ sb.append(':').append(goal);
+ if (executionId != null) {
+ sb.append('@').append(executionId);
+ }
+ }
+ return sb.toString();
+ }
+}
diff --git
a/impl/maven-core/src/main/java/org/apache/maven/lifecycle/internal/filter/FilterPredicate.java
b/impl/maven-core/src/main/java/org/apache/maven/lifecycle/internal/filter/FilterPredicate.java
new file mode 100644
index 0000000000..9ef31606cf
--- /dev/null
+++
b/impl/maven-core/src/main/java/org/apache/maven/lifecycle/internal/filter/FilterPredicate.java
@@ -0,0 +1,41 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.lifecycle.internal.filter;
+
+import org.apache.maven.api.MojoExecution;
+
+/**
+ * Predicate for filtering {@link MojoExecution} entries at execution time.
+ *
+ * <p>Used by {@code -Dmaven.lifecycle.filter} to skip matching executions at
runtime.
+ * New predicate types can be added without breaking existing filter
expressions.
+ *
+ * @see MojoExecutionFilter
+ * @since 4.2.0
+ */
+public interface FilterPredicate {
+
+ /**
+ * Returns {@code true} if the given mojo execution should be
<em>skipped</em> at execution time.
+ *
+ * @param execution the mojo execution to test
+ * @return {@code true} to skip this execution, {@code false} to execute
it normally
+ */
+ boolean matches(MojoExecution execution);
+}
diff --git
a/impl/maven-core/src/main/java/org/apache/maven/lifecycle/internal/filter/MojoExecutionFilter.java
b/impl/maven-core/src/main/java/org/apache/maven/lifecycle/internal/filter/MojoExecutionFilter.java
new file mode 100644
index 0000000000..f9d48cc008
--- /dev/null
+++
b/impl/maven-core/src/main/java/org/apache/maven/lifecycle/internal/filter/MojoExecutionFilter.java
@@ -0,0 +1,218 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.lifecycle.internal.filter;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Optional;
+
+import org.apache.maven.api.Artifact;
+import org.apache.maven.api.Constants;
+import org.apache.maven.api.Dependency;
+import org.apache.maven.api.MojoExecution;
+import org.apache.maven.api.Plugin;
+import org.apache.maven.api.annotations.Nullable;
+import org.apache.maven.api.model.PluginExecution;
+import org.apache.maven.api.plugin.descriptor.PluginDescriptor;
+import org.apache.maven.api.plugin.descriptor.lifecycle.Lifecycle;
+import org.apache.maven.api.xml.XmlNode;
+
+/**
+ * Parses the {@code maven.lifecycle.filter} user property value into a list
of {@link FilterPredicate}s,
+ * and applies them at mojo execution time in {@code MojoExecutor}.
+ *
+ * <p>The property value is a comma-separated list of predicates, OR-ed
together:
+ * a mojo execution matching <em>any</em> predicate is skipped.
+ *
+ * <p>Supported predicate forms:
+ * <ul>
+ * <li>{@code *} — skip all mojo executions</li>
+ * <li>{@code :A} — skip by artifactId (e.g. {@code
:maven-enforcer-plugin})</li>
+ * <li>{@code G:A} — skip by groupId:artifactId</li>
+ * <li>{@code P} — skip by plugin prefix (e.g. {@code enforcer})</li>
+ * <li>{@code P:v:g} — skip by prefix:version:goal</li>
+ * <li>{@code P:v:g@e} — skip by prefix:version:goal@executionId</li>
+ * <li>{@code phase(name)} — skip all mojos bound to the named phase</li>
+ * </ul>
+ *
+ * @since 4.2.0
+ */
+public class MojoExecutionFilter {
+
+ /** The name of the user property that activates the filter. */
+ public static final String PROPERTY_NAME =
Constants.MAVEN_LIFECYCLE_FILTER;
+
+ private MojoExecutionFilter() {
+ // utility class
+ }
+
+ /**
+ * Parses a filter expression string into a list of {@link
FilterPredicate}s.
+ *
+ * @param expression the comma-separated filter expression (may be {@code
null} or blank)
+ * @return list of parsed predicates; empty if the expression is absent or
blank
+ */
+ public static List<FilterPredicate> parse(String expression) {
+ if (expression == null || expression.isBlank()) {
+ return List.of();
+ }
+ List<FilterPredicate> predicates = new ArrayList<>();
+ for (String token : expression.split(",")) {
+ token = token.strip();
+ if (token.isEmpty()) {
+ continue;
+ }
+ predicates.add(parseToken(token));
+ }
+ return List.copyOf(predicates);
+ }
+
+ private static FilterPredicate parseToken(String token) {
+ if (token.startsWith("phase(")) {
+ if (!token.endsWith(")")) {
+ throw new IllegalArgumentException("Invalid phase() predicate
'" + token + "': missing closing ')'");
+ }
+ String phaseName = token.substring("phase(".length(),
token.length() - 1);
+ if (phaseName.isBlank()) {
+ throw new IllegalArgumentException("phase() predicate requires
a non-blank phase name");
+ }
+ if (phaseName.contains(")")) {
+ throw new IllegalArgumentException(
+ "Invalid phase() predicate '" + token + "': phase name
must not contain ')'");
+ }
+ return new PhasePredicate(phaseName);
+ }
+ return CoordinatePredicate.parse(token);
+ }
+
+ /**
+ * Returns the first matching predicate if the given legacy mojo execution
matches any predicate in the list
+ * and should be skipped, or an empty Optional if the execution should
proceed.
+ *
+ * <p>Adapts the legacy {@link org.apache.maven.plugin.MojoExecution} into
a lightweight
+ * {@link MojoExecution} view — only the fields accessed by the predicates
+ * ({@code plugin()}, {@code goal()}, {@code executionId()}, {@code
lifecyclePhase()})
+ * are populated. No session is required.
+ *
+ * @param execution the legacy mojo execution to test
+ * @param predicates the predicates to apply (OR-ed)
+ * @return the first matching predicate, or empty if no match
+ */
+ public static Optional<FilterPredicate> matches(
+ org.apache.maven.plugin.MojoExecution execution,
List<FilterPredicate> predicates) {
+ if (predicates.isEmpty()) {
+ return Optional.empty();
+ }
+ MojoExecution apiExecution = adapt(execution);
+ for (FilterPredicate predicate : predicates) {
+ if (predicate.matches(apiExecution)) {
+ return Optional.of(predicate);
+ }
+ }
+ return Optional.empty();
+ }
+
+ /**
+ * Adapts a legacy {@link org.apache.maven.plugin.MojoExecution} to the API
+ * {@link MojoExecution} interface using only the fields needed by the
predicates.
+ * No session is required.
+ */
+ private static MojoExecution adapt(org.apache.maven.plugin.MojoExecution
legacy) {
+ org.apache.maven.plugin.descriptor.MojoDescriptor legacyMojo =
legacy.getMojoDescriptor();
+ org.apache.maven.plugin.descriptor.PluginDescriptor legacyPlugin =
+ legacyMojo != null ? legacyMojo.getPluginDescriptor() : null;
+ PluginDescriptor descriptorV4 = legacyPlugin != null ?
legacyPlugin.getPluginDescriptorV4() : null;
+
+ Plugin plugin = new Plugin() {
+ @Override
+ public org.apache.maven.api.model.Plugin getModel() {
+ return null;
+ }
+
+ @Override
+ @Nullable // adapter may lack a descriptor; all predicates
null-guard this
+ public PluginDescriptor getDescriptor() {
+ return descriptorV4;
+ }
+
+ @Override
+ public List<Lifecycle> getLifecycles() {
+ return Collections.emptyList();
+ }
+
+ @Override
+ public ClassLoader getClassLoader() {
+ throw new UnsupportedOperationException("getClassLoader() is
not available in the filter adapter");
+ }
+
+ @Override
+ public Artifact getArtifact() {
+ return null;
+ }
+
+ @Override
+ public java.util.Map<String, Dependency> getDependenciesMap() {
+ return Collections.emptyMap();
+ }
+ };
+
+ String goal = legacy.getGoal();
+ Optional<String> executionId =
Optional.ofNullable(legacy.getExecutionId());
+ Optional<String> lifecyclePhase =
Optional.ofNullable(legacy.getLifecyclePhase());
+
+ return new MojoExecution() {
+ @Override
+ public Plugin plugin() {
+ return plugin;
+ }
+
+ @Override
+ public Optional<PluginExecution> model() {
+ return Optional.empty();
+ }
+
+ @Override
+ @Nullable
+ public org.apache.maven.api.plugin.descriptor.MojoDescriptor
descriptor() {
+ return legacyMojo != null ? legacyMojo.getMojoDescriptorV4() :
null;
+ }
+
+ @Override
+ public Optional<String> executionId() {
+ return executionId;
+ }
+
+ @Override
+ public String goal() {
+ return goal;
+ }
+
+ @Override
+ public Optional<String> lifecyclePhase() {
+ return lifecyclePhase;
+ }
+
+ @Override
+ public Optional<XmlNode> configuration() {
+ return Optional.empty();
+ }
+ };
+ }
+}
diff --git
a/impl/maven-core/src/main/java/org/apache/maven/lifecycle/internal/filter/PhasePredicate.java
b/impl/maven-core/src/main/java/org/apache/maven/lifecycle/internal/filter/PhasePredicate.java
new file mode 100644
index 0000000000..73858cc0db
--- /dev/null
+++
b/impl/maven-core/src/main/java/org/apache/maven/lifecycle/internal/filter/PhasePredicate.java
@@ -0,0 +1,49 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.lifecycle.internal.filter;
+
+import org.apache.maven.api.MojoExecution;
+
+/**
+ * A {@link FilterPredicate} that matches all {@link MojoExecution}s bound to
a specific lifecycle phase.
+ *
+ * <p>Syntax in {@code -Dmaven.lifecycle.filter}: {@code phase(<phaseName>)}
+ *
+ * <p>Example: {@code -Dmaven.lifecycle.filter=phase(test)} removes all mojos
bound to the {@code test} phase.
+ *
+ * @since 4.2.0
+ */
+public class PhasePredicate implements FilterPredicate {
+
+ private final String phaseName;
+
+ public PhasePredicate(String phaseName) {
+ this.phaseName = phaseName;
+ }
+
+ @Override
+ public boolean matches(MojoExecution execution) {
+ return execution.lifecyclePhase().map(phaseName::equals).orElse(false);
+ }
+
+ @Override
+ public String toString() {
+ return "phase(" + phaseName + ")";
+ }
+}
diff --git
a/impl/maven-core/src/test/java/org/apache/maven/lifecycle/internal/filter/CoordinatePredicateTest.java
b/impl/maven-core/src/test/java/org/apache/maven/lifecycle/internal/filter/CoordinatePredicateTest.java
new file mode 100644
index 0000000000..928e12e4f4
--- /dev/null
+++
b/impl/maven-core/src/test/java/org/apache/maven/lifecycle/internal/filter/CoordinatePredicateTest.java
@@ -0,0 +1,188 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.lifecycle.internal.filter;
+
+import java.util.Optional;
+
+import org.apache.maven.api.MojoExecution;
+import org.apache.maven.api.Plugin;
+import org.apache.maven.api.plugin.descriptor.PluginDescriptor;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * Unit tests for {@link CoordinatePredicate}.
+ */
+class CoordinatePredicateTest {
+
+ private static MojoExecution execution(
+ String groupId, String artifactId, String version, String
goalPrefix, String goal, String executionId) {
+ PluginDescriptor descriptor = mock(PluginDescriptor.class);
+ when(descriptor.getGroupId()).thenReturn(groupId);
+ when(descriptor.getArtifactId()).thenReturn(artifactId);
+ when(descriptor.getVersion()).thenReturn(version);
+ when(descriptor.getGoalPrefix()).thenReturn(goalPrefix);
+
+ Plugin plugin = mock(Plugin.class);
+ when(plugin.getDescriptor()).thenReturn(descriptor);
+
+ MojoExecution exec = mock(MojoExecution.class);
+ when(exec.plugin()).thenReturn(plugin);
+ when(exec.goal()).thenReturn(goal);
+ when(exec.executionId()).thenReturn(Optional.ofNullable(executionId));
+ return exec;
+ }
+
+ private static MojoExecution surefire() {
+ return execution(
+ "org.apache.maven.plugins", "maven-surefire-plugin", "3.2.5",
"surefire", "test", "default-test");
+ }
+
+ private static MojoExecution enforcer() {
+ return execution(
+ "org.apache.maven.plugins", "maven-enforcer-plugin", "3.4.1",
"enforcer", "enforce", "enforce-rules");
+ }
+
+ @Test
+ void wildcardMatchesAll() {
+ assertTrue(CoordinatePredicate.parse("*").matches(surefire()));
+ assertTrue(CoordinatePredicate.parse("*").matches(enforcer()));
+ }
+
+ @Test
+ void artifactIdOnlyMatchesByArtifactId() {
+ CoordinatePredicate p =
CoordinatePredicate.parse(":maven-surefire-plugin");
+ assertTrue(p.matches(surefire()));
+ assertFalse(p.matches(enforcer()));
+ }
+
+ @Test
+ void colonAloneMatchesAll() {
+ CoordinatePredicate p = CoordinatePredicate.parse(":");
+ assertTrue(p.matches(surefire()));
+ assertTrue(p.matches(enforcer()));
+ }
+
+ @Test
+ void groupAndArtifactMatchesExact() {
+ CoordinatePredicate p =
CoordinatePredicate.parse("org.apache.maven.plugins:maven-surefire-plugin");
+ assertTrue(p.matches(surefire()));
+ assertFalse(p.matches(enforcer()));
+ }
+
+ @Test
+ void groupWithWildcardArtifact() {
+ CoordinatePredicate p =
CoordinatePredicate.parse("org.apache.maven.plugins:");
+ assertTrue(p.matches(surefire()));
+ assertTrue(p.matches(enforcer()));
+ }
+
+ @Test
+ void groupMismatchDoesNotMatch() {
+ CoordinatePredicate p =
CoordinatePredicate.parse("com.example:maven-surefire-plugin");
+ assertFalse(p.matches(surefire()));
+ }
+
+ @Test
+ void prefixMatchesByGoalPrefix() {
+ CoordinatePredicate p = CoordinatePredicate.parse("surefire");
+ assertTrue(p.matches(surefire()));
+ assertFalse(p.matches(enforcer()));
+ }
+
+ @Test
+ void prefixWithGoalMatchesGoal() {
+ CoordinatePredicate p = CoordinatePredicate.parse("surefire::test");
+ assertTrue(p.matches(surefire()));
+ assertFalse(p.matches(enforcer()));
+ }
+
+ @Test
+ void prefixWithVersionGoalAndExecution() {
+ CoordinatePredicate p =
CoordinatePredicate.parse("surefire:3.2.5:test@default-test");
+ assertTrue(p.matches(surefire()));
+ }
+
+ @Test
+ void prefixVersionMismatch() {
+ CoordinatePredicate p =
CoordinatePredicate.parse("surefire:99.0:test@default-test");
+ assertFalse(p.matches(surefire()));
+ }
+
+ @Test
+ void prefixExecutionIdMismatch() {
+ CoordinatePredicate p =
CoordinatePredicate.parse("surefire::test@other-id");
+ assertFalse(p.matches(surefire()));
+ }
+
+ @Test
+ void fullCoordinateWithGoalAndExecution() {
+ CoordinatePredicate p =
+
CoordinatePredicate.parse("org.apache.maven.plugins:maven-surefire-plugin:3.2.5:test@default-test");
+ assertTrue(p.matches(surefire()));
+ }
+
+ @Test
+ void coordinateGoalMismatch() {
+ CoordinatePredicate p =
+
CoordinatePredicate.parse("org.apache.maven.plugins:maven-surefire-plugin:3.2.5:other@default-test");
+ assertFalse(p.matches(surefire()));
+ }
+
+ @Test
+ void noDescriptorDoesNotMatchSpecificPlugin() {
+ MojoExecution exec = mock(MojoExecution.class);
+ Plugin plugin = mock(Plugin.class);
+ when(plugin.getDescriptor()).thenReturn(null);
+ when(exec.plugin()).thenReturn(plugin);
+ when(exec.goal()).thenReturn("test");
+ when(exec.executionId()).thenReturn(Optional.of("default-test"));
+
assertFalse(CoordinatePredicate.parse(":maven-surefire-plugin").matches(exec));
+ }
+
+ @Test
+ void wildcardMatchesEvenWithNullDescriptor() {
+ MojoExecution exec = mock(MojoExecution.class);
+ Plugin plugin = mock(Plugin.class);
+ when(plugin.getDescriptor()).thenReturn(null);
+ when(exec.plugin()).thenReturn(plugin);
+ assertTrue(CoordinatePredicate.MATCH_ALL.matches(exec));
+ }
+
+ @Test
+ void dotlessGroupIdIsMisroutedToPrefixMode() {
+ // GroupIds without a '.' (e.g. "commons-io") cannot be used in G:A
form — they are routed
+ // to prefix-based matching. Document this: the token
"commons-io:commons-io" is treated as
+ // prefix="commons-io", version="commons-io" — it will NOT match an
execution with groupId
+ // "commons-io". Users should use ":commons-io" (artifactId-only form)
instead.
+ MojoExecution exec = execution("commons-io", "commons-io", "2.15.1",
"commons-io", "copy", "default");
+ // "commons-io:commons-io" is parsed as P:v form (prefix="commons-io",
version="commons-io").
+ // The prefix check succeeds (goalPrefix="commons-io" matches), but
the version check fails
+ // ("commons-io" != "2.15.1"), so the predicate returns false. This
demonstrates that the
+ // misrouting produces a non-matching predicate, not a silent match.
+ CoordinatePredicate p =
CoordinatePredicate.parse("commons-io:commons-io");
+ assertFalse(p.matches(exec), "dotless groupId in G:A form is misrouted
to prefix mode and should not match");
+ // The correct workaround: use :A form to match by artifactId
+ assertTrue(CoordinatePredicate.parse(":commons-io").matches(exec));
+ }
+}
diff --git
a/impl/maven-core/src/test/java/org/apache/maven/lifecycle/internal/filter/MojoExecutionFilterTest.java
b/impl/maven-core/src/test/java/org/apache/maven/lifecycle/internal/filter/MojoExecutionFilterTest.java
new file mode 100644
index 0000000000..3a3f75e3e6
--- /dev/null
+++
b/impl/maven-core/src/test/java/org/apache/maven/lifecycle/internal/filter/MojoExecutionFilterTest.java
@@ -0,0 +1,143 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.lifecycle.internal.filter;
+
+import java.util.List;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Unit tests for {@link MojoExecutionFilter}.
+ */
+class MojoExecutionFilterTest {
+
+ // ── parse
─────────────────────────────────────────────────────────────────
+
+ @Test
+ void parseNullReturnsEmpty() {
+ assertTrue(MojoExecutionFilter.parse(null).isEmpty());
+ }
+
+ @Test
+ void parseBlankReturnsEmpty() {
+ assertTrue(MojoExecutionFilter.parse(" ").isEmpty());
+ }
+
+ @Test
+ void parseSinglePhase() {
+ List<FilterPredicate> predicates =
MojoExecutionFilter.parse("phase(test)");
+ assertEquals(1, predicates.size());
+ assertInstanceOf(PhasePredicate.class, predicates.get(0));
+ }
+
+ @Test
+ void parseMultiplePredicates() {
+ List<FilterPredicate> predicates =
+ MojoExecutionFilter.parse("phase(test),
phase(integration-test), :maven-enforcer-plugin");
+ assertEquals(3, predicates.size());
+ assertInstanceOf(PhasePredicate.class, predicates.get(0));
+ assertInstanceOf(PhasePredicate.class, predicates.get(1));
+ assertInstanceOf(CoordinatePredicate.class, predicates.get(2));
+ }
+
+ @Test
+ void parseSkipsBlankTokens() {
+ List<FilterPredicate> predicates =
MojoExecutionFilter.parse("phase(test),,phase(compile),");
+ assertEquals(2, predicates.size());
+ }
+
+ @Test
+ void parseWildcard() {
+ List<FilterPredicate> predicates = MojoExecutionFilter.parse("*");
+ assertEquals(1, predicates.size());
+ assertEquals(CoordinatePredicate.MATCH_ALL, predicates.get(0));
+ }
+
+ @Test
+ void parsePrefix() {
+ List<FilterPredicate> predicates =
MojoExecutionFilter.parse("surefire");
+ assertEquals(1, predicates.size());
+ assertInstanceOf(CoordinatePredicate.class, predicates.get(0));
+ }
+
+ @Test
+ void parsePrefixWithVersionAndGoalAndExecution() {
+ List<FilterPredicate> predicates =
MojoExecutionFilter.parse("surefire:3.2.5:test@default-test");
+ assertEquals(1, predicates.size());
+ assertInstanceOf(CoordinatePredicate.class, predicates.get(0));
+ }
+
+ @Test
+ void parseGroupArtifact() {
+ List<FilterPredicate> predicates =
MojoExecutionFilter.parse("org.apache.maven.plugins:maven-surefire-plugin");
+ assertEquals(1, predicates.size());
+ assertInstanceOf(CoordinatePredicate.class, predicates.get(0));
+ }
+
+ @Test
+ void parseResultIsImmutable() {
+ List<FilterPredicate> predicates =
MojoExecutionFilter.parse("phase(test)");
+ org.junit.jupiter.api.Assertions.assertThrows(
+ UnsupportedOperationException.class, () ->
predicates.add(CoordinatePredicate.MATCH_ALL));
+ }
+
+ @Test
+ void emptyPhaseParensThrows() {
+ org.junit.jupiter.api.Assertions.assertThrows(
+ IllegalArgumentException.class, () ->
MojoExecutionFilter.parse("phase()"));
+ }
+
+ @Test
+ void blankPhaseParensThrows() {
+ org.junit.jupiter.api.Assertions.assertThrows(
+ IllegalArgumentException.class, () ->
MojoExecutionFilter.parse("phase( )"));
+ }
+
+ @Test
+ void extraClosingParenThrows() {
+ org.junit.jupiter.api.Assertions.assertThrows(
+ IllegalArgumentException.class, () ->
MojoExecutionFilter.parse("phase(test))"));
+ }
+
+ @Test
+ void missingClosingParenThrows() {
+ // phase(test with no closing ')' must not silently fall through to
CoordinatePredicate
+ org.junit.jupiter.api.Assertions.assertThrows(
+ IllegalArgumentException.class, () ->
MojoExecutionFilter.parse("phase(test"));
+ }
+
+ // ── propertyName
─────────────────────────────────────────────────────────
+
+ @Test
+ void propertyNameMatchesConstant() {
+ assertEquals(org.apache.maven.api.Constants.MAVEN_LIFECYCLE_FILTER,
MojoExecutionFilter.PROPERTY_NAME);
+ }
+
+ // ── helpers
───────────────────────────────────────────────────────────────
+
+ private static void assertInstanceOf(Class<?> expected, Object actual) {
+ assertTrue(
+ expected.isInstance(actual),
+ "Expected instance of " + expected.getSimpleName() + " but got
"
+ + actual.getClass().getSimpleName());
+ }
+}
diff --git
a/impl/maven-core/src/test/java/org/apache/maven/lifecycle/internal/filter/PhasePredicateTest.java
b/impl/maven-core/src/test/java/org/apache/maven/lifecycle/internal/filter/PhasePredicateTest.java
new file mode 100644
index 0000000000..a3db019ad4
--- /dev/null
+++
b/impl/maven-core/src/test/java/org/apache/maven/lifecycle/internal/filter/PhasePredicateTest.java
@@ -0,0 +1,68 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.lifecycle.internal.filter;
+
+import java.util.Optional;
+
+import org.apache.maven.api.MojoExecution;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * Unit tests for {@link PhasePredicate}.
+ */
+class PhasePredicateTest {
+
+ @Test
+ void matchesExecutionBoundToThatPhase() {
+ MojoExecution exec = mock(MojoExecution.class);
+ when(exec.lifecyclePhase()).thenReturn(Optional.of("test"));
+ assertTrue(new PhasePredicate("test").matches(exec));
+ }
+
+ @Test
+ void doesNotMatchDifferentPhase() {
+ MojoExecution exec = mock(MojoExecution.class);
+ when(exec.lifecyclePhase()).thenReturn(Optional.of("compile"));
+ assertFalse(new PhasePredicate("test").matches(exec));
+ }
+
+ @Test
+ void doesNotMatchNullPhase() {
+ MojoExecution exec = mock(MojoExecution.class);
+ when(exec.lifecyclePhase()).thenReturn(Optional.empty());
+ assertFalse(new PhasePredicate("test").matches(exec));
+ }
+
+ @Test
+ void matchesIntegrationTestPhase() {
+ MojoExecution exec = mock(MojoExecution.class);
+
when(exec.lifecyclePhase()).thenReturn(Optional.of("integration-test"));
+ assertTrue(new PhasePredicate("integration-test").matches(exec));
+ }
+
+ @Test
+ void toStringReturnsPhaseExpression() {
+ org.junit.jupiter.api.Assertions.assertEquals("phase(test)", new
PhasePredicate("test").toString());
+ }
+}
diff --git
a/its/core-it-suite/src/test/java/org/apache/maven/it/MavenITmng12535LifecycleFilterPhaseTest.java
b/its/core-it-suite/src/test/java/org/apache/maven/it/MavenITmng12535LifecycleFilterPhaseTest.java
new file mode 100644
index 0000000000..9c00080cda
--- /dev/null
+++
b/its/core-it-suite/src/test/java/org/apache/maven/it/MavenITmng12535LifecycleFilterPhaseTest.java
@@ -0,0 +1,62 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.it;
+
+import java.nio.file.Path;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * Verifies that {@code -Dmaven.lifecycle.filter=phase(test)} skips the {@code
test} phase,
+ * while running the same lifecycle without the filter executes tests normally.
+ *
+ * @see <a href="https://github.com/apache/maven/issues/12535">MNG-12535</a>
+ */
+public class MavenITmng12535LifecycleFilterPhaseTest extends
AbstractMavenIntegrationTestCase {
+
+ @Test
+ void lifecycleFilterSkipsTestPhase() throws Exception {
+ Path testDir = extractResources("/mng-12535-lifecycle-filter-phase");
+
+ Verifier verifier = newVerifier(testDir);
+ verifier.setAutoclean(false);
+ verifier.deleteDirectory("target");
+ verifier.addCliArgument("-Dmaven.lifecycle.filter=phase(test)");
+ verifier.addCliArgument("test");
+ verifier.execute();
+ verifier.verifyErrorFreeLog();
+
+ // Surefire ran → would produce "Tests run:" in log; with filter it
must NOT appear
+ verifier.verifyTextNotInLog("Tests run:");
+ }
+
+ @Test
+ void withoutFilterSurefireRunsNormally() throws Exception {
+ Path testDir = extractResources("/mng-12535-lifecycle-filter-phase");
+
+ Verifier verifier = newVerifier(testDir);
+ verifier.setAutoclean(false);
+ verifier.deleteDirectory("target");
+ verifier.addCliArgument("test");
+ verifier.execute();
+ verifier.verifyErrorFreeLog();
+
+ verifier.verifyTextInLog("Tests run:");
+ }
+}
diff --git
a/its/core-it-suite/src/test/java/org/apache/maven/it/MavenITmng12536LifecycleFilterCoordinateTest.java
b/its/core-it-suite/src/test/java/org/apache/maven/it/MavenITmng12536LifecycleFilterCoordinateTest.java
new file mode 100644
index 0000000000..312c63a378
--- /dev/null
+++
b/its/core-it-suite/src/test/java/org/apache/maven/it/MavenITmng12536LifecycleFilterCoordinateTest.java
@@ -0,0 +1,62 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.it;
+
+import java.nio.file.Path;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * Verifies that {@code maven.lifecycle.filter} can target plugins by
artifactId ({@code :A})
+ * and by goal prefix.
+ *
+ * @see <a href="https://github.com/apache/maven/issues/12536">MNG-12536</a>
+ */
+public class MavenITmng12536LifecycleFilterCoordinateTest extends
AbstractMavenIntegrationTestCase {
+
+ @Test
+ void filterByArtifactIdSkipsSurefire() throws Exception {
+ Path testDir =
extractResources("/mng-12536-lifecycle-filter-coordinate");
+
+ Verifier verifier = newVerifier(testDir);
+ verifier.setAutoclean(false);
+ verifier.deleteDirectory("target");
+
verifier.addCliArgument("-Dmaven.lifecycle.filter=:maven-surefire-plugin");
+ verifier.addCliArgument("test");
+ verifier.execute();
+ verifier.verifyErrorFreeLog();
+
+ verifier.verifyTextNotInLog("Tests run:");
+ }
+
+ @Test
+ void filterByPrefixSkipsSurefire() throws Exception {
+ Path testDir =
extractResources("/mng-12536-lifecycle-filter-coordinate");
+
+ Verifier verifier = newVerifier(testDir);
+ verifier.setAutoclean(false);
+ verifier.deleteDirectory("target");
+ verifier.addCliArgument("-Dmaven.lifecycle.filter=surefire");
+ verifier.addCliArgument("test");
+ verifier.execute();
+ verifier.verifyErrorFreeLog();
+
+ verifier.verifyTextNotInLog("Tests run:");
+ }
+}
diff --git
a/its/core-it-suite/src/test/resources/mng-12535-lifecycle-filter-phase/pom.xml
b/its/core-it-suite/src/test/resources/mng-12535-lifecycle-filter-phase/pom.xml
new file mode 100644
index 0000000000..7c631c3c83
--- /dev/null
+++
b/its/core-it-suite/src/test/resources/mng-12535-lifecycle-filter-phase/pom.xml
@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.apache.maven.its.mng12535</groupId>
+ <artifactId>mng-12535-lifecycle-filter-phase</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>jar</packaging>
+ <description>Verifies that maven.lifecycle.filter=phase(test) skips the test
phase.</description>
+ <dependencies>
+ <dependency>
+ <groupId>org.junit.jupiter</groupId>
+ <artifactId>junit-jupiter-api</artifactId>
+ <version>5.11.0</version>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ </plugin>
+ </plugins>
+ </build>
+</project>
diff --git
a/its/core-it-suite/src/test/resources/mng-12535-lifecycle-filter-phase/src/test/java/org/apache/maven/its/mng12535/SampleTest.java
b/its/core-it-suite/src/test/resources/mng-12535-lifecycle-filter-phase/src/test/java/org/apache/maven/its/mng12535/SampleTest.java
new file mode 100644
index 0000000000..c3e864312a
--- /dev/null
+++
b/its/core-it-suite/src/test/resources/mng-12535-lifecycle-filter-phase/src/test/java/org/apache/maven/its/mng12535/SampleTest.java
@@ -0,0 +1,30 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.its.mng12535;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class SampleTest {
+ @Test
+ void alwaysPasses() {
+ assertTrue(true);
+ }
+}
diff --git
a/its/core-it-suite/src/test/resources/mng-12536-lifecycle-filter-coordinate/pom.xml
b/its/core-it-suite/src/test/resources/mng-12536-lifecycle-filter-coordinate/pom.xml
new file mode 100644
index 0000000000..ccf52930bd
--- /dev/null
+++
b/its/core-it-suite/src/test/resources/mng-12536-lifecycle-filter-coordinate/pom.xml
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.apache.maven.its.mng12536</groupId>
+ <artifactId>mng-12536-lifecycle-filter-coordinate</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>jar</packaging>
+ <description>Verifies that maven.lifecycle.filter=:maven-surefire-plugin
skips surefire by artifactId.</description>
+ <dependencies>
+ <dependency>
+ <groupId>org.junit.jupiter</groupId>
+ <artifactId>junit-jupiter-api</artifactId>
+ <version>5.11.0</version>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+</project>
diff --git
a/its/core-it-suite/src/test/resources/mng-12536-lifecycle-filter-coordinate/src/test/java/org/apache/maven/its/mng12536/SampleTest.java
b/its/core-it-suite/src/test/resources/mng-12536-lifecycle-filter-coordinate/src/test/java/org/apache/maven/its/mng12536/SampleTest.java
new file mode 100644
index 0000000000..a891857017
--- /dev/null
+++
b/its/core-it-suite/src/test/resources/mng-12536-lifecycle-filter-coordinate/src/test/java/org/apache/maven/its/mng12536/SampleTest.java
@@ -0,0 +1,30 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.its.mng12536;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class SampleTest {
+ @Test
+ void alwaysPasses() {
+ assertTrue(true);
+ }
+}