diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..d3c72f7 --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,303 @@ + + +# Migration Guide: From maven-verifier to maven-executor + +## ⚠️ Deprecation Notice + +**Apache Maven Verifier is deprecated and will be replaced by [maven-executor](https://github.com/apache/maven/tree/master/impl/maven-executor).** + +New projects should use maven-executor. Existing projects should plan migration to maven-executor. + +See [Issue #186](https://github.com/apache/maven-verifier/issues/186) for more details. + +## Why Migrate? + +### Problems with Current Ecosystem + +Maven currently has two overlapping components for running Maven programmatically: +- **maven-invoker**: Can only fork Maven processes +- **maven-verifier**: Can fork or embed Maven, but with helper methods unnecessarily coupled to execution + +Both have issues: +- ❌ Different APIs for the same purpose +- ❌ Require updates when Maven CLI changes +- ❌ Heavy-handed solutions with duplicated concerns +- ❌ No unified approach for Maven 3 and Maven 4 support +- ❌ Time-consuming to maintain + +### Benefits of maven-executor + +- ✅ **Unified API**: Single, simple API without need for changes when CLI changes +- ✅ **Both execution modes**: Supports both "forked" and "embedded" executors +- ✅ **Dependency-less**: Minimal dependencies +- ✅ **Maven 3.9 & 4+ support**: Transparent support for both Maven versions +- ✅ **Better isolation**: Proper environment isolation +- ✅ **Already in use**: Powers Maven 4 Integration Tests + +## Migration Path + +### 1. Update Dependencies + +**Remove:** +```xml + + org.apache.maven.shared + maven-verifier + test + +``` + +**Add:** +```xml + + org.apache.maven + maven-executor + 4.0.0-rc-5 + test + +``` + +> **Note**: maven-executor location may change as it might be moved out of Maven 4 core to become a standalone project. Check the latest documentation. + +### 2. Code Migration Examples + +#### Before (maven-verifier): + +```java +import org.apache.maven.shared.verifier.Verifier; +import org.apache.maven.shared.verifier.VerificationException; + +public class MyTest { + @Test + public void testBuild() throws Exception { + String baseDir = "/path/to/project"; + Verifier verifier = new Verifier(baseDir); + + // Configure + verifier.setAutoclean(false); + verifier.setMavenDebug(true); + verifier.addCliArgument("-DskipTests=true"); + + // Execute + verifier.addCliArgument("package"); + verifier.execute(); + + // Verify + verifier.verifyErrorFreeLog(); + verifier.verifyFilePresent("target/my-app-1.0.jar"); + verifier.resetStreams(); + } +} +``` + +#### After (maven-executor): + +```java +import org.apache.maven.api.cli.Executor; +import org.apache.maven.api.cli.ExecutorRequest; +import org.apache.maven.cling.executor.forked.ForkedExecutor; +import org.apache.maven.cling.executor.embedded.EmbeddedExecutor; + +import java.nio.file.Path; +import java.nio.file.Paths; +import java.util.Arrays; + +public class MyTest { + @Test + public void testBuild() throws Exception { + Path baseDir = Paths.get("/path/to/project"); + + // Choose executor type: Forked or Embedded + Executor executor = new ForkedExecutor(); + // OR: Executor executor = new EmbeddedExecutor(); + + // Build request with CLI arguments + ExecutorRequest request = ExecutorRequest.builder() + .cwd(baseDir) + .arguments(Arrays.asList("package", "-DskipTests=true", "-X")) + .build(); + + // Execute + int exitCode = executor.execute(request); + + // Verify + assertEquals(0, exitCode, "Build should succeed"); + assertTrue(Files.exists(baseDir.resolve("target/my-app-1.0.jar")), + "JAR file should exist"); + } +} +``` + +### 3. Key API Mapping + +| maven-verifier Concept | maven-executor Equivalent | +|------------------------|---------------------------| +| `new Verifier(baseDir)` | `ExecutorRequest.builder().cwd(baseDir).build()` | +| `verifier.addCliArgument(arg)` | Add to `arguments` list in ExecutorRequest | +| `verifier.setMavenDebug(true)` | Add `-X` to arguments | +| `verifier.setAutoclean(false)` | Manage manually or via arguments | +| `verifier.setForkJvm(true)` | Use `ForkedExecutor` | +| `verifier.setForkJvm(false)` | Use `EmbeddedExecutor` | +| `verifier.execute()` | `executor.execute(request)` | +| `verifier.verifyErrorFreeLog()` | Check `exitCode == 0` | +| `verifier.verifyFilePresent(path)` | Use `Files.exists(Paths.get(...))` | +| `verifier.verifyTextInLog(text)` | Capture and parse executor output | + +### 4. Environment Variables + +**Before:** +```java +verifier.setEnvironmentVariable("JAVA_HOME", "/path/to/java"); +verifier.setEnvironmentVariable("MAVEN_OPTS", "-Xmx1024m"); +``` + +**After:** +```java +Map env = new HashMap<>(); +env.put("JAVA_HOME", "/path/to/java"); +env.put("MAVEN_OPTS", "-Xmx1024m"); + +ExecutorRequest request = ExecutorRequest.builder() + .cwd(baseDir) + .arguments(args) + .environmentVariables(env) + .build(); +``` + +### 5. Verification Helpers + +maven-verifier included many helper methods like `verifyFilePresent()`, `verifyTextInLog()`, etc. These are not part of maven-executor's core responsibility. Instead: + +**Extract verification to separate utilities:** +```java +public class MavenTestUtils { + public static void assertFileExists(Path base, String relativePath) { + Path file = base.resolve(relativePath); + assertTrue(Files.exists(file), + "Expected file does not exist: " + file); + } + + public static void assertLogContains(String log, String expectedText) { + assertTrue(log.contains(expectedText), + "Log does not contain expected text: " + expectedText); + } + + public static void assertErrorFreeLog(String log) { + assertFalse(log.contains("[ERROR]"), + "Log contains errors"); + } +} +``` + +### 6. Settings and Local Repository + +**Before:** +```java +verifier.setLocalRepo("/custom/repo"); +verifier.setUserSettingsFile("/path/to/settings.xml"); +``` + +**After:** +```java +ExecutorRequest request = ExecutorRequest.builder() + .cwd(baseDir) + .arguments(Arrays.asList( + "package", + "-Dmaven.repo.local=/custom/repo", + "-s", "/path/to/settings.xml" + )) + .build(); +``` + +## Migration Checklist + +- [ ] Review all usages of `Verifier` class in your codebase +- [ ] Update POM dependencies to use maven-executor +- [ ] Replace Verifier instantiation with ExecutorRequest builder pattern +- [ ] Convert `addCliArgument()` calls to arguments list +- [ ] Choose between ForkedExecutor and EmbeddedExecutor +- [ ] Replace verification methods with standard Java file checks or custom utilities +- [ ] Update environment variable configuration +- [ ] Update local repository and settings configuration +- [ ] Test thoroughly with your integration test suite +- [ ] Update documentation and comments + +## Gradual Migration Strategy + +For large codebases, consider a gradual approach: + +1. **Phase 1**: Add maven-executor dependency alongside maven-verifier +2. **Phase 2**: Create adapter/wrapper classes to ease transition +3. **Phase 3**: Migrate tests module by module +4. **Phase 4**: Remove maven-verifier dependency once all tests are migrated + +## Example Adapter Pattern + +For gradual migration, you can create an adapter: + +```java +public class MavenExecutorAdapter { + private final Path baseDir; + private final List arguments = new ArrayList<>(); + private final Map env = new HashMap<>(); + private Executor executor = new ForkedExecutor(); + + public MavenExecutorAdapter(String baseDir) { + this.baseDir = Paths.get(baseDir); + } + + public void addCliArgument(String arg) { + arguments.add(arg); + } + + public void setEnvironmentVariable(String key, String value) { + env.put(key, value); + } + + public void setForkJvm(boolean fork) { + executor = fork ? new ForkedExecutor() : new EmbeddedExecutor(); + } + + public void execute() throws Exception { + ExecutorRequest request = ExecutorRequest.builder() + .cwd(baseDir) + .arguments(arguments) + .environmentVariables(env) + .build(); + + int exitCode = executor.execute(request); + if (exitCode != 0) { + throw new Exception("Maven execution failed with exit code: " + exitCode); + } + } + + // Add other adapter methods as needed +} +``` + +## Resources + +- [maven-executor source](https://github.com/apache/maven/tree/master/impl/maven-executor) +- [Maven 4 IT Verifier implementation](https://github.com/apache/maven/blob/master/its/core-it-support/maven-it-helper/src/main/java/org/apache/maven/it/Verifier.java) +- [Issue #186 discussion](https://github.com/apache/maven-verifier/issues/186) + +## Support & Questions + +For migration questions or issues: +- Post to [Maven Dev Mailing List](https://maven.apache.org/mailing-lists.html) +- Open issues on [maven-executor GitHub](https://github.com/apache/maven/issues) diff --git a/README.md b/README.md index 8839ca8..4ef0241 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,15 @@ Contributing to [Apache Maven Verifier](https://maven.apache.org/shared/maven-verifier/) ====================== +> **️ DEPRECATION NOTICE** +> +> **This project is deprecated and will be replaced by [maven-executor](https://github.com/apache/maven/tree/master/impl/maven-executor).** +> +> - **New projects**: Please use maven-executor instead +> - **Existing projects**: Please plan migration to maven-executor +> - See [MIGRATION.md](MIGRATION.md) for migration guide +> - See [Issue #186](https://github.com/apache/maven-verifier/issues/186) for discussion + [![Apache License, Version 2.0, January 2004](https://img.shields.io/github/license/apache/maven.svg?label=License)][license] [![Maven Central](https://img.shields.io/maven-central/v/org.apache.maven.shared/maven-verifier.svg?label=Maven%20Central)](https://search.maven.org/artifact/org.apache.maven.shared/maven-verifier) [![Reproducible Builds](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/jvm-repo-rebuild/reproducible-central/master/content/org/apache/maven/shared/maven-verifier/badge.json)](https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org/apache/maven/shared/maven-verifier/README.md) diff --git a/pom.xml b/pom.xml index 16e22c7..99321e9 100644 --- a/pom.xml +++ b/pom.xml @@ -30,8 +30,12 @@ maven-verifier 2.0.0-M2-SNAPSHOT - Apache Maven Verifier Component - Provides a test harness for Maven integration tests. + Apache Maven Verifier Component (Deprecated) + [DEPRECATED] This component is deprecated and will be replaced by maven-executor. + New projects should use maven-executor (https://github.com/apache/maven/tree/master/impl/maven-executor). + Existing projects should plan migration. See https://github.com/apache/maven-verifier/issues/186 + + Provides a test harness for Maven integration tests. diff --git a/src/main/java/org/apache/maven/shared/verifier/Embedded3xLauncher.java b/src/main/java/org/apache/maven/shared/verifier/Embedded3xLauncher.java index 792bd50..ee69da1 100644 --- a/src/main/java/org/apache/maven/shared/verifier/Embedded3xLauncher.java +++ b/src/main/java/org/apache/maven/shared/verifier/Embedded3xLauncher.java @@ -40,7 +40,12 @@ * Launches an embedded Maven 3.x instance from some Maven installation directory. * * @author Benjamin Bentmann + * @deprecated This class is deprecated. Use + * maven-executor's + * {@code EmbeddedExecutor} instead. + * See Migration Guide. */ +@Deprecated class Embedded3xLauncher implements MavenLauncher { private final Object mavenCli; diff --git a/src/main/java/org/apache/maven/shared/verifier/ForkedLauncher.java b/src/main/java/org/apache/maven/shared/verifier/ForkedLauncher.java index f4a3b73..b5afd80 100644 --- a/src/main/java/org/apache/maven/shared/verifier/ForkedLauncher.java +++ b/src/main/java/org/apache/maven/shared/verifier/ForkedLauncher.java @@ -41,8 +41,15 @@ import org.apache.maven.shared.utils.io.FileUtils; /** + * Launcher implementation that forks a new JVM process to execute Maven. + * * @author Benjamin Bentmann + * @deprecated This class is deprecated. Use + * maven-executor's + * {@code ForkedExecutor} instead. + * See Migration Guide. */ +@Deprecated class ForkedLauncher implements MavenLauncher { private final String mavenHome; diff --git a/src/main/java/org/apache/maven/shared/verifier/LauncherException.java b/src/main/java/org/apache/maven/shared/verifier/LauncherException.java index 867e457..905d3fd 100644 --- a/src/main/java/org/apache/maven/shared/verifier/LauncherException.java +++ b/src/main/java/org/apache/maven/shared/verifier/LauncherException.java @@ -19,8 +19,14 @@ package org.apache.maven.shared.verifier; /** + * Exception thrown when Maven launcher encounters an error. + * * @author Benjamin Bentmann + * @deprecated This exception is deprecated along with the MavenLauncher interface. + * When migrating to maven-executor, use standard Java exceptions. + * See Migration Guide. */ +@Deprecated class LauncherException extends Exception { /** * diff --git a/src/main/java/org/apache/maven/shared/verifier/MavenLauncher.java b/src/main/java/org/apache/maven/shared/verifier/MavenLauncher.java index 23c346f..82fd217 100644 --- a/src/main/java/org/apache/maven/shared/verifier/MavenLauncher.java +++ b/src/main/java/org/apache/maven/shared/verifier/MavenLauncher.java @@ -23,8 +23,15 @@ import java.util.Properties; /** + * Interface for Maven launcher implementations. + * * @author Benjamin Bentmann + * @deprecated This interface is deprecated. Use + * maven-executor's + * {@code Executor} interface instead. + * See Migration Guide. */ +@Deprecated interface MavenLauncher { int run(String[] cliArgs, Properties systemProperties, String workingDirectory, File logFile) diff --git a/src/main/java/org/apache/maven/shared/verifier/VerificationException.java b/src/main/java/org/apache/maven/shared/verifier/VerificationException.java index d3a5342..587d788 100644 --- a/src/main/java/org/apache/maven/shared/verifier/VerificationException.java +++ b/src/main/java/org/apache/maven/shared/verifier/VerificationException.java @@ -19,8 +19,15 @@ package org.apache.maven.shared.verifier; /** + * Exception thrown when Maven verification fails. + * * @author Jason van Zyl + * @deprecated This exception is deprecated along with the Verifier class. + * When migrating to maven-executor, use standard Java exceptions + * and check executor exit codes directly. + * See Migration Guide. */ +@Deprecated public class VerificationException extends Exception { /** * diff --git a/src/main/java/org/apache/maven/shared/verifier/Verifier.java b/src/main/java/org/apache/maven/shared/verifier/Verifier.java index 378ffd0..a7ac3a0 100644 --- a/src/main/java/org/apache/maven/shared/verifier/Verifier.java +++ b/src/main/java/org/apache/maven/shared/verifier/Verifier.java @@ -79,9 +79,49 @@ import org.xml.sax.helpers.DefaultHandler; /** + * Maven test harness for integration tests. + * + *

DEPRECATION NOTICE: This class is deprecated and will be removed in a future version. + * Please migrate to + * maven-executor + * which provides a unified, modern API for programmatic Maven execution with support for both + * Maven 3.9+ and Maven 4+.

+ * + *

Benefits of maven-executor:

+ *
    + *
  • Unified API that doesn't require updates when Maven CLI changes
    • + *
  • Support for both forked and embedded execution modes
    • + *
  • Dependency-less design
    • + *
  • Better environment isolation
    • + *
  • Transparent support for Maven 3.9+ and Maven 4+
    • + *
+ * + *

Migration example:

+ * 
{@code
+ * // Old (maven-verifier):
+ * Verifier verifier = new Verifier("/path/to/project");
+ * verifier.addCliArgument("package");
+ * verifier.execute();
+ * verifier.verifyErrorFreeLog();
+ *
+ * // New (maven-executor):
+ * Executor executor = new ForkedExecutor();
+ * ExecutorRequest request = ExecutorRequest.builder()
+ *     .cwd(Paths.get("/path/to/project"))
+ *     .arguments(List.of("package"))
+ *     .build();
+ * int exitCode = executor.execute(request);
+ * assertEquals(0, exitCode);
+ * }
+ * + * @see Migration Guide + * @see maven-executor * @author Jason van Zyl * @author Brett Porter + * @deprecated Use maven-executor instead. + * See Migration Guide. */ +@Deprecated public class Verifier { private static final String LOG_FILENAME = "log.txt"; diff --git a/src/main/java/org/apache/maven/shared/verifier/util/ResourceExtractor.java b/src/main/java/org/apache/maven/shared/verifier/util/ResourceExtractor.java index befeae8..b284941 100644 --- a/src/main/java/org/apache/maven/shared/verifier/util/ResourceExtractor.java +++ b/src/main/java/org/apache/maven/shared/verifier/util/ResourceExtractor.java @@ -32,8 +32,18 @@ import org.apache.maven.shared.utils.io.IOUtil; /** - * TODO this can be replaced with plexus-archiver + * Utility for extracting test resources. + * + *

Note: This utility class provides functionality independent of + * Maven execution and could potentially be extracted to a separate, non-deprecated + * utility library if there is community interest.

+ * + * @deprecated This class is deprecated as part of maven-verifier deprecation. + * The resource extraction functionality may be moved to a separate utility + * library in the future. For now, users should copy this utility if needed. + * See Issue #186. */ +@Deprecated public class ResourceExtractor { public static File simpleExtractResources(Class cl, String resourcePath) throws IOException { diff --git a/src/site/markdown/getting-started.md b/src/site/markdown/getting-started.md index 2fb690b..9c45f68 100644 --- a/src/site/markdown/getting-started.md +++ b/src/site/markdown/getting-started.md @@ -19,6 +19,15 @@ # Getting Started +> **⚠️ DEPRECATION NOTICE** +> +> **This project is deprecated and will be replaced by [maven-executor](https://github.com/apache/maven/tree/master/impl/maven-executor).** +> +> - **New projects**: Please use maven-executor instead +> - **Existing projects**: Please plan migration to maven-executor +> - See [Migration Guide](https://github.com/apache/maven-verifier/blob/master/MIGRATION.md) +> - See [Issue #186](https://github.com/apache/maven-verifier/issues/186) for discussion + ## Overview Using the `Verifier` consists out of three different phases diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md index f10d5c3..1c512cf 100644 --- a/src/site/markdown/index.md +++ b/src/site/markdown/index.md @@ -19,6 +19,17 @@ # About Apache Maven Verifier Component + + Provides a test harness for Maven integration tests. This is a library which can be used in Java-based integration tests. Look at the [Getting Started guide](./getting-started.html) for more information on how to use it. More complex example usages can be found in the the [different integration tests](https://github.com/apache/maven-integration-testing/tree/master/core-it-suite/src/test/java/org/apache/maven/it) of [Maven Core Integration Tests](https://github.com/apache/maven-integration-testing).