org.apache.maven.plugin.surefire.HelpMojo Maven / Gradle / Ivy
package org.apache.maven.plugin.surefire;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import org.apache.maven.plugin.AbstractMojo;
import org.apache.maven.plugin.MojoExecutionException;
/**
* Display help information on maven-surefire-plugin.
Call mvn surefire:help -Ddetail=true -Dgoal=<goal-name>
to display parameter details.
*
* @version generated on Fri Feb 18 14:33:31 GMT 2011
* @author org.apache.maven.tools.plugin.generator.PluginHelpGenerator (version 2.6)
* @goal help
* @requiresProject false
*/
public class HelpMojo
extends AbstractMojo
{
/**
* If true, display all settable properties for each goal.
*
* @parameter expression="${detail}" default-value="false"
*/
private boolean detail;
/**
* The name of the goal for which to show help. If unspecified, all goals will be displayed.
*
* @parameter expression="${goal}"
*/
private java.lang.String goal;
/**
* The maximum length of a display line, should be positive.
*
* @parameter expression="${lineLength}" default-value="80"
*/
private int lineLength;
/**
* The number of spaces per indentation level, should be positive.
*
* @parameter expression="${indentSize}" default-value="2"
*/
private int indentSize;
/** {@inheritDoc} */
public void execute()
throws MojoExecutionException
{
if ( lineLength <= 0 )
{
getLog().warn( "The parameter 'lineLength' should be positive, using '80' as default." );
lineLength = 80;
}
if ( indentSize <= 0 )
{
getLog().warn( "The parameter 'indentSize' should be positive, using '2' as default." );
indentSize = 2;
}
StringBuffer sb = new StringBuffer();
append( sb, "org.jboss.maven.surefire.modular:maven-surefire-plugin:1.0.0.Alpha2", 0 );
append( sb, "", 0 );
append( sb, "Maven Surefire Plugin", 0 );
append( sb, "Surefire is a test framework project.", 1 );
append( sb, "", 0 );
if ( goal == null || goal.length() <= 0 )
{
append( sb, "This plugin has 2 goals:", 0 );
append( sb, "", 0 );
}
if ( goal == null || goal.length() <= 0 || "help".equals( goal ) )
{
append( sb, "surefire:help", 0 );
append( sb, "Display help information on maven-surefire-plugin.\nCall\n\u00a0\u00a0mvn\u00a0surefire:help\u00a0-Ddetail=true\u00a0-Dgoal=\nto display parameter details.", 1 );
append( sb, "", 0 );
if ( detail )
{
append( sb, "Available parameters:", 1 );
append( sb, "", 0 );
append( sb, "detail (Default: false)", 2 );
append( sb, "If true, display all settable properties for each goal.", 3 );
append( sb, "", 0 );
append( sb, "goal", 2 );
append( sb, "The name of the goal for which to show help. If unspecified, all goals will be displayed.", 3 );
append( sb, "", 0 );
append( sb, "indentSize (Default: 2)", 2 );
append( sb, "The number of spaces per indentation level, should be positive.", 3 );
append( sb, "", 0 );
append( sb, "lineLength (Default: 80)", 2 );
append( sb, "The maximum length of a display line, should be positive.", 3 );
append( sb, "", 0 );
}
}
if ( goal == null || goal.length() <= 0 || "test".equals( goal ) )
{
append( sb, "surefire:test", 0 );
append( sb, "Run tests using Surefire. This is a fork of org.apache.maven.plugins:maven-surefire-plugin:2.6:test. It has the configuration options of the \'real\' surefire plugin (http://maven.apache.org/plugins/maven-surefire-plugin/test-mojo.html), although your mileage may vary if you start playing with the fork modes. The plugin takes a module definition file and creates a directory structure containing modules in the jboss-modules format.", 1 );
append( sb, "", 0 );
if ( detail )
{
append( sb, "Available parameters:", 1 );
append( sb, "", 0 );
append( sb, "additionalClasspathElements", 2 );
append( sb, "Additional elements to be appended to the classpath.", 3 );
append( sb, "", 0 );
append( sb, "argLine", 2 );
append( sb, "Arbitrary JVM options to set on the command line.", 3 );
append( sb, "", 0 );
append( sb, "basedir (Default: ${basedir})", 2 );
append( sb, "The base directory of the project being tested. This can be obtained in your unit test by System.getProperty(\'basedir\').", 3 );
append( sb, "", 0 );
append( sb, "childDelegation (Default: false)", 2 );
append( sb, "When false it makes tests run using the standard classloader delegation instead of the default Maven isolated classloader. Only used when forking (forkMode is not \'none\').\nSetting it to false helps with some problems caused by conflicts between xml parsers in the classpath and the Java 5 provider parser.", 3 );
append( sb, "", 0 );
append( sb, "classesDirectory (Default: ${project.build.outputDirectory})", 2 );
append( sb, "The directory containing generated classes of the project being tested. This will be included after the test classes in the test classpath.", 3 );
append( sb, "", 0 );
append( sb, "classpathDependencyExcludes", 2 );
append( sb, "List of dependencies to exclude from the test classpath. Each dependency string must follow the format groupId:artifactId. For example: org.acme:project-a", 3 );
append( sb, "", 0 );
append( sb, "classpathDependencyScopeExclude", 2 );
append( sb, "A dependency scope to exclude from the test classpath The scope can be one of the following scopes:\n-\tcompile - system, provided, compile\n-\truntime - compile, runtime\n-\ttest - system, provided, compile, runtime, test\n", 3 );
append( sb, "", 0 );
append( sb, "cleanModulesDirectory (Default: true)", 2 );
append( sb, "If true (default) clean out the modules directory each time we run the tests.", 3 );
append( sb, "", 0 );
append( sb, "debugForkedProcess", 2 );
append( sb, "Attach a debugger to the forked JVM. If set to \'true\', the process will suspend and wait for a debugger to attach on port 5005. If set to some other string, that string will be appended to the argLine, allowing you to configure arbitrary debuggability options (without overwriting the other options specified in the argLine).", 3 );
append( sb, "", 0 );
append( sb, "disableXmlReport (Default: false)", 2 );
append( sb, "Flag to disable the generation of report files in xml format.", 3 );
append( sb, "", 0 );
append( sb, "enableAssertions (Default: true)", 2 );
append( sb, "By default, Surefire enables JVM assertions for the execution of your test cases. To disable the assertions, set this flag to false.", 3 );
append( sb, "", 0 );
append( sb, "environmentVariables", 2 );
append( sb, "Additional environments to set on the command line.", 3 );
append( sb, "", 0 );
append( sb, "excludedGroups", 2 );
append( sb, "(TestNG only) Excluded groups. Any methods/classes/etc with one of the groups specified in this list will specifically not be run. This parameter is overridden if suiteXmlFiles are specified.", 3 );
append( sb, "", 0 );
append( sb, "excludes", 2 );
append( sb, "List of patterns (separated by commas) used to specify the tests that should be excluded in testing. When not specified and when the test parameter is not specified, the default excludes will be **/*$* (which excludes all inner classes). This parameter is ignored if TestNG suiteXmlFiles are specified.", 3 );
append( sb, "", 0 );
append( sb, "failIfNoTests", 2 );
append( sb, "Set this to \'true\' to cause a failure if there are no tests to run.", 3 );
append( sb, "", 0 );
append( sb, "forkedProcessTimeoutInSeconds", 2 );
append( sb, "Kill the forked test process after a certain number of seconds. If set to 0, wait forever for the process, never timing out.", 3 );
append( sb, "", 0 );
append( sb, "forkMode (Default: once)", 2 );
append( sb, "Option to specify the forking mode. Can be \'never\', \'once\' or \'always\'. \'none\' and \'pertest\' are also accepted for backwards compatibility.", 3 );
append( sb, "", 0 );
append( sb, "groups", 2 );
append( sb, "(TestNG only) Groups for this test. Only classes/methods/etc decorated with one of the groups specified here will be included in test run, if specified. This parameter is overridden if suiteXmlFiles are specified.", 3 );
append( sb, "", 0 );
append( sb, "includes", 2 );
append( sb, "List of patterns (separated by commas) used to specify the tests that should be included in testing. When not specified and when the test parameter is not specified, the default includes will be **/Test*.java **/*Test.java **/*TestCase.java. This parameter is ignored if TestNG suiteXmlFiles are specified.", 3 );
append( sb, "", 0 );
append( sb, "junitArtifactName (Default: junit:junit)", 2 );
append( sb, "Allows you to specify the name of the JUnit artifact. If not set, junit:junit will be used.", 3 );
append( sb, "", 0 );
append( sb, "jvm", 2 );
append( sb, "Option to specify the jvm (or path to the java executable) to use with the forking options. For the default, the jvm will be the same as the one used to run Maven.", 3 );
append( sb, "", 0 );
append( sb, "logConfiguration", 2 );
append( sb, "The JBoss logging configuration if any. This must be set if the target project uses jboss logging and you want any output to be displayed", 3 );
append( sb, "", 0 );
append( sb, "logModule", 2 );
append( sb, "The name of the -logmodule parameter passes in to JBoss Modules (i.e. the name of the module containg the jboss logmanager). This is needed if the target project uses java.util.Logging or jboss logging, and the jboss log manager is not on the system classpath.", 3 );
append( sb, "", 0 );
append( sb, "moduleDefinitionFile (Default: ${project.build.testOutputDirectory}/modules/module-def.xml)", 2 );
append( sb, "The path of the module definition file.", 3 );
append( sb, "", 0 );
append( sb, "modulesDirectory (Default: ${project.build.directory}/modules)", 2 );
append( sb, "The absolute path of the modules output directory created from moduleDefinitionFile.", 3 );
append( sb, "", 0 );
append( sb, "objectFactory", 2 );
append( sb, "(TestNG only) Define the factory class used to create all test instances", 3 );
append( sb, "", 0 );
append( sb, "parallel", 2 );
append( sb, "(TestNG only) When you use the parallel attribute, TestNG will try to run all your test methods in separate threads, except for methods that depend on each other, which will be run in the same thread in order to respect their order of execution.\n(JUnit 4.7 provider) Supports values classes\nmethods/both to run in separate threads, as controlled by threadCount.", 3 );
append( sb, "", 0 );
append( sb, "parallelMavenExecution (Default: ${session.parallel})", 2 );
append( sb, "(no description available)", 3 );
append( sb, "", 0 );
append( sb, "perCoreThreadCount", 2 );
append( sb, "(JUnit 4.7 provider) Indicates that threadCount is per cpu core. Defaults to true", 3 );
append( sb, "", 0 );
append( sb, "printSummary (Default: true)", 2 );
append( sb, "Option to print summary of test suites or just print the test cases that has errors.", 3 );
append( sb, "", 0 );
append( sb, "properties", 2 );
append( sb, "List of properties for configuring all TestNG related configurations. This is the new preferred method of configuring TestNG.", 3 );
append( sb, "", 0 );
append( sb, "redirectTestOutputToFile (Default: false)", 2 );
append( sb, "When forking, set this to true to redirect the unit test standard output to a file (found in reportsDirectory/testName-output.txt).", 3 );
append( sb, "", 0 );
append( sb, "remoteRepositories", 2 );
append( sb, "The plugin remote repositories declared in the POM.", 3 );
append( sb, "", 0 );
append( sb, "reportFormat (Default: brief)", 2 );
append( sb, "Selects the formatting for the test report to be generated. Can be set as brief or plain.", 3 );
append( sb, "", 0 );
append( sb, "reportsDirectory (Default: ${project.build.directory}/surefire-reports)", 2 );
append( sb, "Base directory where all reports are written to.", 3 );
append( sb, "", 0 );
append( sb, "roots", 2 );
append( sb, "The existing module root directories", 3 );
append( sb, "", 0 );
append( sb, "skip (Default: false)", 2 );
append( sb, "Set this to \'true\' to bypass unit tests entirely. Its use is NOT RECOMMENDED, especially if you enable it using the \'maven.test.skip\' property, because maven.test.skip disables both running the tests and compiling the tests. Consider using the skipTests parameter instead.", 3 );
append( sb, "", 0 );
append( sb, "skipExec", 2 );
append( sb, "Deprecated. Use -DskipTests instead.", 3 );
append( sb, "", 0 );
append( sb, "This old parameter is just like skipTests, but bound to the old property maven.test.skip.exec.", 3 );
append( sb, "", 0 );
append( sb, "skipTests (Default: false)", 2 );
append( sb, "Set this to \'true\' to skip running tests, but still compile them. Its use is NOT RECOMMENDED, but quite convenient on occasion.", 3 );
append( sb, "", 0 );
append( sb, "suiteXmlFiles", 2 );
append( sb, "(TestNG only) List of TestNG suite xml file locations, seperated by commas. Note that suiteXmlFiles is incompatible with several other parameters on this plugin, like includes/excludes. This parameter is ignored if the \'test\' parameter is specified (allowing you to run a single test instead of an entire suite).", 3 );
append( sb, "", 0 );
append( sb, "systemProperties", 2 );
append( sb, "Deprecated. Use systemPropertyVariables instead.", 3 );
append( sb, "", 0 );
append( sb, "List of System properties to pass to the JUnit tests.", 3 );
append( sb, "", 0 );
append( sb, "systemPropertyVariables", 2 );
append( sb, "List of System properties to pass to the JUnit tests.", 3 );
append( sb, "", 0 );
append( sb, "test", 2 );
append( sb, "Specify this parameter to run individual tests by file name, overriding the includes/excludes parameters. Each pattern you specify here will be used to create an include pattern formatted like **/${test}.java, so you can just type \'-Dtest=MyTest\' to run a single test called \'foo/MyTest.java\'. This parameter will override the TestNG suiteXmlFiles parameter.", 3 );
append( sb, "", 0 );
append( sb, "testClassesDirectory (Default: ${project.build.testOutputDirectory})", 2 );
append( sb, "The directory containing generated test classes of the project being tested. This will be included at the beginning the test classpath.", 3 );
append( sb, "", 0 );
append( sb, "testFailureIgnore (Default: false)", 2 );
append( sb, "Set this to true to ignore a failure during testing. Its use is NOT RECOMMENDED, but quite convenient on occasion.", 3 );
append( sb, "", 0 );
append( sb, "testNGArtifactName (Default: org.testng:testng)", 2 );
append( sb, "Allows you to specify the name of the TestNG artifact. If not set, org.testng:testng will be used.", 3 );
append( sb, "", 0 );
append( sb, "testSourceDirectory (Default: ${project.build.testSourceDirectory})", 2 );
append( sb, "The test source directory containing test class sources.", 3 );
append( sb, "", 0 );
append( sb, "threadCount", 2 );
append( sb, "(TestNG/JUnit 4.7 provider only) The attribute thread-count allows you to specify how many threads should be allocated for this execution. Only makes sense to use in conjunction with parallel.", 3 );
append( sb, "", 0 );
append( sb, "trimStackTrace (Default: true)", 2 );
append( sb, "Whether to trim the stack trace in the reports to just the lines within the test, or show the full trace.", 3 );
append( sb, "", 0 );
append( sb, "useFile (Default: true)", 2 );
append( sb, "Option to generate a file test report or just output the test report to the console.", 3 );
append( sb, "", 0 );
append( sb, "useManifestOnlyJar (Default: true)", 2 );
append( sb, "By default, Surefire forks your tests using a manifest-only JAR; set this parameter to \'false\' to force it to launch your tests with a plain old Java classpath. (See http://maven.apache.org/plugins/maven-surefire-plugin/examples/class-loading.html for a more detailed explanation of manifest-only JARs and their benefits.)\nBeware, setting this to \'false\' may cause your tests to fail on Windows if your classpath is too long.\n", 3 );
append( sb, "", 0 );
append( sb, "useSystemClassLoader", 2 );
append( sb, "Option to pass dependencies to the system\'s classloader instead of using an isolated class loader when forking. Prevents problems with JDKs which implement the service provider lookup mechanism by using the system\'s classloader. Default value is \'true\'.", 3 );
append( sb, "", 0 );
append( sb, "useUnlimitedThreads", 2 );
append( sb, "(JUnit 4.7 provider) Indicates that the thread pool will be unlimited. The parallel parameter and the actual number of classes/methods will decide. Setting this to true effectively disables perCoreThreadCount and threadCount.", 3 );
append( sb, "", 0 );
append( sb, "workingDirectory", 2 );
append( sb, "Command line working directory.", 3 );
append( sb, "", 0 );
}
}
if ( getLog().isInfoEnabled() )
{
getLog().info( sb.toString() );
}
}
/**
* Repeat a String n times to form a new string.
*
* @param str String to repeat
* @param repeat number of times to repeat str
* @return String with repeated String
* @throws NegativeArraySizeException if repeat < 0
* @throws NullPointerException if str is null
*/
private static String repeat( String str, int repeat )
{
StringBuffer buffer = new StringBuffer( repeat * str.length() );
for ( int i = 0; i < repeat; i++ )
{
buffer.append( str );
}
return buffer.toString();
}
/**
* Append a description to the buffer by respecting the indentSize and lineLength parameters.
* Note: The last character is always a new line.
*
* @param sb The buffer to append the description, not null.
* @param description The description, not null.
* @param indent The base indentation level of each line, must not be negative.
*/
private void append( StringBuffer sb, String description, int indent )
{
for ( Iterator it = toLines( description, indent, indentSize, lineLength ).iterator(); it.hasNext(); )
{
sb.append( it.next().toString() ).append( '\n' );
}
}
/**
* Splits the specified text into lines of convenient display length.
*
* @param text The text to split into lines, must not be null.
* @param indent The base indentation level of each line, must not be negative.
* @param indentSize The size of each indentation, must not be negative.
* @param lineLength The length of the line, must not be negative.
* @return The sequence of display lines, never null.
* @throws NegativeArraySizeException if indent < 0
*/
private static List toLines( String text, int indent, int indentSize, int lineLength )
{
List lines = new ArrayList();
String ind = repeat( "\t", indent );
String[] plainLines = text.split( "(\r\n)|(\r)|(\n)" );
for ( int i = 0; i < plainLines.length; i++ )
{
toLines( lines, ind + plainLines[i], indentSize, lineLength );
}
return lines;
}
/**
* Adds the specified line to the output sequence, performing line wrapping if necessary.
*
* @param lines The sequence of display lines, must not be null.
* @param line The line to add, must not be null.
* @param indentSize The size of each indentation, must not be negative.
* @param lineLength The length of the line, must not be negative.
*/
private static void toLines( List lines, String line, int indentSize, int lineLength )
{
int lineIndent = getIndentLevel( line );
StringBuffer buf = new StringBuffer( 256 );
String[] tokens = line.split( " +" );
for ( int i = 0; i < tokens.length; i++ )
{
String token = tokens[i];
if ( i > 0 )
{
if ( buf.length() + token.length() >= lineLength )
{
lines.add( buf.toString() );
buf.setLength( 0 );
buf.append( repeat( " ", lineIndent * indentSize ) );
}
else
{
buf.append( ' ' );
}
}
for ( int j = 0; j < token.length(); j++ )
{
char c = token.charAt( j );
if ( c == '\t' )
{
buf.append( repeat( " ", indentSize - buf.length() % indentSize ) );
}
else if ( c == '\u00A0' )
{
buf.append( ' ' );
}
else
{
buf.append( c );
}
}
}
lines.add( buf.toString() );
}
/**
* Gets the indentation level of the specified line.
*
* @param line The line whose indentation level should be retrieved, must not be null.
* @return The indentation level of the line.
*/
private static int getIndentLevel( String line )
{
int level = 0;
for ( int i = 0; i < line.length() && line.charAt( i ) == '\t'; i++ )
{
level++;
}
for ( int i = level + 1; i <= level + 4 && i < line.length(); i++ )
{
if ( line.charAt( i ) == '\t' )
{
level++;
break;
}
}
return level;
}
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy