1 package org.apache.maven.plugin.failsafe;
2
3 import java.util.ArrayList;
4 import java.util.Iterator;
5 import java.util.List;
6
7 import org.apache.maven.plugin.AbstractMojo;
8 import org.apache.maven.plugin.MojoExecutionException;
9
10
11
12
13
14
15
16
17
18 public class HelpMojo
19 extends AbstractMojo
20 {
21
22
23
24
25
26 private boolean detail;
27
28
29
30
31
32
33 private java.lang.String goal;
34
35
36
37
38
39
40 private int lineLength;
41
42
43
44
45
46
47 private int indentSize;
48
49
50
51 public void execute()
52 throws MojoExecutionException
53 {
54 if ( lineLength <= 0 )
55 {
56 getLog().warn( "The parameter 'lineLength' should be positive, using '80' as default." );
57 lineLength = 80;
58 }
59 if ( indentSize <= 0 )
60 {
61 getLog().warn( "The parameter 'indentSize' should be positive, using '2' as default." );
62 indentSize = 2;
63 }
64
65 StringBuffer sb = new StringBuffer();
66
67 append( sb, "org.apache.maven.plugins:maven-failsafe-plugin:2.7", 0 );
68 append( sb, "", 0 );
69
70 append( sb, "Maven Failsafe Plugin", 0 );
71 append( sb, "Surefire is a test framework project.", 1 );
72 append( sb, "", 0 );
73
74 if ( goal == null || goal.length() <= 0 )
75 {
76 append( sb, "This plugin has 3 goals:", 0 );
77 append( sb, "", 0 );
78 }
79
80 if ( goal == null || goal.length() <= 0 || "help".equals( goal ) )
81 {
82 append( sb, "failsafe:help", 0 );
83 append( sb, "Display help information on maven-failsafe-plugin.\nCall\n\u00a0\u00a0mvn\u00a0failsafe:help\u00a0-Ddetail=true\u00a0-Dgoal=<goal-name>\nto display parameter details.", 1 );
84 append( sb, "", 0 );
85 if ( detail )
86 {
87 append( sb, "Available parameters:", 1 );
88 append( sb, "", 0 );
89
90 append( sb, "detail (Default: false)", 2 );
91 append( sb, "If true, display all settable properties for each goal.", 3 );
92 append( sb, "", 0 );
93
94 append( sb, "goal", 2 );
95 append( sb, "The name of the goal for which to show help. If unspecified, all goals will be displayed.", 3 );
96 append( sb, "", 0 );
97
98 append( sb, "indentSize (Default: 2)", 2 );
99 append( sb, "The number of spaces per indentation level, should be positive.", 3 );
100 append( sb, "", 0 );
101
102 append( sb, "lineLength (Default: 80)", 2 );
103 append( sb, "The maximum length of a display line, should be positive.", 3 );
104 append( sb, "", 0 );
105 }
106 }
107
108 if ( goal == null || goal.length() <= 0 || "integration-test".equals( goal ) )
109 {
110 append( sb, "failsafe:integration-test", 0 );
111 append( sb, "Run integration tests using Surefire.", 1 );
112 append( sb, "", 0 );
113 if ( detail )
114 {
115 append( sb, "Available parameters:", 1 );
116 append( sb, "", 0 );
117
118 append( sb, "additionalClasspathElements", 2 );
119 append( sb, "Additional elements to be appended to the classpath.", 3 );
120 append( sb, "", 0 );
121
122 append( sb, "argLine", 2 );
123 append( sb, "Arbitrary JVM options to set on the command line.", 3 );
124 append( sb, "", 0 );
125
126 append( sb, "basedir (Default: ${basedir})", 2 );
127 append( sb, "The base directory of the project being tested. This can be obtained in your unit test by System.getProperty(\'basedir\').", 3 );
128 append( sb, "", 0 );
129
130 append( sb, "childDelegation (Default: false)", 2 );
131 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 );
132 append( sb, "", 0 );
133
134 append( sb, "classesDirectory (Default: ${project.build.outputDirectory})", 2 );
135 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 );
136 append( sb, "", 0 );
137
138 append( sb, "classpathDependencyExcludes", 2 );
139 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 );
140 append( sb, "", 0 );
141
142 append( sb, "classpathDependencyScopeExclude", 2 );
143 append( sb, "A dependency scope to exclude from the test classpath The scope should be one of the scopes defined by org.apache.maven.artifact.Artifact. This includes the following\n>\n\n-\tcompile - system, provided, compile\n-\truntime - compile, runtime\n-\tcompile+runtime - system, provided, compile, runtime\n-\truntime+system - system, compile, runtime\n-\ttest - system, provided, compile, runtime, test\n", 3 );
144 append( sb, "", 0 );
145
146 append( sb, "debugForkedProcess", 2 );
147 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 );
148 append( sb, "", 0 );
149
150 append( sb, "disableXmlReport (Default: false)", 2 );
151 append( sb, "Flag to disable the generation of report files in xml format.", 3 );
152 append( sb, "", 0 );
153
154 append( sb, "enableAssertions (Default: true)", 2 );
155 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 );
156 append( sb, "", 0 );
157
158 append( sb, "encoding (Default: ${project.reporting.outputEncoding})", 2 );
159 append( sb, "The character encoding scheme to be applied.", 3 );
160 append( sb, "", 0 );
161
162 append( sb, "environmentVariables", 2 );
163 append( sb, "Additional environments to set on the command line.", 3 );
164 append( sb, "", 0 );
165
166 append( sb, "excludedGroups", 2 );
167 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 );
168 append( sb, "", 0 );
169
170 append( sb, "excludes", 2 );
171 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 );
172 append( sb, "", 0 );
173
174 append( sb, "failIfNoTests", 2 );
175 append( sb, "Set this to \'true\' to cause a failure if there are no tests to run. Defaults to false.", 3 );
176 append( sb, "", 0 );
177
178 append( sb, "forkedProcessTimeoutInSeconds", 2 );
179 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 );
180 append( sb, "", 0 );
181
182 append( sb, "forkMode (Default: once)", 2 );
183 append( sb, "Option to specify the forking mode. Can be \'never\', \'once\' or \'always\'. \'none\' and \'pertest\' are also accepted for backwards compatibility.", 3 );
184 append( sb, "", 0 );
185
186 append( sb, "groups", 2 );
187 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 );
188 append( sb, "", 0 );
189
190 append( sb, "includes", 2 );
191 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 **/IT*.java **/*IT.java **/*ITCase.java. This parameter is ignored if TestNG suiteXmlFiles are specified.", 3 );
192 append( sb, "", 0 );
193
194 append( sb, "junitArtifactName (Default: junit:junit)", 2 );
195 append( sb, "Allows you to specify the name of the JUnit artifact. If not set, junit:junit will be used.", 3 );
196 append( sb, "", 0 );
197
198 append( sb, "jvm", 2 );
199 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 a new instance of the same VM as the one used to run Maven. JVM settings are not inherited from MAVEN_OPTS", 3 );
200 append( sb, "", 0 );
201
202 append( sb, "objectFactory", 2 );
203 append( sb, "(TestNG only) Define the factory class used to create all test instances", 3 );
204 append( sb, "", 0 );
205
206 append( sb, "parallel", 2 );
207 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 );
208 append( sb, "", 0 );
209
210 append( sb, "perCoreThreadCount", 2 );
211 append( sb, "(JUnit 4.7 provider) Indicates that threadCount is per cpu core. Defaults to true", 3 );
212 append( sb, "", 0 );
213
214 append( sb, "printSummary (Default: true)", 2 );
215 append( sb, "Option to print summary of test suites or just print the test cases that has errors.", 3 );
216 append( sb, "", 0 );
217
218 append( sb, "properties", 2 );
219 append( sb, "List of properties for configuring all TestNG related configurations. This is the new preferred method of configuring TestNG.", 3 );
220 append( sb, "", 0 );
221
222 append( sb, "redirectTestOutputToFile (Default: false)", 2 );
223 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 );
224 append( sb, "", 0 );
225
226 append( sb, "remoteRepositories", 2 );
227 append( sb, "The plugin remote repositories declared in the POM.", 3 );
228 append( sb, "", 0 );
229
230 append( sb, "reportFormat (Default: brief)", 2 );
231 append( sb, "Selects the formatting for the test report to be generated. Can be set as brief or plain.", 3 );
232 append( sb, "", 0 );
233
234 append( sb, "reportsDirectory (Default: ${project.build.directory}/failsafe-reports)", 2 );
235 append( sb, "Base directory where all reports are written to.", 3 );
236 append( sb, "", 0 );
237
238 append( sb, "runOrder", 2 );
239 append( sb, "Defines the order the tests will be run in. Supported values are alphabetical, reversealphabetical random, hourly (alphabetical on even hours, reverse alphabetical on odd hours) and filesystem.\n>Not supplying a value for this setting will run tests in filesystem order.\n\n>Odd\nEven for hourly is determined at the time the of scanning the classpath, meaning it could change during a multi-module build.", 3 );
240 append( sb, "", 0 );
241
242 append( sb, "skip (Default: false)", 2 );
243 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 );
244 append( sb, "", 0 );
245
246 append( sb, "skipExec", 2 );
247 append( sb, "Deprecated. Use -DskipTests instead.", 3 );
248 append( sb, "", 0 );
249 append( sb, "This old parameter is just like skipTests, but bound to the old property maven.test.skip.exec.", 3 );
250 append( sb, "", 0 );
251
252 append( sb, "skipITs", 2 );
253 append( sb, "Set this to \'true\' to skip running integration tests, but still compile them. Its use is NOT RECOMMENDED, but quite convenient on occasion.", 3 );
254 append( sb, "", 0 );
255
256 append( sb, "skipTests (Default: false)", 2 );
257 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 );
258 append( sb, "", 0 );
259
260 append( sb, "suiteXmlFiles", 2 );
261 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 );
262 append( sb, "", 0 );
263
264 append( sb, "summaryFile", 2 );
265 append( sb, "The summary file to write integration test results to.", 3 );
266 append( sb, "", 0 );
267
268 append( sb, "systemProperties", 2 );
269 append( sb, "Deprecated. Use systemPropertyVariables instead.", 3 );
270 append( sb, "", 0 );
271 append( sb, "List of System properties to pass to the JUnit tests.", 3 );
272 append( sb, "", 0 );
273
274 append( sb, "systemPropertyVariables", 2 );
275 append( sb, "List of System properties to pass to the JUnit tests.", 3 );
276 append( sb, "", 0 );
277
278 append( sb, "test", 2 );
279 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 );
280 append( sb, "", 0 );
281
282 append( sb, "testClassesDirectory (Default: ${project.build.testOutputDirectory})", 2 );
283 append( sb, "The directory containing generated test classes of the project being tested. This will be included at the beginning the test classpath.", 3 );
284 append( sb, "", 0 );
285
286 append( sb, "testNGArtifactName (Default: org.testng:testng)", 2 );
287 append( sb, "Allows you to specify the name of the TestNG artifact. If not set, org.testng:testng will be used.", 3 );
288 append( sb, "", 0 );
289
290 append( sb, "testSourceDirectory (Default: ${project.build.testSourceDirectory})", 2 );
291 append( sb, "The test source directory containing test class sources.", 3 );
292 append( sb, "", 0 );
293
294 append( sb, "threadCount", 2 );
295 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 );
296 append( sb, "", 0 );
297
298 append( sb, "trimStackTrace (Default: true)", 2 );
299 append( sb, "Whether to trim the stack trace in the reports to just the lines within the test, or show the full trace.", 3 );
300 append( sb, "", 0 );
301
302 append( sb, "useFile (Default: true)", 2 );
303 append( sb, "Option to generate a file test report or just output the test report to the console.", 3 );
304 append( sb, "", 0 );
305
306 append( sb, "useManifestOnlyJar (Default: true)", 2 );
307 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.)\n>Beware, setting this to \'false\' may cause your tests to fail on Windows if your classpath is too long.\n", 3 );
308 append( sb, "", 0 );
309
310 append( sb, "useSystemClassLoader", 2 );
311 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 );
312 append( sb, "", 0 );
313
314 append( sb, "useUnlimitedThreads", 2 );
315 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 );
316 append( sb, "", 0 );
317
318 append( sb, "workingDirectory", 2 );
319 append( sb, "Command line working directory.", 3 );
320 append( sb, "", 0 );
321 }
322 }
323
324 if ( goal == null || goal.length() <= 0 || "verify".equals( goal ) )
325 {
326 append( sb, "failsafe:verify", 0 );
327 append( sb, "Verify integration tests ran using Surefire.", 1 );
328 append( sb, "", 0 );
329 if ( detail )
330 {
331 append( sb, "Available parameters:", 1 );
332 append( sb, "", 0 );
333
334 append( sb, "basedir (Default: ${basedir})", 2 );
335 append( sb, "The base directory of the project being tested. This can be obtained in your unit test by System.getProperty(\'basedir\').", 3 );
336 append( sb, "", 0 );
337
338 append( sb, "encoding (Default: ${project.reporting.outputEncoding})", 2 );
339 append( sb, "The character encoding scheme to be applied.", 3 );
340 append( sb, "", 0 );
341
342 append( sb, "failIfNoTests", 2 );
343 append( sb, "Set this to \'true\' to cause a failure if there are no tests to run.", 3 );
344 append( sb, "", 0 );
345
346 append( sb, "reportsDirectory (Default: ${project.build.directory}/failsafe-reports)", 2 );
347 append( sb, "Base directory where all reports are written to.", 3 );
348 append( sb, "", 0 );
349
350 append( sb, "skip (Default: false)", 2 );
351 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 );
352 append( sb, "", 0 );
353
354 append( sb, "skipExec", 2 );
355 append( sb, "Deprecated. Use -DskipTests instead.", 3 );
356 append( sb, "", 0 );
357 append( sb, "This old parameter is just like skipTests, but bound to the old property maven.test.skip.exec.", 3 );
358 append( sb, "", 0 );
359
360 append( sb, "skipITs", 2 );
361 append( sb, "Set this to \'true\' to skip running integration tests, but still compile them. Its use is NOT RECOMMENDED, but quite convenient on occasion.", 3 );
362 append( sb, "", 0 );
363
364 append( sb, "skipTests", 2 );
365 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 );
366 append( sb, "", 0 );
367
368 append( sb, "summaryFile", 2 );
369 append( sb, "The summary file to read integration test results from.", 3 );
370 append( sb, "", 0 );
371
372 append( sb, "summaryFiles", 2 );
373 append( sb, "Additional summary files to read integration test results from.", 3 );
374 append( sb, "", 0 );
375
376 append( sb, "testClassesDirectory (Default: ${project.build.testOutputDirectory})", 2 );
377 append( sb, "The directory containing generated test classes of the project being tested. This will be included at the beginning the test classpath.", 3 );
378 append( sb, "", 0 );
379
380 append( sb, "testFailureIgnore (Default: false)", 2 );
381 append( sb, "Set this to true to ignore a failure during testing. Its use is NOT RECOMMENDED, but quite convenient on occasion.", 3 );
382 append( sb, "", 0 );
383 }
384 }
385
386 if ( getLog().isInfoEnabled() )
387 {
388 getLog().info( sb.toString() );
389 }
390 }
391
392
393
394
395
396
397
398
399
400
401 private static String repeat( String str, int repeat )
402 {
403 StringBuffer buffer = new StringBuffer( repeat * str.length() );
404
405 for ( int i = 0; i < repeat; i++ )
406 {
407 buffer.append( str );
408 }
409
410 return buffer.toString();
411 }
412
413
414
415
416
417
418
419
420
421 private void append( StringBuffer sb, String description, int indent )
422 {
423 for ( Iterator it = toLines( description, indent, indentSize, lineLength ).iterator(); it.hasNext(); )
424 {
425 sb.append( it.next().toString() ).append( '\n' );
426 }
427 }
428
429
430
431
432
433
434
435
436
437
438
439 private static List toLines( String text, int indent, int indentSize, int lineLength )
440 {
441 List lines = new ArrayList();
442
443 String ind = repeat( "\t", indent );
444 String[] plainLines = text.split( "(\r\n)|(\r)|(\n)" );
445 for ( int i = 0; i < plainLines.length; i++ )
446 {
447 toLines( lines, ind + plainLines[i], indentSize, lineLength );
448 }
449
450 return lines;
451 }
452
453
454
455
456
457
458
459
460
461 private static void toLines( List lines, String line, int indentSize, int lineLength )
462 {
463 int lineIndent = getIndentLevel( line );
464 StringBuffer buf = new StringBuffer( 256 );
465 String[] tokens = line.split( " +" );
466 for ( int i = 0; i < tokens.length; i++ )
467 {
468 String token = tokens[i];
469 if ( i > 0 )
470 {
471 if ( buf.length() + token.length() >= lineLength )
472 {
473 lines.add( buf.toString() );
474 buf.setLength( 0 );
475 buf.append( repeat( " ", lineIndent * indentSize ) );
476 }
477 else
478 {
479 buf.append( ' ' );
480 }
481 }
482 for ( int j = 0; j < token.length(); j++ )
483 {
484 char c = token.charAt( j );
485 if ( c == '\t' )
486 {
487 buf.append( repeat( " ", indentSize - buf.length() % indentSize ) );
488 }
489 else if ( c == '\u00A0' )
490 {
491 buf.append( ' ' );
492 }
493 else
494 {
495 buf.append( c );
496 }
497 }
498 }
499 lines.add( buf.toString() );
500 }
501
502
503
504
505
506
507
508 private static int getIndentLevel( String line )
509 {
510 int level = 0;
511 for ( int i = 0; i < line.length() && line.charAt( i ) == '\t'; i++ )
512 {
513 level++;
514 }
515 for ( int i = level + 1; i <= level + 4 && i < line.length(); i++ )
516 {
517 if ( line.charAt( i ) == '\t' )
518 {
519 level++;
520 break;
521 }
522 }
523 return level;
524 }
525 }