------
  Debugging Tests
  ------
  Dan Fabulich
  ------
  2010-01-09
  ------
  
 ~~ 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

Debugging Tests

  Sometimes you need to debug the tests exactly as Maven ran them.  Here's how!

Forked Tests

  By default, Maven runs your tests in a separate ("forked") process.  You can use the <<<maven.${thisPlugin.toLowerCase()}.debug>>> property
  to debug your forked tests remotely, like this:

#{if}(${project.artifactId}=="maven-surefire-plugin")
+---+
mvn -Dmaven.${thisPlugin.toLowerCase()}.debug test
+---+
#{else}
+---+
mvn -Dmaven.${thisPlugin.toLowerCase()}.debug verify
+---+
#{end}

  The tests will automatically pause and await a remote debugger on port 5005.  You can then attach to the running tests
  using Eclipse.  You can setup a "Remote Java Application" launch configuration via the menu
  command "Run" > "Open Debug Dialog..."

  If you need to configure a different port, you may pass a more detailed value.  For example, the command below will use port 8000
  instead of port 5005.

#{if}(${project.artifactId}=="maven-surefire-plugin")
+---+
mvn -Dmaven.surefire.debug="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000 -Xnoagent -Djava.compiler=NONE" test
+---+
#{else}
+---+
mvn -Dmaven.surefire.debug="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000 -Xnoagent -Djava.compiler=NONE" verify
+---+
#{end}

Non-forked Tests

  You can force Maven not to fork tests by configuring the <<<forkMode>>> configuration parameter.

#{if}(${project.artifactId}=="maven-surefire-plugin")
+---+
mvn -DforkMode=never test
+---+
#{else}
+---+
mvn -DforkMode=never verify
+---+
#{end}

  Then all you need to do is debug Maven itself.  Since Maven 2.0.8, Maven has shipped with a "mvnDebug" shell script that you can
  use to launch Maven with convenient debugging options:

#{if}(${project.artifactId}=="maven-surefire-plugin")
+---+
mvnDebug -DforkMode=never test
+---+
#{else}
+---+
mvnDebug -DforkMode=never verify
+---+
#{end}

  Then you can attach Eclipse to Maven itself, which may be easier/more convenient than debugging the forked executable.