------
  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:

* 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.

* 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.

* 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