You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by kr...@apache.org on 2012/12/06 20:16:44 UTC
[2/6] o Reformatted entire code base to code style
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/a303827d/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/booterclient/ForkConfigurationTest.java
----------------------------------------------------------------------
diff --git a/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/booterclient/ForkConfigurationTest.java b/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/booterclient/ForkConfigurationTest.java
index 6ec931e..5c93722 100644
--- a/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/booterclient/ForkConfigurationTest.java
+++ b/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/booterclient/ForkConfigurationTest.java
@@ -22,11 +22,10 @@ package org.apache.maven.plugin.surefire.booterclient;
import java.io.File;
import java.io.IOException;
import java.util.Collections;
-
import org.apache.maven.shared.utils.StringUtils;
+import org.apache.maven.shared.utils.cli.Commandline;
import org.apache.maven.surefire.booter.Classpath;
import org.apache.maven.surefire.booter.SurefireBooterForkException;
-import org.apache.maven.shared.utils.cli.Commandline;
import junit.framework.TestCase;
@@ -37,7 +36,7 @@ public class ForkConfigurationTest
public void testCreateCommandLine_UseSystemClassLoaderForkOnce_ShouldConstructManifestOnlyJar()
throws IOException, SurefireBooterForkException
{
- ForkConfiguration config = getForkConfiguration(null, "java");
+ ForkConfiguration config = getForkConfiguration( null, "java" );
File cpElement = getTempClasspathFile();
Commandline cli =
@@ -52,11 +51,11 @@ public class ForkConfigurationTest
{
// SUREFIRE-657
File cpElement = getTempClasspathFile();
- ForkConfiguration forkConfiguration = getForkConfiguration("abc\ndef", null );
+ ForkConfiguration forkConfiguration = getForkConfiguration( "abc\ndef", null );
final Commandline commandLine =
- forkConfiguration.createCommandLine( Collections.singletonList( cpElement.getAbsolutePath() ), false,
- false, 1 );
+ forkConfiguration.createCommandLine( Collections.singletonList( cpElement.getAbsolutePath() ), false, false,
+ 1 );
assertTrue( commandLine.toString().contains( "abc def" ) );
}
@@ -72,8 +71,8 @@ public class ForkConfigurationTest
throws IOException
{
ForkConfiguration forkConfiguration =
- new ForkConfiguration( new Classpath(), null, null, jvm, new File( "." ).getCanonicalFile() ,
- argLine, null, false, 1 );
+ new ForkConfiguration( new Classpath(), null, null, jvm, new File( "." ).getCanonicalFile(), argLine, null,
+ false, 1 );
return forkConfiguration;
}
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/a303827d/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/booterclient/ForkingRunListenerTest.java
----------------------------------------------------------------------
diff --git a/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/booterclient/ForkingRunListenerTest.java b/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/booterclient/ForkingRunListenerTest.java
index 7786876..2006d6b 100644
--- a/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/booterclient/ForkingRunListenerTest.java
+++ b/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/booterclient/ForkingRunListenerTest.java
@@ -257,8 +257,8 @@ public class ForkingRunListenerTest
ReportEntry expected = createDefaultReportEntry();
final SimpleReportEntry secondExpected = createAnotherDefaultReportEntry();
- new ForkingRunListener( printStream, defaultChannel, false).testStarting( expected );
- new ForkingRunListener( printStream, anotherChannel, false).testSkipped( secondExpected );
+ new ForkingRunListener( printStream, defaultChannel, false ).testStarting( expected );
+ new ForkingRunListener( printStream, anotherChannel, false ).testSkipped( secondExpected );
TestSetMockReporterFactory providerReporterFactory = new TestSetMockReporterFactory();
final ForkClient forkStreamClient = new ForkClient( providerReporterFactory, new Properties() );
@@ -279,12 +279,12 @@ public class ForkingRunListenerTest
private SimpleReportEntry createDefaultReportEntry()
{
- return new SimpleReportEntry( "com.abc.TestClass", "testMethod", 22);
+ return new SimpleReportEntry( "com.abc.TestClass", "testMethod", 22 );
}
private SimpleReportEntry createAnotherDefaultReportEntry()
{
- return new SimpleReportEntry( "com.abc.AnotherTestClass", "testAnotherMethod", 42);
+ return new SimpleReportEntry( "com.abc.AnotherTestClass", "testAnotherMethod", 42 );
}
private SimpleReportEntry createReportEntryWithStackTrace()
@@ -297,8 +297,7 @@ public class ForkingRunListenerTest
{
StackTraceWriter stackTraceWriter =
new PojoStackTraceWriter( "org.apache.tests.TestClass", "testMethod11", e );
- return new CategorizedReportEntry( "com.abc.TestClass", "testMethod", "aGroup", stackTraceWriter,
- 77);
+ return new CategorizedReportEntry( "com.abc.TestClass", "testMethod", "aGroup", stackTraceWriter, 77 );
}
}
@@ -312,14 +311,13 @@ public class ForkingRunListenerTest
{
StackTraceWriter stackTraceWriter =
new PojoStackTraceWriter( "org.apache.tests.TestClass", "testMethod11", e );
- return new CategorizedReportEntry( "com.abc.TestClass", "testMethod", "aGroup", stackTraceWriter,
- 77);
+ return new CategorizedReportEntry( "com.abc.TestClass", "testMethod", "aGroup", stackTraceWriter, 77 );
}
}
private RunListener createForkingRunListener( Integer testSetCHannel )
{
- return new ForkingRunListener( printStream, testSetCHannel, false);
+ return new ForkingRunListener( printStream, testSetCHannel, false );
}
private class StandardTestRun
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/a303827d/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/report/StatelessXMLReporterTest.java
----------------------------------------------------------------------
diff --git a/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/report/StatelessXMLReporterTest.java b/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/report/StatelessXMLReporterTest.java
index c3a49ac..340ab3c 100644
--- a/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/report/StatelessXMLReporterTest.java
+++ b/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/report/StatelessXMLReporterTest.java
@@ -20,11 +20,9 @@ package org.apache.maven.plugin.surefire.report;
*/
import java.io.File;
-
import org.apache.maven.surefire.report.PojoStackTraceWriter;
import org.apache.maven.surefire.report.ReportEntry;
import org.apache.maven.surefire.report.SimpleReportEntry;
-import org.codehaus.plexus.util.xml.Xpp3Dom;
import junit.framework.AssertionFailedError;
import junit.framework.TestCase;
@@ -56,7 +54,8 @@ public class StatelessXMLReporterTest
File reportDir = new File( "." );
String testName = "org.apache.maven.plugin.surefire.report.StatelessXMLReporterTest";
reportEntry = new SimpleReportEntry( this.getClass().getName(), testName, 12 );
- WrappedReportEntry testSetReportEntry = new WrappedReportEntry( reportEntry, ReportEntryType.success, 12, null, null );
+ WrappedReportEntry testSetReportEntry =
+ new WrappedReportEntry( reportEntry, ReportEntryType.success, 12, null, null );
stats.testSucceeded( testSetReportEntry );
reporter.testSetCompleted( testSetReportEntry, stats );
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/a303827d/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/report/WrappedReportEntryTest.java
----------------------------------------------------------------------
diff --git a/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/report/WrappedReportEntryTest.java b/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/report/WrappedReportEntryTest.java
index 1229546..f568fa8 100644
--- a/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/report/WrappedReportEntryTest.java
+++ b/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/report/WrappedReportEntryTest.java
@@ -18,10 +18,11 @@ package org.apache.maven.plugin.surefire.report;
* under the License.
*/
-import junit.framework.TestCase;
import org.apache.maven.surefire.report.ReportEntry;
import org.apache.maven.surefire.report.SimpleReportEntry;
+import junit.framework.TestCase;
+
/**
* @author Kristian Rosenvold
*/
@@ -64,7 +65,8 @@ public class WrappedReportEntryTest
ReportEntry reportEntry = new SimpleReportEntry( "fud", category );
WrappedReportEntry wr = new WrappedReportEntry( reportEntry, null, 12, null, null );
String elapsedTimeSummary = wr.getElapsedTimeSummary();
- assertEquals( "[0] 1, 2, 3 (testSum)(surefire.testcase.JunitParamsTest) Time elapsed: 0.012 sec", elapsedTimeSummary );
+ assertEquals( "[0] 1, 2, 3 (testSum)(surefire.testcase.JunitParamsTest) Time elapsed: 0.012 sec",
+ elapsedTimeSummary );
}
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/a303827d/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/runorder/RunEntryStatisticsMapTest.java
----------------------------------------------------------------------
diff --git a/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/runorder/RunEntryStatisticsMapTest.java b/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/runorder/RunEntryStatisticsMapTest.java
index 9d13c87..e86ac4b 100644
--- a/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/runorder/RunEntryStatisticsMapTest.java
+++ b/maven-surefire-common/src/test/java/org/apache/maven/plugin/surefire/runorder/RunEntryStatisticsMapTest.java
@@ -104,7 +104,7 @@ public class RunEntryStatisticsMapTest
class C
{
}
-
+
class NewClass
{
}
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/a303827d/maven-surefire-common/src/test/java/org/apache/maven/surefire/report/ConsoleOutputFileReporterTest.java
----------------------------------------------------------------------
diff --git a/maven-surefire-common/src/test/java/org/apache/maven/surefire/report/ConsoleOutputFileReporterTest.java b/maven-surefire-common/src/test/java/org/apache/maven/surefire/report/ConsoleOutputFileReporterTest.java
index 40e8382..6943b70 100644
--- a/maven-surefire-common/src/test/java/org/apache/maven/surefire/report/ConsoleOutputFileReporterTest.java
+++ b/maven-surefire-common/src/test/java/org/apache/maven/surefire/report/ConsoleOutputFileReporterTest.java
@@ -19,10 +19,10 @@ package org.apache.maven.surefire.report;
* under the License.
*/
-import junit.framework.TestCase;
+import java.io.File;
import org.apache.maven.plugin.surefire.report.ConsoleOutputFileReporter;
-import java.io.File;
+import junit.framework.TestCase;
public class ConsoleOutputFileReporterTest
extends TestCase
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/a303827d/maven-surefire-common/src/test/java/org/apache/maven/surefire/report/FileReporterTest.java
----------------------------------------------------------------------
diff --git a/maven-surefire-common/src/test/java/org/apache/maven/surefire/report/FileReporterTest.java b/maven-surefire-common/src/test/java/org/apache/maven/surefire/report/FileReporterTest.java
index f437044..b2877b1 100644
--- a/maven-surefire-common/src/test/java/org/apache/maven/surefire/report/FileReporterTest.java
+++ b/maven-surefire-common/src/test/java/org/apache/maven/surefire/report/FileReporterTest.java
@@ -19,14 +19,14 @@ package org.apache.maven.surefire.report;
* under the License.
*/
-import junit.framework.TestCase;
+import java.io.File;
+import java.util.ArrayList;
import org.apache.maven.plugin.surefire.report.FileReporter;
import org.apache.maven.plugin.surefire.report.ReportEntryType;
import org.apache.maven.plugin.surefire.report.TestSetStats;
import org.apache.maven.plugin.surefire.report.WrappedReportEntry;
-import java.io.File;
-import java.util.ArrayList;
+import junit.framework.TestCase;
public class FileReporterTest
extends TestCase
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/a303827d/maven-surefire-plugin/pom.xml
----------------------------------------------------------------------
diff --git a/maven-surefire-plugin/pom.xml b/maven-surefire-plugin/pom.xml
index 4623583..550e80e 100644
--- a/maven-surefire-plugin/pom.xml
+++ b/maven-surefire-plugin/pom.xml
@@ -18,7 +18,8 @@
~ under the License.
-->
-<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">
+<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>
<parent>
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/a303827d/maven-surefire-plugin/src/assembly/site-source.xml
----------------------------------------------------------------------
diff --git a/maven-surefire-plugin/src/assembly/site-source.xml b/maven-surefire-plugin/src/assembly/site-source.xml
index 202ed5f..0c563eb 100644
--- a/maven-surefire-plugin/src/assembly/site-source.xml
+++ b/maven-surefire-plugin/src/assembly/site-source.xml
@@ -16,8 +16,9 @@
~ specific language governing permissions and limitations
~ under the License.
-->
-<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 http://maven.apache.org/xsd/assembly-1.1.2.xsd">
+<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 http://maven.apache.org/xsd/assembly-1.1.2.xsd">
<id>site-source</id>
<formats>
<format>zip</format>
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/a303827d/maven-surefire-plugin/src/main/java/org/apache/maven/plugin/surefire/SurefirePlugin.java
----------------------------------------------------------------------
diff --git a/maven-surefire-plugin/src/main/java/org/apache/maven/plugin/surefire/SurefirePlugin.java b/maven-surefire-plugin/src/main/java/org/apache/maven/plugin/surefire/SurefirePlugin.java
index 0126f27..7582ff9 100644
--- a/maven-surefire-plugin/src/main/java/org/apache/maven/plugin/surefire/SurefirePlugin.java
+++ b/maven-surefire-plugin/src/main/java/org/apache/maven/plugin/surefire/SurefirePlugin.java
@@ -35,7 +35,6 @@ import org.apache.maven.surefire.util.internal.StringUtils;
* Run tests using Surefire.
*
* @author Jason van Zyl
- *
* @noinspection JavaDoc
*/
@Mojo( name = "test", defaultPhase = LifecyclePhase.TEST, threadSafe = true,
@@ -144,12 +143,12 @@ public class SurefirePlugin
@Parameter( property = "surefire.useManifestOnlyJar", defaultValue = "true" )
private boolean useManifestOnlyJar;
- protected void handleSummary(RunResult summary, NestedCheckedException firstForkException)
+ protected void handleSummary( RunResult summary, NestedCheckedException firstForkException )
throws MojoExecutionException, MojoFailureException
{
assertNoException( firstForkException );
- SurefireHelper.reportExecution(this, summary, getLog() );
+ SurefireHelper.reportExecution( this, summary, getLog() );
}
private void assertNoException( NestedCheckedException firstForkException )
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/a303827d/maven-surefire-plugin/src/site/apt/api.apt.vm
----------------------------------------------------------------------
diff --git a/maven-surefire-plugin/src/site/apt/api.apt.vm b/maven-surefire-plugin/src/site/apt/api.apt.vm
index 31572c1..95c1a09 100644
--- a/maven-surefire-plugin/src/site/apt/api.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/api.apt.vm
@@ -1,11 +1,11 @@
- ------
- Provider API
- ------
- Kristian Rosenvold
- ------
- 2010-12-09
- ------
-
+------
+Provider API
+------
+Kristian Rosenvold
+------
+2010-12-09
+------
+
~~ 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
@@ -29,64 +29,71 @@
Maven Surefire Provider API
- As of version 2.7 of surefire, there is a proposed public api available for
- external providers to use surefire features.
+As of version 2.7 of surefire, there is a proposed public api available for
+external providers to use surefire features.
- The key features of surefire are forking, reporting and directory/classpath scanning.
- The remaining features are implemented in the providers.
+The key features of surefire are forking, reporting and directory/classpath scanning.
+The remaining features are implemented in the providers.
- Please note that this API is still subject to change until otherwise declared, even in minor revisions. This would
- mostly happen to facilitate needs in new providers.
+Please note that this API is still subject to change until otherwise declared, even in minor revisions. This would
+mostly happen to facilitate needs in new providers.
* Requirements for a provider
- There are three things any provider must fulfill:
+There are three things any provider must fulfill:
- * A provider must implement the <<<org.apache.maven.surefire.providerapi.SurefireProvider>>> interface.
+* A provider must implement the <<
+<org.apache.maven.surefire.providerapi.SurefireProvider>>> interface.
- * A provider contains a <<<META-INF/services>>> file entry named <<<org.apache.maven.surefire.providerapi.SurefireProvider>>>
- ( as per {{{http://download.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html}ServiceLoader}}). This file
- contains the name of the actual provider class.
+ * A provider contains a <<
+ <META-INF
+ /services>>> file entry named <<
+ <org.apache.maven.surefire.providerapi.SurefireProvider>>>
+ ( as per {{{http://download.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html}ServiceLoader}}). This
+ file
+ contains the name of the actual provider class.
- * The actual provider class contains a one-arg constructor that accepts an instance of
- <<<org.apache.maven.surefire.providerapi.ProviderParameters>>>. This interface delivers all the surefire feature
- to the provider implementation, please see the javadoc of this interface for options.
+ * The actual provider class contains a one-arg constructor that accepts an instance of
+ <<
+ <org.apache.maven.surefire.providerapi.ProviderParameters>>>. This interface delivers all the surefire feature
+ to the provider implementation, please see the javadoc of this interface for options.
- There are 4 well-known providers within surefire that are also implemented this way, so
- examples can be found by looking at the surefire source code itself. surefire-junit47 is
- the showcase implementation.
+ There are 4 well-known providers within surefire that are also implemented this way, so
+ examples can be found by looking at the surefire source code itself. surefire-junit47 is
+ the showcase implementation.
- The javadoc on the intefaces mentioned in this article should otherwise be sufficient to write a provider.
- Providers are added as dependencies to the surefire/failsafe plugins.
+ The javadoc on the intefaces mentioned in this article should otherwise be sufficient to write a provider.
+ Providers are added as dependencies to the surefire/failsafe plugins.
-** API Changes for 2.11
+ ** API Changes for 2.11
- Prior to 2.11, the provider would do
+ Prior to 2.11, the provider would do
-+---+
- TestsToRun scanned = directoryScanner.locateTestClasses( testClassLoader, scannerFilter );
-+---+
+ +---+
+ TestsToRun scanned = directoryScanner.locateTestClasses( testClassLoader, scannerFilter );
+ +---+
- and the classes would arrive in sorted order. In 2.11, an additional step must be implemented by the provider;
+ and the classes would arrive in sorted order. In 2.11, an additional step must be implemented by the
+ provider;
-+---+
- TestsToRun scanned = directoryScanner.locateTestClasses( testClassLoader, scannerFilter );
- return providerParameters.getRunOrderCalculator().orderTestClasses( scanned );
-+---+
+ +---+
+ TestsToRun scanned = directoryScanner.locateTestClasses( testClassLoader, scannerFilter );
+ return providerParameters.getRunOrderCalculator().orderTestClasses( scanned );
+ +---+
-** API changes for 2.12.2:
+ ** API changes for 2.12.2:
- Prior to this version, the provider would do
+ Prior to this version, the provider would do
-+---+
- directoryScanner = booterParameters.getDirectoryScanner();
- final TestsToRun scanResult = directoryScanner.locateTestClasses( testClassLoader, testChecker );
-+---+
+ +---+
+ directoryScanner = booterParameters.getDirectoryScanner();
+ final TestsToRun scanResult = directoryScanner.locateTestClasses( testClassLoader, testChecker );
+ +---+
- from this version ProviderParameters#getDirectoryScanner has been deprecated, and *will* be removed
- for the next major version.
+ from this version ProviderParameters#getDirectoryScanner has been deprecated, and *will* be removed
+ for the next major version.
-+---+
- scanResult = booterParameters.getScanResult();
- final TestsToRun testsToRun = scanResult.applyFilter(testChecker, testClassLoader );
-+---+
+ +---+
+ scanResult = booterParameters.getScanResult();
+ final TestsToRun testsToRun = scanResult.applyFilter(testChecker, testClassLoader );
+ +---+
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/a303827d/maven-surefire-plugin/src/site/apt/developing.apt.vm
----------------------------------------------------------------------
diff --git a/maven-surefire-plugin/src/site/apt/developing.apt.vm b/maven-surefire-plugin/src/site/apt/developing.apt.vm
index 954f0ce..6a5012b 100644
--- a/maven-surefire-plugin/src/site/apt/developing.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/developing.apt.vm
@@ -1,51 +1,51 @@
- ------
- Developing surefire
- ------
- Kristian Rosenvold
- ------
- 2011-03-07
- ------
-
- ~~ 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.
-
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+------
+Developing surefire
+------
+Kristian Rosenvold
+------
+2011-03-07
+------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
Developer Center
- When working with surefire, it is necessary to understand a few things:
+When working with surefire, it is necessary to understand a few things:
* Multi-Module project
- The plugin is built as part of a multi-module plugin. The generated
- 'project information' will suggest that you check out (e.g.)
- http://svn.apache.org/repos/asf/maven/surefire/trunk/${project.artifactId}.
- In fact, you need to check out (e.g.)
- http://svn.apache.org/repos/asf/maven/surefire/trunk and
- build from there.
+The plugin is built as part of a multi-module plugin. The generated
+'project information' will suggest that you check out (e.g.)
+http://svn.apache.org/repos/asf/maven/surefire/trunk/${project.artifactId}.
+In fact, you need to check out (e.g.)
+http://svn.apache.org/repos/asf/maven/surefire/trunk and
+build from there.
* Making testcases for demonstrating problems
- When reporting an issue, it is immensely useful to create a small sample project
- that demonstrates the problem. Surefire already contains a large number of such
- projects, and they can be found at
- https://svn.apache.org/repos/asf/maven/surefire/trunk/surefire-integration-tests/src/test/resources/
- Typically you can check out one of the pre-existing projects and run it like this:
+When reporting an issue, it is immensely useful to create a small sample project
+that demonstrates the problem. Surefire already contains a large number of such
+projects, and they can be found at
+https://svn.apache.org/repos/asf/maven/surefire/trunk/surefire-integration-tests/src/test/resources/
+Typically you can check out one of the pre-existing projects and run it like this:
+---+
svn co https://svn.apache.org/repos/asf/maven/surefire/trunk/surefire-integration-tests/src/test/resources/failsafe-buildfail
@@ -55,34 +55,34 @@ mvn -Dsurefire.version=2.12 verify
* Attaching a debugger
- Sometimes it's appropriate to attach a remote debugger to the surefire fork to try to determine what
- is /really/ going on. If you checkout & build trunk, you'd usually do something like this:
+Sometimes it's appropriate to attach a remote debugger to the surefire fork to try to determine what
+is /really/ going on. If you checkout & build trunk, you'd usually do something like this:
+---+
- mvn -Dmaven.surefire.debug=true install
+mvn -Dmaven.surefire.debug=true install
+---+
- Load the source in your IDE, set a breakpoint at the start of ForkedBooter#main and attach
- a debugger to port 5005.
+Load the source in your IDE, set a breakpoint at the start of ForkedBooter#main and attach
+a debugger to port 5005.
* TestCases
- All patches to surefire must contain test coverage, either as an integration test
- or a unit test. All new features (changed/added plugin options) must be covered by
- and end-to-end integration test.
+All patches to surefire must contain test coverage, either as an integration test
+or a unit test. All new features (changed/added plugin options) must be covered by
+and end-to-end integration test.
- There are
- numerous other integration tests that all operate upon small sample projects in
- surefire-integration-tests/src/test/resources
+There are
+numerous other integration tests that all operate upon small sample projects in
+surefire-integration-tests/src/test/resources
- Example integration tests are Surefire141PluggableProvidersIT and the corresponding
- surefire-integration-tests/src/test/resources/surefire-141-pluggableproviders.
+Example integration tests are Surefire141PluggableProvidersIT and the corresponding
+surefire-integration-tests/src/test/resources/surefire-141-pluggableproviders.
* Essential source code reading list
- Some methods/classes reveal more about the basic working of a piece of code than others. The enclosed classes/methods
- are a "reading list" for getting quickly acquainted with the code:
+Some methods/classes reveal more about the basic working of a piece of code than others. The enclosed classes/methods
+are a "reading list" for getting quickly acquainted with the code:
+---+
AbstractSurefireMojo#executeAllProviders
@@ -92,36 +92,36 @@ ForkedBooter#main
* JDK Versions
- The surefire booter is capable of booting all the way back to jdk1.3. Specifically
- this means surefire-api, surefire-booter, common-junit3 and surefire-junit3 are
- source/target 1.3. The plugin and several providers are 1.5.
+The surefire booter is capable of booting all the way back to jdk1.3. Specifically
+this means surefire-api, surefire-booter, common-junit3 and surefire-junit3 are
+source/target 1.3. The plugin and several providers are 1.5.
* Provider Isolation
- Classes in the SUT (Subject Under Test), override any classes within the
- surefire providers. This means providers using any
- third party dependencies (other than the test framework itself), should
- shade these classes to a different package.
+Classes in the SUT (Subject Under Test), override any classes within the
+surefire providers. This means providers using any
+third party dependencies (other than the test framework itself), should
+shade these classes to a different package.
* Common provider modules
- The surefire-providers module contains common-junitXX modules. These modules
- depend on the XX version of JUnit and can access the JUnit API's at the correct
- JUnit version level. Unit tests can also be written that will run with the
- correct JUnit version. At build time, all of the relevant parts of these "common"
- modules are just shaded into the providers jar files.
+The surefire-providers module contains common-junitXX modules. These modules
+depend on the XX version of JUnit and can access the JUnit API's at the correct
+JUnit version level. Unit tests can also be written that will run with the
+correct JUnit version. At build time, all of the relevant parts of these "common"
+modules are just shaded into the providers jar files.
* Shadefire
- "Shadefire" is the first module to be run in the
- surefire build. This creates as shaded version of the JUnit provider, and this provider
- is thereafter used to build surefire itself (As of any release after 2.8). This is
- because the SUT overrides the provider, and the shadefire provider has been
- relocated to avoid this overriding when surefire is building itself.
+"Shadefire" is the first module to be run in the
+surefire build. This creates as shaded version of the JUnit provider, and this provider
+is thereafter used to build surefire itself (As of any release after 2.8). This is
+because the SUT overrides the provider, and the shadefire provider has been
+relocated to avoid this overriding when surefire is building itself.
* Deploying/releasing surefire
- Surefire depends on a previous version of itself, which
- is too advanced for maven 2.2.x dependency resolution, and maven 3.x is
- required to build surefire
\ No newline at end of file
+Surefire depends on a previous version of itself, which
+is too advanced for maven 2.2.x dependency resolution, and maven 3.x is
+required to build surefire
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/a303827d/maven-surefire-plugin/src/site/apt/examples/class-loading.apt.vm
----------------------------------------------------------------------
diff --git a/maven-surefire-plugin/src/site/apt/examples/class-loading.apt.vm b/maven-surefire-plugin/src/site/apt/examples/class-loading.apt.vm
index 7fac4e8..719b524 100644
--- a/maven-surefire-plugin/src/site/apt/examples/class-loading.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/examples/class-loading.apt.vm
@@ -1,174 +1,252 @@
- ------
- Classloading and Forking
- ------
- Dan Fabulich
- ------
- 2010-01-09
- ------
-
- ~~ 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.
-
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+------
+Classloading and Forking
+------
+Dan Fabulich
+------
+2010-01-09
+------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
Classloading and Forking in Maven Surefire
- This page discusses classloading and forking under Maven Surefire which is a shared component used by both
- the Surefire and Failsafe Maven plugins, with an eye towards troubleshooting problems.
+This page discusses classloading and forking under Maven Surefire which is a shared component used by both
+the Surefire and Failsafe Maven plugins, with an eye towards troubleshooting problems.
* Executive Summary
- If you're having problems, you'll probably want to tinker with these three settings: <<<forkMode>>>, <<<useSystemClassLoader>>>, and <<<useManifestOnlyJar>>>.
-
-* What problem does the Maven Surefire project solve?
-
- Initially, the problem seems simple enough. Just launch Java with a classpath, like this:
-
-+---+
-java -classpath foo.jar:bar.jar MyApp
-+---+
-
- But there's a problem here: on some operating systems (Windows), there's a limit on how long you can make
- your command line, and therefore a limit on how long you can make your classpath. The limit is different
- on different versions of Windows; in some versions only a few hundred characters are allowed, in others
- a few thousand, but the limit can be pretty severe in either case.
-
-* Update for Maven Surefire 2.8.2
-
- It turns out setting the <<<CLASSPATH>>> as an environment variable may remove most of the
- practical length limitations, as documented in {{{http://jira.codehaus.org/browse/SUREFIRE-727}SUREFIRE-727}}.
- This means most of the length-related problems in this article may be outdated.
-
-* How do people solve this problem in general?
-
- There are two "tricks" you can use to workaround this problem; both of them can cause other problems in some cases.
-
- 1. <<Isolated Classloader>>: One workaround is to use an isolated classloader.
- Instead of launching MyApp directly, we can launch some other app (a "booter")
- with a much shorter classpath. We can then create a new java.lang.ClassLoader
- (usually a java.net.URLClassLoader) with your classpath configured. The booter
- can then load up MyApp from the classloader; when MyApp refers to other classes,
- they will be automatically loaded from our isolated classloader.
-
- The problem with using an isolated classloader is that your classpath isn't
- <really> correct, and some apps can detect this and object. For example, the
- system property <<<java.class.path>>> won't include your jars; if your app notices
- this, it could cause a problem.
-
- There's another similar problem with using an isolated classloader: any class
- may call the static method <<<ClassLoader.getSystemClassLoader()>>> and attempt to
- load classes out of that classloader, instead of using the default classloader.
- Classes often do this if they need to create classloaders of their own.
- Unfortunately, Java-based web application servers like Jetty, Tomcat, BEA
- WebLogic and IBM WebSphere are very likely to try to escape the confines of an
- isolated classloader.
-
- 2. <<Manifest-Only JAR>>: Another workaround is to use a "manifest-only jar." In
- this case, you create a temporary jar that's almost completely empty, except for
- a META-INF/MANIFEST.MF file. Java manifests can contain attributes that the Java
- VM will honor as directives; for example, you can have a "Class-Path" attribute,
- which contains a list of other jars to add to the classpath. So then you can run
- your code like this:
-
-+---+
-java -classpath booter.jar MyApp
-+---+
-
- This is a bit more realistic, because in this case the system classloader, the
- thread context classloader and the default classloader are all the same; there's
- no possibility of "escaping" the classloader. But this is still a weird
- simulation of a "normal" classpath, and it's still possible for apps to notice
- this. Again, <<<java.class.path>>> may not be what you'd expect ("why does it contain
- only one jar?"). Additionally, it's possible to query the system classloader to
- get the list of jars back out of it; your app may be confused if it finds only
- our <<<booter.jar>>> there!
-
-* Advantages/Disadvantages of each solution
-
- If your app tries to interrogate its own classloader for a list of jars, it may
- work better under an isolated classloader than it would with a manifest-only
- jar. However, if your app tries to escape its default classloader, it may not
- work under an isolated classloader at all.
-
- One advantage of using an isolated classloader is that it's the only way to use
- an isolated classloader without forking a separate process, running all of the
- tests in the same process as Maven itself. But that itself can be pretty risky,
- especially if Maven is running embedded in your IDE!
-
- Finally, of course, you could just try to wire up a plain old Java classpath and hope
- it's short enough. The worst case there is that your classpath might work
- on some machines and not others. Windows boxes would behave differently from
- Linux boxes; users with short user names might have more success than users
- with long user names, etc. For this reason, we chose not to make the basic
- classpath the default, though we do provide it as an option (mostly as a last
- resort).
-
-* What does Maven Surefire do?
-
- Surefire provides a mechanism for using multiple strategies. The main parameter that
- determines this is called <<<useSystemClassLoader>>>. If <<<useSystemClassLoader>>> is
- <<<true>>>, then we use a manifest-only JAR; otherwise, we use an isolated
- classloader. If you want to use a basic plain old Java classpath, you can set
- <<<useManifestOnlyJar=false>>> which only has an effect when <<<useSystemClassLoader=true>>>.
-
- The default value for <<<useSystemClassLoader>>> changed between Surefire 2.3 and
- Surefire 2.4, which was a pretty significant change. In Surefire 2.3,
- <<<useSystemClassLoader>>> was <<<false>>> by default, and we used an isolated classloader.
- In Surefire 2.4, <<<useSystemClassLoader>>> is <<<true>>> by default. No value works for
- everyone, but we think this default is an improvement; a bunch of
- hard-to-diagnose bugs get better when we <<<useSystemClassLoader=true>>>.
-
- Unfortunately, if <<<useSystemClassLoader>>> is set incorrectly for your app, you're going to
- have a problem on your hands that can be quite difficult to diagnose. You might
- even be forced to read a long doc page like this one. ;-)
-
- If you're having problems loading classes, try setting <<<useSystemClassLoader=false>>>
- to see if that helps. You can do that with the POM snippet below, or by setting
- <<<-Dsurefire.useSystemClassLoader=false>>>. If that doesn't work, try setting
- <<<useSystemClassLoader>>> back to <<<true>>> and setting <<<useManifestOnlyJar>>> to <<<false>>>.
-
-+---+
-<project>
- [...]
- <build>
- <plugins>
- <plugin>
- <groupId>${project.groupId}</groupId>
- <artifactId>${project.artifactId}</artifactId>
- <version>${project.version}</version>
- <configuration>
- <useSystemClassLoader>false</useSystemClassLoader>
- </configuration>
- </plugin>
- </plugins>
- </build>
- [...]
-</project>
-+---+
-
-* Debugging Classpath Problems
-
- If you've read this far, you're probably fully equipped to diagnose problems that may occur during classloading. Here's some general tips to try:
-
- * Run mvn with --debug (aka -X) to get more detailed output
-
- * Check your <<<forkMode>>>. If <<<forkMode=never>>>, it's impossible to use the system classloader or a plain old Java classpath; we have to use an isolated classloader.
-
- * If you're using the defaults, <<<useSystemClassLoader=true>>> and <<<useManifestOnlyJar=false>>>. In that case, look at the generated manifest-only Surefire booter JAR. Open it up (it's just a zip) and read its manifest.
-
- * Run mvn with -Dmaven.${thisPlugin.toLowerCase()}.debug, and attach to the running process with a debugger.
\ No newline at end of file
+If you're having problems, you'll probably want to tinker with these three settings: <<
+<forkMode>>>, <<
+ <useSystemClassLoader>>>, and <<
+ <useManifestOnlyJar>>>.
+
+ * What problem does the Maven Surefire project solve?
+
+ Initially, the problem seems simple enough. Just launch Java with a classpath, like this:
+
+ +---+
+ java -classpath foo.jar:bar.jar MyApp
+ +---+
+
+ But there's a problem here: on some operating systems (Windows), there's a limit on how long you can make
+ your command line, and therefore a limit on how long you can make your classpath. The limit is different
+ on different versions of Windows; in some versions only a few hundred characters are allowed, in others
+ a few thousand, but the limit can be pretty severe in either case.
+
+ * Update for Maven Surefire 2.8.2
+
+ It turns out setting the <<
+ <CLASSPATH>>> as an environment variable may remove most of the
+ practical length limitations, as documented in
+ {{{http://jira.codehaus.org/browse/SUREFIRE-727}SUREFIRE-727}}.
+ This means most of the length-related problems in this article may be outdated.
+
+ * How do people solve this problem in general?
+
+ There are two "tricks" you can use to workaround this problem; both of them can cause other problems in
+ some cases.
+
+ 1. <
+ <Isolated Classloader>>: One workaround is to use an isolated classloader.
+ Instead of launching MyApp directly, we can launch some other app (a "booter")
+ with a much shorter classpath. We can then create a new java.lang.ClassLoader
+ (usually a java.net.URLClassLoader) with your classpath configured. The booter
+ can then load up MyApp from the classloader; when MyApp refers to other classes,
+ they will be automatically loaded from our isolated classloader.
+
+ The problem with using an isolated classloader is that your classpath isn't
+ <really> correct, and some apps can detect this and object. For example, the
+ system property <<
+ <java.class.path>>> won't include your jars; if your app notices
+ this, it could cause a problem.
+
+ There's another similar problem with using an isolated classloader: any class
+ may call the static method <<
+ <ClassLoader.getSystemClassLoader
+ ()>>> and attempt to
+ load classes out of that classloader, instead of using the default classloader.
+ Classes often do this if they need to create classloaders of their own.
+ Unfortunately, Java-based web application servers like Jetty, Tomcat, BEA
+ WebLogic and IBM WebSphere are very likely to try to escape the confines of an
+ isolated classloader.
+
+ 2. <
+ <Manifest-Only JAR>>: Another workaround is to use a "manifest-only jar." In
+ this case, you create a temporary jar that's almost completely empty, except for
+ a META-INF/MANIFEST.MF file. Java manifests can contain attributes that the Java
+ VM will honor as directives; for example, you can have a "Class-Path" attribute,
+ which contains a list of other jars to add to the classpath. So then you can run
+ your code like this:
+
+ +---+
+ java -classpath booter.jar MyApp
+ +---+
+
+ This is a bit more realistic, because in this case the system classloader, the
+ thread context classloader and the default classloader are all the same; there's
+ no possibility of "escaping" the classloader. But this is still a weird
+ simulation of a "normal" classpath, and it's still possible for apps to notice
+ this. Again, <<
+ <java.class.path>>> may not be what you'd expect ("why does it contain
+ only one jar?"). Additionally, it's possible to query the system classloader to
+ get the list of jars back out of it; your app may be confused if it finds only
+ our <<
+ <booter.jar>>> there!
+
+ * Advantages/Disadvantages of each solution
+
+ If your app tries to interrogate its own classloader for a list of jars, it may
+ work better under an isolated classloader than it would with a manifest-only
+ jar. However, if your app tries to escape its default classloader, it may not
+ work under an isolated classloader at all.
+
+ One advantage of using an isolated classloader is that it's the only way to use
+ an isolated classloader without forking a separate process, running all of the
+ tests in the same process as Maven itself. But that itself can be pretty risky,
+ especially if Maven is running embedded in your IDE!
+
+ Finally, of course, you could just try to wire up a plain old Java classpath and
+ hope
+ it's short enough. The worst case there is that your classpath might work
+ on some machines and not others. Windows boxes would behave differently from
+ Linux boxes; users with short user names might have more success than users
+ with long user names, etc. For this reason, we chose not to make the basic
+ classpath the default, though we do provide it as an option (mostly as a last
+ resort).
+
+ * What does Maven Surefire do?
+
+ Surefire provides a mechanism for using multiple strategies. The main parameter
+ that
+ determines this is called <<
+ <useSystemClassLoader>>>. If <<
+ <useSystemClassLoader>>> is
+ <<
+ <true>>>, then we use a manifest-only JAR; otherwise, we use an isolated
+ classloader. If you want to use a basic plain old Java classpath,
+ you can set
+ <<
+ <useManifestOnlyJar
+ =false>>> which only has an effect when <<
+ <useSystemClassLoader
+ =true>>>.
+
+ The default value for <<
+ <useSystemClassLoader>>> changed between Surefire 2.3 and
+ Surefire 2.4, which was a pretty significant change. In Surefire
+ 2.3,
+ <<
+ <useSystemClassLoader>>> was <<
+ <false>>> by default, and we used an isolated classloader.
+ In Surefire 2.4, <<
+ <useSystemClassLoader>>> is <<
+ <true>>> by default. No value works for
+ everyone, but we think this default is an
+ improvement; a bunch of
+ hard-to-diagnose bugs get better when we <<
+ <useSystemClassLoader
+ =true>>>.
+
+ Unfortunately, if <<
+ <useSystemClassLoader>>> is set incorrectly for
+ your app, you're going to
+ have a problem on your hands that can be
+ quite difficult to diagnose. You might
+ even be forced to read a long doc page like
+ this one. ;-)
+
+ If you're having problems loading classes,
+ try setting <<
+ <useSystemClassLoader
+ =false>>>
+ to see if that helps. You can do that with
+ the POM snippet below, or by setting
+ <<<-Dsurefire.useSystemClassLoader=false>>>.
+ If that doesn't work, try setting
+ <<
+ <useSystemClassLoader>>> back to <<
+ <true>>> and setting <<
+ <useManifestOnlyJar>>> to <<
+ <false>>>.
+
+ +---+
+ <project>
+ [...]
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>${project.artifactId}</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <useSystemClassLoader>
+ false
+ </useSystemClassLoader>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ [...]
+ </project>
+ +---+
+
+ * Debugging Classpath
+ Problems
+
+ If you've read this far,
+ you're probably fully
+ equipped to diagnose
+ problems that may occur
+ during classloading. Here's
+ some general tips to try:
+
+ * Run mvn with --debug (aka
+ -X) to get more detailed
+ output
+
+ * Check your <<
+ <forkMode>>>. If <<
+ <forkMode
+ =never>>>, it's
+ impossible to use the
+ system classloader or a
+ plain old Java
+ classpath; we have to
+ use an isolated
+ classloader.
+
+ * If you're using the
+ defaults, <<
+ <useSystemClassLoader
+ =true>>> and <<
+ <useManifestOnlyJar
+ =false>>>. In that case,
+ look at the generated
+ manifest-only Surefire
+ booter JAR. Open it up
+ (it's just a zip) and
+ read its manifest.
+
+ * Run mvn with
+ -Dmaven.${thisPlugin.toLowerCase()}
+ .debug, and attach to
+ the running process with
+ a debugger.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/a303827d/maven-surefire-plugin/src/site/apt/examples/configuring-classpath.apt.vm
----------------------------------------------------------------------
diff --git a/maven-surefire-plugin/src/site/apt/examples/configuring-classpath.apt.vm b/maven-surefire-plugin/src/site/apt/examples/configuring-classpath.apt.vm
index 2b2ad4c..2c425b9 100644
--- a/maven-surefire-plugin/src/site/apt/examples/configuring-classpath.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/examples/configuring-classpath.apt.vm
@@ -1,135 +1,146 @@
- ------
- Configuring the Classpath
- ------
- Pascal Lambert
- ------
- 2010-01-09
- ------
-
- ~~ 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.
-
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+------
+Configuring the Classpath
+------
+Pascal Lambert
+------
+2010-01-09
+------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
The Default Classpath
- The surefire plugin builds the test classpath in the following order:
+The surefire plugin builds the test classpath in the following order:
#{if}(${project.artifactId}=="maven-surefire-plugin")
- [[1]] The {{{../test-mojo.html#testClassesDirectory}test-classes}} directory
+[[1]] The {{{../test-mojo.html#testClassesDirectory}test-classes}} directory
- [[2]] The {{{../test-mojo.html#classesDirectory}classes}} directory
+[[2]] The {{{../test-mojo.html#classesDirectory}classes}} directory
#{else}
- [[1]] The {{{../integration-test-mojo.html#testClassesDirectory}test-classes}} directory
+[[1]] The {{{../integration-test-mojo.html#testClassesDirectory}test-classes}} directory
- [[2]] The {{{../integration-test-mojo.html#classesDirectory}classes}} directory
+[[2]] The {{{../integration-test-mojo.html#classesDirectory}classes}} directory
#{end}
- [[3]] The project dependencies
+[[3]] The project dependencies
- [[4]] Additional classpath elements
+[[4]] Additional classpath elements
Additional Classpath Elements
- If you need to put more stuff in your classpath when ${thisPlugin} executes (e.g some funky resources or a container specific JAR),
- we normally recommend you add it to your classpath as a dependency. Consider deploying shared jars to a private remote repository for your
- organization.
-
- But, if you must, you can use the <<<additionalClasspathElements>>> element to add custom resources/jars to your classpath.
- This will be treated as an absolute file system path, so you may want use $\{basedir\} or another property combined with a relative path.
- Note that additional classpath elements are added to the end of the classpath, so you cannot use these to
- override project dependencies or resources.
-
-+---+
-<project>
- [...]
- <build>
- <plugins>
- <plugin>
- <groupId>${project.groupId}</groupId>
- <artifactId>${project.artifactId}</artifactId>
- <version>${project.version}</version>
- <configuration>
- <additionalClasspathElements>
- <additionalClasspathElement>path/to/additional/resources</additionalClasspathElement>
- <additionalClasspathElement>path/to/additional/jar</additionalClasspathElement>
- </additionalClasspathElements>
- </configuration>
- </plugin>
- </plugins>
- </build>
- [...]
-</project>
-+---+
-
-Removing Dependency Classpath Elements
-
- Dependencies can be removed from the test classpath using the parameters <<<classpathDependencyExcludes>>> and
- <<<classpathDependencyScopeExclude>>>. A list of specific dependencies can be removed from the
- classpath by specifying the groupId:artifactId to be removed.
-
-+---+
-<project>
- [...]
- <build>
- <plugins>
- <plugin>
- <groupId>${project.groupId}</groupId>
- <artifactId>${project.artifactId}</artifactId>
- <version>${project.version}</version>
- <configuration>
- <classpathDependencyExcludes>
- <classpathDependencyExcludes>org.apache.commons:commons-email</classpathDependencyExcludes>
- </classpathDependencyExcludes>
- </configuration>
- </plugin>
- </plugins>
- </build>
- [...]
-</project>
-+---+
-
- Dependencies under a certain scope can be removed from the classpath using
- <<<classpathDependencyScopeExclude>>>. The valid values for the dependency scope
- exclude are defined by <<<org.apache.maven.artifact.resolver.filter.ScopeArtifactFilter>>>.
-
- * <<compile>> - system, provided, compile
-
- * <<runtime>> - compile, runtime
-
- * <<test>> - system, provided, compile, runtime, test
-
-+---+
-<project>
- [...]
- <build>
- <plugins>
- <plugin>
- <groupId>${project.groupId}</groupId>
- <artifactId>${project.artifactId}</artifactId>
- <version>${project.version}</version>
- <configuration>
- <classpathDependencyScopeExclude>runtime</classpathDependencyScopeExclude>
- </configuration>
- </plugin>
- </plugins>
- </build>
- [...]
-</project>
-+---+
+If you need to put more stuff in your classpath when ${thisPlugin} executes (e.g some funky resources or a container specific JAR),
+we normally recommend you add it to your classpath as a dependency. Consider deploying shared jars to a private remote repository for your
+organization.
+
+But, if you must, you can use the <<
+<additionalClasspathElements>>> element to add custom resources/jars to your classpath.
+ This will be treated as an absolute file system path, so you may want use $\{basedir\} or another property combined
+ with a relative path.
+ Note that additional classpath elements are added to the end of the classpath, so you cannot use these to
+ override project dependencies or resources.
+
+ +---+
+ <project>
+ [...]
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>${project.artifactId}</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <additionalClasspathElements>
+ <additionalClasspathElement>path/to/additional/resources</additionalClasspathElement>
+ <additionalClasspathElement>path/to/additional/jar</additionalClasspathElement>
+ </additionalClasspathElements>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ [...]
+ </project>
+ +---+
+
+ Removing Dependency Classpath Elements
+
+ Dependencies can be removed from the test classpath using the parameters <<
+ <classpathDependencyExcludes>>> and
+ <<
+ <classpathDependencyScopeExclude>>>. A list of specific dependencies can be removed from the
+ classpath by specifying the groupId:artifactId to be removed.
+
+ +---+
+ <project>
+ [...]
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>${project.artifactId}</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <classpathDependencyExcludes>
+ <classpathDependencyExcludes>org.apache.commons:commons-email
+ </classpathDependencyExcludes>
+ </classpathDependencyExcludes>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ [...]
+ </project>
+ +---+
+
+ Dependencies under a certain scope can be removed from the classpath using
+ <<
+ <classpathDependencyScopeExclude>>>. The valid values for the dependency scope
+ exclude are defined by <<
+ <org.apache.maven.artifact.resolver.filter.ScopeArtifactFilter>>>.
+
+ * <
+ <compile>> - system, provided, compile
+
+ * <
+ <runtime>> - compile, runtime
+
+ * <
+ <test>> - system, provided, compile, runtime, test
+
+ +---+
+ <project>
+ [...]
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>${project.artifactId}</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <classpathDependencyScopeExclude>runtime
+ </classpathDependencyScopeExclude>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ [...]
+ </project>
+ +---+
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/a303827d/maven-surefire-plugin/src/site/apt/examples/debugging.apt.vm
----------------------------------------------------------------------
diff --git a/maven-surefire-plugin/src/site/apt/examples/debugging.apt.vm b/maven-surefire-plugin/src/site/apt/examples/debugging.apt.vm
index f07ff08..9eba148 100644
--- a/maven-surefire-plugin/src/site/apt/examples/debugging.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/examples/debugging.apt.vm
@@ -1,92 +1,100 @@
- ------
- Debugging Tests
- ------
- Dan Fabulich
- ------
- 2010-01-09
- ------
-
- ~~ 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.
-
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+------
+Debugging Tests
+------
+Dan Fabulich
+------
+2010-01-09
+------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
Debugging Tests
- Sometimes you need to debug the tests exactly as Maven ran them. Here's how!
+Sometimes you need to debug the tests exactly as Maven ran them. Here's how!
Forked Tests
- By default, Maven runs your tests in a separate ("forked") process. You can use the <<<maven.${thisPlugin.toLowerCase()}.debug>>> property
- to debug your forked tests remotely, like this:
-
-#{if}(${project.artifactId}=="maven-surefire-plugin")
-+---+
-mvn -Dmaven.${thisPlugin.toLowerCase()}.debug test
-+---+
-#{else}
-+---+
-mvn -Dmaven.${thisPlugin.toLowerCase()}.debug verify
-+---+
-#{end}
-
- The tests will automatically pause and await a remote debugger on port 5005. You can then attach to the running tests
- using Eclipse. You can setup a "Remote Java Application" launch configuration via the menu
- command "Run" > "Open Debug Dialog..."
-
- If you need to configure a different port, you may pass a more detailed value. For example, the command below will use port 8000
- instead of port 5005.
-
-#{if}(${project.artifactId}=="maven-surefire-plugin")
-+---+
-mvn -Dmaven.surefire.debug="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000 -Xnoagent -Djava.compiler=NONE" test
-+---+
-#{else}
-+---+
-mvn -Dmaven.surefire.debug="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000 -Xnoagent -Djava.compiler=NONE" verify
-+---+
-#{end}
-
-Non-forked Tests
-
- You can force Maven not to fork tests by configuring the <<<forkMode>>> configuration parameter.
-
-#{if}(${project.artifactId}=="maven-surefire-plugin")
-+---+
-mvn -DforkMode=never test
-+---+
-#{else}
-+---+
-mvn -DforkMode=never verify
-+---+
-#{end}
-
- Then all you need to do is debug Maven itself. Since Maven 2.0.8, Maven has shipped with a "mvnDebug" shell script that you can
- use to launch Maven with convenient debugging options:
-
-#{if}(${project.artifactId}=="maven-surefire-plugin")
-+---+
-mvnDebug -DforkMode=never test
-+---+
-#{else}
-+---+
-mvnDebug -DforkMode=never verify
-+---+
-#{end}
-
- Then you can attach Eclipse to Maven itself, which may be easier/more convenient than debugging the forked executable.
\ No newline at end of file
+By default, Maven runs your tests in a separate ("forked") process. You can use the <<
+<maven.${thisPlugin.toLowerCase()}.debug>>> property
+ to debug your forked tests remotely, like this:
+
+ #{if}(${project.artifactId}=="maven-surefire-plugin")
+ +---+
+ mvn -Dmaven.${thisPlugin.toLowerCase()}.debug test
+ +---+
+ #{else}
+ +---+
+ mvn -Dmaven.${thisPlugin.toLowerCase()}.debug verify
+ +---+
+ #{end}
+
+ The tests will automatically pause and await a remote debugger on port 5005. You can then attach to the running
+ tests
+ using Eclipse. You can setup a "Remote Java Application" launch configuration via the menu
+ command "Run" > "Open Debug Dialog..."
+
+ If you need to configure a different port, you may pass a more detailed value. For example, the command below will
+ use port 8000
+ instead of port 5005.
+
+ #{if}(${project.artifactId}=="maven-surefire-plugin")
+ +---+
+ mvn -Dmaven.surefire.debug="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000 -Xnoagent
+ -Djava.compiler=NONE" test
+ +---+
+ #{else}
+ +---+
+ mvn -Dmaven.surefire.debug="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000 -Xnoagent
+ -Djava.compiler=NONE" verify
+ +---+
+ #{end}
+
+ Non-forked Tests
+
+ You can force Maven not to fork tests by configuring the <<
+ <forkMode>>> configuration parameter.
+
+ #{if}(${project.artifactId}=="maven-surefire-plugin")
+ +---+
+ mvn -DforkMode=never test
+ +---+
+ #{else}
+ +---+
+ mvn -DforkMode=never verify
+ +---+
+ #{end}
+
+ Then all you need to do is debug Maven itself. Since Maven 2.0.8, Maven has shipped with a "mvnDebug" shell
+ script that you can
+ use to launch Maven with convenient debugging options:
+
+ #{if}(${project.artifactId}=="maven-surefire-plugin")
+ +---+
+ mvnDebug -DforkMode=never test
+ +---+
+ #{else}
+ +---+
+ mvnDebug -DforkMode=never verify
+ +---+
+ #{end}
+
+ Then you can attach Eclipse to Maven itself, which may be easier/more convenient than debugging the forked
+ executable.
\ No newline at end of file