Author: kwin
Date: Fri Jun 12 07:15:19 2015
New Revision: 1685039
URL: http://svn.apache.org/r1685039
Log:
fix list and add information about debugging ITs
Modified:
sling/site/trunk/content/documentation/development/sling-testing-tools.mdtext
Modified:
sling/site/trunk/content/documentation/development/sling-testing-tools.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/development/sling-testing-tools.mdtext?rev=1685039&r1=1685038&r2=1685039&view=diff
==============================================================================
---
sling/site/trunk/content/documentation/development/sling-testing-tools.mdtext
(original)
+++
sling/site/trunk/content/documentation/development/sling-testing-tools.mdtext
Fri Jun 12 07:15:19 2015
@@ -108,11 +108,12 @@ Besides serving as examples, some of the
The sample uses the
[testing/tools](http://svn.apache.org/repos/asf/sling/trunk/testing/tools) to
make the test code simpler. See the
[OsgiConsoleTest|https://svn.apache.org/repos/asf/sling/trunk/testing/samples/integration-tests/src/test/java/org/apache/sling/testing/samples/integrationtests/http/OsgiConsoleTest.java]
class for an example of a test that's very readable and requires no test setup
or boilerplate code.
The following steps are executed in the `integration-test` phase of this
module's Maven build:
+
1. A random port number for the Sling server is selected by the Maven build
helper plugin, unless explicitely set (see pom.xml for such options).
1. Additional bundles, defined in the module's pom, are downloaded from the
Maven repository in the `target/sling/additional-bundles` folder.
1. The first test that inherits from the
[SlingTestBase](https://svn.apache.org/repos/asf/sling/trunk/testing/tools/src/main/java/org/apache/sling/testing/tools/sling/SlingTestBase.java)
class causes the Sling runnable jar (defined as a dependency in the module's
pom) to be started.
-1. # The `SlingTestBase` class waits for the Sling server to be ready, based
on URLs and expected responses defined in the pom.
-1. # The `SlingTestBase` class installs and starts the bundles found in the
`target/sling/additional-bundles` folder.
+1. The `SlingTestBase` class waits for the Sling server to be ready, based on
URLs and expected responses defined in the pom.
+1. The `SlingTestBase` class installs and starts the bundles found in the
`target/sling/additional-bundles` folder.
1. The test can now either test Sling directly via its http interface, or use
the JUnitServlet to execute server-side tests contributed by bundles or
scripts, as described above.
1. The Sling runnable jar is stopped when the test VM exits.
1. The test results are reported via the usual Maven mechanisms.
@@ -135,3 +136,12 @@ for an example of how to do that.
The
[SlingRemoteExecutionRule](http://svn.apache.org/repos/asf/sling/trunk/testing/junit/remote/src/main/java/org/apache/sling/junit/remote/ide/SlingRemoteExecutionRule.java)
is a JUnit Rule that allows tests to be executed remotely in a Sling instance
from an IDE, assuming the test is available on both sides.
The
[ExampleRemoteTest](https://svn.apache.org/repos/asf/sling/trunk/testing/junit/remote/src/main/java/org/apache/sling/junit/remote/exported/ExampleRemoteTest.java)
class demonstrates this. To run it from your IDE, set the
`sling.remote.test.url` in the IDE to the URL of the JUnitServlet, like
http://localhost:8080/system/sling/junit for example.
+
+# Debugging ITs
+The JVM is usually forked twice during the execution of integration tests. The
first time by the `maven-surefire-plugin` which executes the client-side (i.e.
Maven-side) part of the tests. To debug this side the option
`-Dmaven.surefire.debug` can be used which waits for a debugger to be attached
on port 5005 before the (client-side) test is executed. More information is
available in the [documentation of the
maven-surefire-plugin](http://maven.apache.org/surefire/maven-surefire-plugin/examples/debugging.html).
+
+Then the `JarExecutor` is forking the VM a second time to start the server
(this does not happen if connecting to an already running instance). The system
environment variable `jar.executor.vm.options` can be used to start that VM
with debug options. All debug options are described at the [JPDA
documentation](http://docs.oracle.com/javase/7/docs/technotes/guides/jpda/conninv.html#Invocation).
If running
+
+ mvn test
-Djar.executor.vm.options="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=8000"
+
+the server start is interrupted until a debugger is connected on port 8000.
