How To Read A Maven Plugin Documentation

I recently came along a tutorial that describes "How to skip Maven unit test example". The author certainly had the best intentions - but finally he messed things up. This would not have happend if he had a look at the plugin documentation. If you once understand how to read it - plugin usage will be simple.

The best thing about a Maven plugin documentation is that there is a Plugin Documentation Standard. Nearly all plugins I use follow this standard. So does the Maven Surefire Plugin that is handled in the tutorial mentioned above. Lets have a look at the documentation:

The first thing I always ask myself when using a plugin is: What's the current version of the plugin? This question can easily be answered by looking at the upper right corner of a plugin documentation page.

There, the current version is mentioned as also in each example that is provided in the documentation.

A maven plugin has (several) goals. A goal is a specific task of the plugin. The goals are listed on the plugin documentation page (Goals Overview). Each goal has its own documentation with the list of configuration parameters. The 'test' goal of the surefire plugin e.g. supports the 'skipTests' parameter. This will skip running the test but still compile them.

 If you want to set this Parameter in the plugin section of the pom.xml you have to add it as an <configuration> element (full example):

<configuration>
    <skipTests>true</skipTests>
</configuration>

But you can also use the User Property of this parameter to set the configuration on the command line while executing the maven build (parameter name and user property are the same here).

mvn -DskipTests=true clean install

A similar parameter would be the 'skip' parameter.

Using this as a parameter in the pom.xml also bypasses the test execution but in addition to that the corresponding user property 'maven.test.skip' would also disable the compiling of the test classes (so you would be able to build your project even if the test classes would not compile). I find it somehow confusing that the pom.xml configuration parameter causes a different behaviour than the user property but at least it is clearly documented.

Back to the tutorial mentioned above. It messes up different configuration settings (skipTests / maven.test.skip) and gives the impression that only the pom.xml configuration affects the surefire plugin execution. But as we know now skipTests and maven.test.skip have a different impact on the build but are both related to the surefire plugin configuration.

Conclusion: Knowing about the current plugin version, its goals and configuration parameters (and the corresponding user properties) should make it easy to use a Maven Plugin. You can even find much more useful information on a plugin documentation page that I did not handle here - especially the Usage and Examples sections.

So my advice for the future: RT(F)M and have fun using maven plugins

Recommended further reading:

• Maven - Guide to the Plugin Documentation Standard
• Maven - Guide to Configuring Plug-ins
• Maven - Guide to Developing Java Plugins