Developer Center
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/maven-failsafe-plugin. 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:
svn co https://svn.apache.org/repos/asf/maven/surefire/trunk/surefire-integration-tests/src/test/resources/failsafe-buildfail cd failsafe-buildfail 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:
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.
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.
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.
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:
AbstractSurefireMojo#executeAllProviders ForkStarter#fork 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.
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.
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.
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.