Author: jdcasey
Date: Wed Nov 15 21:11:48 2006
New Revision: 475585
URL: http://svn.apache.org/viewvc?view=rev&rev=475585
Log:
Adding documentation and javadocs, and removing a dormant method from
RepositoryTool until it's been better thought-out.
Modified:
maven/sandbox/maven-plugin-testing-tools/src/main/java/org/apache/maven/shared/test/plugin/BuildTool.java
maven/sandbox/maven-plugin-testing-tools/src/main/java/org/apache/maven/shared/test/plugin/PluginTestTool.java
maven/sandbox/maven-plugin-testing-tools/src/main/java/org/apache/maven/shared/test/plugin/ProjectTool.java
maven/sandbox/maven-plugin-testing-tools/src/main/java/org/apache/maven/shared/test/plugin/RepositoryTool.java
maven/sandbox/maven-plugin-testing-tools/src/site/apt/index.apt
Modified:
maven/sandbox/maven-plugin-testing-tools/src/main/java/org/apache/maven/shared/test/plugin/BuildTool.java
URL:
http://svn.apache.org/viewvc/maven/sandbox/maven-plugin-testing-tools/src/main/java/org/apache/maven/shared/test/plugin/BuildTool.java?view=diff&rev=475585&r1=475584&r2=475585
==============================================================================
---
maven/sandbox/maven-plugin-testing-tools/src/main/java/org/apache/maven/shared/test/plugin/BuildTool.java
(original)
+++
maven/sandbox/maven-plugin-testing-tools/src/main/java/org/apache/maven/shared/test/plugin/BuildTool.java
Wed Nov 15 21:11:48 2006
@@ -20,6 +20,8 @@
import java.util.Properties;
/**
+ * Test-tool used to execute Maven builds in order to test plugin
functionality.
+ *
* @plexus.component role="org.apache.maven.shared.test.plugin.BuildTool"
role-hint="default"
* @author jdcasey
*
@@ -31,7 +33,20 @@
private Invoker mavenInvoker;
- protected InvocationResult executeMaven( File pom, Properties properties,
List goals, File buildLogFile )
+ /**
+ * Build a standard InvocationRequest using the specified test-build POM,
command-line properties,
+ * goals, and output logfile. Then, execute Maven using this standard
request. Return the result
+ * of the invocation.
+ *
+ * @param pom The test-build POM
+ * @param properties command-line properties to fine-tune the test build,
or test parameter
+ * extraction from CLI properties
+ * @param goals The list of goals and/or lifecycle phases to execute
during this build
+ * @param buildLogFile The logfile used to capture build output
+ * @return The result of the Maven invocation, including exit value and
any execution exceptions
+ * resulting from the Maven invocation.
+ */
+ public InvocationResult executeMaven( File pom, Properties properties,
List goals, File buildLogFile )
throws TestToolsException
{
InvocationRequest request = createBasicInvocationRequest( pom,
properties, goals, buildLogFile );
@@ -39,6 +54,15 @@
return executeMaven( request );
}
+ /**
+ * Execute a test build using a customized InvocationRequest. Normally,
this request would be
+ * created using the <code>createBasicInvocationRequest</code> method in
this class.
+ *
+ * @param request The customized InvocationRequest containing the
configuration used to execute
+ * the current test build
+ * @return The result of the Maven invocation, containing exit value,
along with any execution
+ * exceptions resulting from the [attempted] Maven invocation.
+ */
public InvocationResult executeMaven( InvocationRequest request )
throws TestToolsException
{
@@ -56,6 +80,13 @@
}
}
+ /**
+ * Detect the location of the local Maven installation, and start up the
MavenInvoker using that
+ * path. Detection uses the system property <code>maven.home</code>, and
falls back to the shell
+ * environment variable <code>M2_HOME</code>.
+ *
+ * @throws IOException in case the shell environment variables cannot be
read
+ */
private void startInvoker()
throws IOException
{
@@ -77,6 +108,12 @@
}
}
+ /**
+ * If we're logging output to a logfile using standard output handlers,
make sure these are
+ * closed.
+ *
+ * @param request
+ */
private void closeHandlers( InvocationRequest request )
{
InvocationOutputHandler outHandler = request.getOutputHandler( null );
@@ -95,6 +132,20 @@
}
}
+ /**
+ * Construct a standardized InvocationRequest given the test-build POM, a
set of CLI properties,
+ * a list of goals to execute, and the location of a log file to which
build output should be
+ * directed. The resulting InvocationRequest can then be customized by the
test class before
+ * being used to execute a test build. Both standard-out and
standard-error will be directed
+ * to the specified log file.
+ *
+ * @param pom The POM for the test build
+ * @param properties The command-line properties for use in this test build
+ * @param goals The goals and/or lifecycle phases to execute during the
test build
+ * @param buildLogFile Location to which build output should be logged
+ * @return The standardized InvocationRequest for the test build, ready
for any necessary
+ * customizations.
+ */
public InvocationRequest createBasicInvocationRequest( File pom,
Properties properties, List goals,
File buildLogFile )
{
@@ -162,6 +213,10 @@
}
+ /**
+ * Initialize this tool once it's been instantiated and composed, in order
to start up the
+ * MavenInvoker instance.
+ */
public void initialize()
throws InitializationException
{
@@ -176,6 +231,10 @@
}
+ /**
+ * Not currently used; when this API switches to use the Maven Embedder,
it will be used to
+ * shutdown the embedder and its associated container, to free up JVM
memory.
+ */
public void dispose()
{
// TODO: When we switch to the embedder, use this to deallocate the
MavenEmbedder, along
Modified:
maven/sandbox/maven-plugin-testing-tools/src/main/java/org/apache/maven/shared/test/plugin/PluginTestTool.java
URL:
http://svn.apache.org/viewvc/maven/sandbox/maven-plugin-testing-tools/src/main/java/org/apache/maven/shared/test/plugin/PluginTestTool.java?view=diff&rev=475585&r1=475584&r2=475585
==============================================================================
---
maven/sandbox/maven-plugin-testing-tools/src/main/java/org/apache/maven/shared/test/plugin/PluginTestTool.java
(original)
+++
maven/sandbox/maven-plugin-testing-tools/src/main/java/org/apache/maven/shared/test/plugin/PluginTestTool.java
Wed Nov 15 21:11:48 2006
@@ -5,6 +5,19 @@
import java.io.File;
/**
+ * Test tool that provides a single point of access for staging a plugin
artifact - along with its
+ * POM lineage - into a clean test-time local repository. This involves
modifying the plugin POM to
+ * provide a stable test-time version for test-build POMs to reference, then
installing the plugin
+ * jar and associated POMs (including those ancestors that are reachable using
<relativePath>)
+ * into the test local repository.
+ *
+ * <p>
+ * <b>WARNING:</b> Currently, the <code>RepositoryTool</code> will not
+ * resolve parent POMs that exist <b>only</b> in your normal local repository,
and are not reachable
+ * using the relativePath element. This may result in failed test builds, as
one or more of the
+ * plugin's ancestor POMs cannot be resolved.
+ * </p>
+ *
* @plexus.component role="org.apache.maven.shared.test.plugin.PluginTestTool"
role-hint="default"
* @author jdcasey
*
@@ -23,24 +36,65 @@
*/
private RepositoryTool repositoryTool;
+ /**
+ * Stage the plugin, using a stable version, into a temporary
local-repository directory that is
+ * generated by this method. When the plugin is staged, return the local
repository base directory
+ * for use in test builds.
+ *
+ * @param testVersion The test version for the plugin, used for reference
in test-build POMs and
+ * fully-qualified goals
+ * @return The base-directory location of the generated local repository
+ */
public File preparePluginForIntegrationTesting( String testVersion )
throws TestToolsException
{
return prepareForTesting( testVersion, false, null );
}
+ /**
+ * Stage the plugin, using a stable version, into a temporary
local-repository directory that is
+ * generated by this method. When the plugin is staged, return the local
repository base directory
+ * for use in test builds. This method also skips unit testing during
plugin jar production,
+ * since it is assumed that executing these tests would lead to a
recursive test-and-build loop.
+ *
+ * @param testVersion The test version for the plugin, used for reference
in test-build POMs and
+ * fully-qualified goals
+ * @return The base-directory location of the generated local repository
+ */
public File preparePluginForUnitTestingWithMavenBuilds( String testVersion
)
throws TestToolsException
{
return prepareForTesting( testVersion, true, null );
}
+ /**
+ * Stage the plugin, using a stable version, into the specified
local-repository directory.
+ * When the plugin is staged, return the local repository base directory
for verification.
+ *
+ * @param testVersion The test version for the plugin, used for reference
in test-build POMs and
+ * fully-qualified goals
+ * @param localRepositoryDir The base-directory location of the test local
repository, into which
+ * the plugin's test version should be staged.
+ * @return The base-directory location of the generated local repository
+ */
public File preparePluginForIntegrationTesting( String testVersion, File
localRepositoryDir )
throws TestToolsException
{
return prepareForTesting( testVersion, false, localRepositoryDir );
}
+ /**
+ * Stage the plugin, using a stable version, into the specified
local-repository directory.
+ * When the plugin is staged, return the local repository base directory
for verification. This
+ * method also skips unit testing during plugin jar production, since it
is assumed that
+ * executing these tests would lead to a recursive test-and-build loop.
+ *
+ * @param testVersion The test version for the plugin, used for reference
in test-build POMs and
+ * fully-qualified goals
+ * @param localRepositoryDir The base-directory location of the test local
repository, into which
+ * the plugin's test version should be staged.
+ * @return The base-directory location of the generated local repository
+ */
public File preparePluginForUnitTestingWithMavenBuilds( String
testVersion, File localRepositoryDir )
throws TestToolsException
{
Modified:
maven/sandbox/maven-plugin-testing-tools/src/main/java/org/apache/maven/shared/test/plugin/ProjectTool.java
URL:
http://svn.apache.org/viewvc/maven/sandbox/maven-plugin-testing-tools/src/main/java/org/apache/maven/shared/test/plugin/ProjectTool.java?view=diff&rev=475585&r1=475584&r2=475585
==============================================================================
---
maven/sandbox/maven-plugin-testing-tools/src/main/java/org/apache/maven/shared/test/plugin/ProjectTool.java
(original)
+++
maven/sandbox/maven-plugin-testing-tools/src/main/java/org/apache/maven/shared/test/plugin/ProjectTool.java
Wed Nov 15 21:11:48 2006
@@ -28,9 +28,12 @@
import java.util.Properties;
/**
+ * Testing tool used to read MavenProject instances from pom.xml files, and to
create plugin jar
+ * files (package phase of the normal build process) for distribution to a
test local repository
+ * directory.
+ *
* @plexus.component role="org.apache.maven.shared.test.plugin.ProjectTool"
role-hint="default"
* @author jdcasey
- *
*/
public class ProjectTool
{
@@ -61,12 +64,19 @@
*/
private ArtifactFactory artifactFactory;
+ /**
+ * Construct a MavenProject instance from the specified POM file.
+ */
public MavenProject readProject( File pomFile )
throws TestToolsException
{
return readProject( pomFile,
repositoryTool.findLocalRepositoryDirectory() );
}
+ /**
+ * Construct a MavenProject instance from the specified POM file, using
the specified local
+ * repository directory to resolve ancestor POMs as needed.
+ */
public MavenProject readProject( File pomFile, File localRepositoryBasedir
)
throws TestToolsException
{
@@ -83,12 +93,50 @@
}
}
+ /**
+ * Run the plugin's Maven build up to the package phase, in order to
produce a jar file for
+ * distribution to a test-time local repository. The testVersion parameter
specifies the version
+ * to be used in the <version/> element of the plugin configuration,
and also in fully
+ * qualified, unambiguous goal invocations (as in
+ * org.apache.maven.plugins:maven-eclipse-plugin:test:eclipse).
+ *
+ * @param pomFile The plugin's POM
+ * @param testVersion The version to use for testing this plugin. To
promote test resiliency,
+ * this version should remain unchanged, regardless of what plugin
version is under
+ * development.
+ * @param skipUnitTests In cases where test builds occur during the
unit-testing phase (usually
+ * a bad testing smell), the plugin jar must be produced <b>without</b>
running unit tests.
+ * Otherwise, the testing process will result in a recursive loop of
building a plugin jar and
+ * trying to unit test it during the build. In these cases, set this
flag to <code>true</code>.
+ * @return The resulting MavenProject, after the test version and skip
flag (for unit tests)
+ * have been appropriately configured.
+ */
public MavenProject packageProjectArtifact( File pomFile, String
testVersion, boolean skipUnitTests )
throws TestToolsException
{
return packageProjectArtifact( pomFile, testVersion, skipUnitTests,
null );
}
+ /**
+ * Run the plugin's Maven build up to the package phase, in order to
produce a jar file for
+ * distribution to a test-time local repository. The testVersion parameter
specifies the version
+ * to be used in the <version/> element of the plugin configuration,
and also in fully
+ * qualified, unambiguous goal invocations (as in
+ * org.apache.maven.plugins:maven-eclipse-plugin:test:eclipse).
+ *
+ * @param pomFile The plugin's POM
+ * @param testVersion The version to use for testing this plugin. To
promote test resiliency,
+ * this version should remain unchanged, regardless of what plugin
version is under
+ * development.
+ * @param skipUnitTests In cases where test builds occur during the
unit-testing phase (usually
+ * a bad testing smell), the plugin jar must be produced <b>without</b>
running unit tests.
+ * Otherwise, the testing process will result in a recursive loop of
building a plugin jar and
+ * trying to unit test it during the build. In these cases, set this
flag to <code>true</code>.
+ * @param logFile The file to which build output should be logged, in
order to allow later
+ * inspection in case this build fails.
+ * @return The resulting MavenProject, after the test version and skip
flag (for unit tests)
+ * have been appropriately configured.
+ */
public MavenProject packageProjectArtifact( File pomFile, String
testVersion, boolean skipUnitTests, File logFile )
throws TestToolsException
{
@@ -127,6 +175,17 @@
}
}
+ /**
+ * Inject a special version for testing, to allow tests to unambiguously
reference the plugin
+ * currently under test. If test builds will be executed from the
unit-testing phase, also inject
+ * <skip>true</skip> into the configuration of the
<code>maven-surefire-plugin</code>
+ * to allow production of a test-only version of the plugin jar without
running unit tests.
+ *
+ * @param pomFile The plugin POM
+ * @param testVersion The version that allows test builds to reference the
plugin under test
+ * @param skipUnitTests If true, configure the surefire plugin to skip
unit tests
+ * @return Information about mangled POM, including the temporary file to
which it was written.
+ */
protected PomInfo manglePomForTesting( File pomFile, String testVersion,
boolean skipUnitTests )
throws TestToolsException
{
@@ -256,22 +315,22 @@
this.finalName = finalName;
}
- public File getPomFile()
+ File getPomFile()
{
return pomFile;
}
- public String getBuildOutputDirectory()
+ String getBuildOutputDirectory()
{
return buildOutputDirectory;
}
- public String getFinalName()
+ String getFinalName()
{
return finalName;
}
- public File getBuildLogFile()
+ File getBuildLogFile()
{
return new File( buildOutputDirectory + "/test-build-logs/" +
groupId + "_" + artifactId + "_" + version
+ ".build.log" );
Modified:
maven/sandbox/maven-plugin-testing-tools/src/main/java/org/apache/maven/shared/test/plugin/RepositoryTool.java
URL:
http://svn.apache.org/viewvc/maven/sandbox/maven-plugin-testing-tools/src/main/java/org/apache/maven/shared/test/plugin/RepositoryTool.java?view=diff&rev=475585&r1=475584&r2=475585
==============================================================================
---
maven/sandbox/maven-plugin-testing-tools/src/main/java/org/apache/maven/shared/test/plugin/RepositoryTool.java
(original)
+++
maven/sandbox/maven-plugin-testing-tools/src/main/java/org/apache/maven/shared/test/plugin/RepositoryTool.java
Wed Nov 15 21:11:48 2006
@@ -14,10 +14,6 @@
import org.apache.maven.project.artifact.ProjectArtifactMetadata;
import org.apache.maven.settings.MavenSettingsBuilder;
import org.apache.maven.settings.Settings;
-import org.apache.maven.shared.repository.RepositoryAssembler;
-import org.apache.maven.shared.repository.RepositoryAssemblyException;
-import org.apache.maven.shared.repository.RepositoryBuilderConfigSource;
-import org.apache.maven.shared.repository.model.RepositoryInfo;
import org.codehaus.plexus.PlexusConstants;
import org.codehaus.plexus.PlexusContainer;
import
org.codehaus.plexus.component.repository.exception.ComponentLookupException;
@@ -33,9 +29,18 @@
import java.net.MalformedURLException;
/**
+ * Tools to access and manage Maven repositories for test builds, including
construction of a local
+ * repository directory structure.
+ *
+ * <p>
+ * <b>WARNING:</b> Currently, the <code>createLocalRepositoryFromPlugin</code>
method will not
+ * resolve parent POMs that exist <b>only</b> in your normal local repository,
and are not reachable
+ * using the relativePath element. This may result in failed test builds, as
one or more of the
+ * plugin's ancestor POMs cannot be resolved.
+ * </p>
+ *
* @plexus.component role="org.apache.maven.shared.test.plugin.RepositoryTool"
role-hint="default"
* @author jdcasey
- *
*/
public class RepositoryTool
implements Contextualizable
@@ -50,11 +55,6 @@
/**
* @plexus.requirement
*/
- private RepositoryAssembler repositoryAssembler;
-
- /**
- * @plexus.requirement
- */
private MavenSettingsBuilder settingsBuilder;
/**
@@ -70,6 +70,9 @@
// contextualized.
private PlexusContainer container;
+ /**
+ * Lookup and return the location of the normal Maven local repository.
+ */
public File findLocalRepositoryDirectory() throws TestToolsException
{
Settings settings;
@@ -89,6 +92,9 @@
return new File( settings.getLocalRepository() );
}
+ /**
+ * Construct an ArtifactRepository instance that refers to the normal
Maven local repository.
+ */
public ArtifactRepository createLocalArtifactRepositoryInstance()
throws TestToolsException
{
@@ -97,6 +103,10 @@
return createLocalArtifactRepositoryInstance( localRepoDir );
}
+ /**
+ * Construct an ArtifactRepository instance that refers to the test-time
Maven local repository.
+ * @param localRepositoryDirectory The location of the local repository to
be used for test builds.
+ */
public ArtifactRepository createLocalArtifactRepositoryInstance( File
localRepositoryDirectory )
throws TestToolsException
{
@@ -122,13 +132,21 @@
}
- public void buildRepository( File targetDirectory, RepositoryInfo
repositoryInfo,
- RepositoryBuilderConfigSource configSource )
- throws RepositoryAssemblyException
- {
- repositoryAssembler.buildRemoteRepository( targetDirectory,
repositoryInfo, configSource );
- }
-
+ /**
+ * Install a test version of a plugin - along with its POM, and as many
ancestor POMs as can be
+ * reached using the <relativePath/> element - to a clean local
repository directory for
+ * use in test builds.
+ *
+ * <p>
+ * <b>WARNING:</b> Currently, this method will not resolve parent POMs
that exist <b>only</b> in
+ * your normal local repository, and are not reachable using the
relativePath element. This may
+ * result in failed test builds, as one or more of the plugin's ancestor
POMs cannot be resolved.
+ * </p>
+ *
+ * @param pluginProject
+ * @param targetLocalRepoBasedir
+ * @throws TestToolsException
+ */
public void createLocalRepositoryFromPlugin( MavenProject pluginProject,
File targetLocalRepoBasedir )
throws TestToolsException
{
@@ -156,6 +174,13 @@
installLocallyReachableAncestorPoms( pluginProject.getFile(),
localRepository );
}
+ /**
+ * Traverse <relativePath/> links for successive POMs in the
plugin's ancestry, installing
+ * each one into the test-time local repository.
+ *
+ * @param pomFile The plugin POM; a starting point.
+ * @param localRepo The test-time local repository instance
+ */
private void installLocallyReachableAncestorPoms( File pomFile,
ArtifactRepository localRepo )
throws TestToolsException
{
@@ -236,6 +261,11 @@
}
}
+ /**
+ * Retrieve the PlexusContainer instance used to instantiate this
component. The container is
+ * used to retrieve the default ArtifactRepositoryLayout component, for
use in constructing
+ * instances of ArtifactRepository that can be used to access local
repositories.
+ */
public void contextualize( Context context )
throws ContextException
{
Modified: maven/sandbox/maven-plugin-testing-tools/src/site/apt/index.apt
URL:
http://svn.apache.org/viewvc/maven/sandbox/maven-plugin-testing-tools/src/site/apt/index.apt?view=diff&rev=475585&r1=475584&r2=475585
==============================================================================
--- maven/sandbox/maven-plugin-testing-tools/src/site/apt/index.apt (original)
+++ maven/sandbox/maven-plugin-testing-tools/src/site/apt/index.apt Wed Nov 15
21:11:48 2006
@@ -41,7 +41,8 @@
plugin integration tests require a custom local repository, to which the
integration-testing builds
can be directed. Further complicating this testing scenario is the fact that
the plugin's parent
POM or one of its ancestor POMs could be a snapshot which has been installed
in the main local
- repository, but which is not reachable using the plugin-POM's
<<<\<relativePath/\>>>> parent-element.+
+ repository, but which is not reachable using the plugin-POM's
<<<\<relativePath/\>>>>
+ parent-element.<+>
<+ All of this seems to indicate that the best approach for ensuring the
presence of all required
POMs and plugins is to use the normal local repository to construct a new
local repository for
@@ -77,9 +78,48 @@
* Integration-Testing Requirements
- To summarize, this library strives to meet the following requirements for
integration testing:
+ To summarize, this library strives to satisfy the following requirements for
integration testing
+ of Maven plugins:
* Trigger Maven builds using test projects, without incurring any sort of
conflict with plugins
already in use within the current (this plugin's) build.
- *
+ * Construct a local repository into which the test version of the plugin can
be installed,
+ allowing the main local repository to remain untouched by the tests.
Integration tests can be
+ directed to use this test-time local repository instead of the normal
location.
+
+ * Support tracking and analysis of results from Maven builds spawned during
integration testing.
+ As far as is reasonable, test builds should be configured in the same way
as normal project
+ builds, to make the most of test cases submitted by users along with the
issues they file.
+
+ []
+
+* Utilities Included in this Library
+
+ For more information on the APIs described below, see the
{{{apidocs/index.html}JavaDocs}}.
+
+ * <<PluginTestTool>> - The main entry point for setting up the
plugin-testing environment, this
+ utility orchestrates the ProjectTool, RepositoryTool, and BuildTool in
order to produce a local
+ repository containing the plugin jar, plus any ancestor POM files that are
reachable using the
+ <<<\<relativePath/\>>>> element of the parent specification.
+
+ In order to make test projects more resilient to changes in the plugin's
version, this tool
+ allows the developer to specify a testing version for the plugin, so any
reference to the plugin
+ can be unambiguous and avoid accidentally referring to a plugin version
resolved from outside.
+
+ * <<ProjectTool>> - This testing tool provides APIs for creating a testable
plugin jar file,
+ optionally skipping the unit tests for the plugin (after all, it's
conceivable that the unit
+ tests themselves may be using these tools).
+
+ * <<RepositoryTool>> - The RepositoryTool provides methods for assembling
artifact repositories to
+ support testing. This tool is responsible for assembling the local
repository that is used
+ during integration testing - complete with the test version of the plugin
itself, along with all
+ of the ancestor POMs that are reachable via <<<\<relativePath/\>>>>.
+
+ * <<BuildTool>> - This tool's purpose is fairly self-explanatory; it is used
to execute Maven
+ builds. It provides a fairly generic API for running builds, for the
simple reason that a single
+ test may need to run multiple builds. For normal use cases, it's a good
idea to wrap the
+ BuildTool API using a standard project-testing method that will
standardize the options used to
+ run a similar set of test builds.
+
+ []
