svn commit: r1704509 - /sling/site/trunk/content/documentation/bundles/org-apache-sling-junit-bundles.mdtext

[bd...@apache.org]

Author: bdelacretaz
Date: Tue Sep 22 10:07:27 2015
New Revision: 1704509

URL: http://svn.apache.org/viewvc?rev=1704509&view=rev
Log:
Tweak JUnit server-side docs

Modified:
    sling/site/trunk/content/documentation/bundles/org-apache-sling-junit-bundles.mdtext

Modified: sling/site/trunk/content/documentation/bundles/org-apache-sling-junit-bundles.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/org-apache-sling-junit-bundles.mdtext?rev=1704509&r1=1704508&r2=1704509&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles/org-apache-sling-junit-bundles.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles/org-apache-sling-junit-bundles.mdtext Tue Sep 22 10:07:27 2015
@@ -5,12 +5,6 @@ This is an overview of the Sling bundles
 ## org.apache.sling.junit.core: server-side JUnit tests support
 This bundle provides a `JUnitServlet` that runs JUnit tests found in bundles. 
 
-To make tests available to that servlet, the bundle that contains them must point to them
-with a `Sling-Test-Regexp` bundle header that defines a regular expression that matches
-the test class names, like for example:
-
-    Sling-Test-Regexp=com.example.*ServerSideTest
-
 <div class="warning">
 Note that the JUnitServlet does not require authentication, so it would allow any client to run tests. The servlet can be disabled by configuration if needed, but in general the `/system` path should not be accessible to website visitors anyway.
 </div>
@@ -19,9 +13,19 @@ Note that the JUnitServlet does not requ
 For tighter integration with Sling, the alternate `SlingJUnitServlet` is registered with the `sling/junit/testing` resource type and `.junit` selector, if the bundle is running in a Sling system. Using this servlet instead of the plain JUnitServlet also allows Sling authentication to be used for running the tests, and the standard Sling request processing is used, including servlet filters for example.
 </div>
 
-The `TeleporterRule` supplied by this bundle makes it easy to write such tests, using this
-rule they can be mixed with other tests in the source code if that's convenient. Here's a basic example of such a
-"teleported" test that accesses OSGi services:
+To make tests available to that servlet, the bundle that contains them must point to them
+with a `Sling-Test-Regexp` bundle header that defines a regular expression that matches
+the test class names, like for example:
+
+    Sling-Test-Regexp=com.example.*ServerSideTest
+
+The `TeleporterRule` supplied by this bundle makes it easy to write such tests, as it takes care of
+all the mechanics of creating the test bundle, adding the above header, installing it etc.
+
+Using this rule the server-side tests can be mixed with other tests in the source code if that's convenient, it just
+requires the `junit.core`and `junit.teleporter` modules described on this page to create such tests. 
+
+Here's a basic example of a server-side test that accesses OSGi services:
 
     public class BasicTeleporterTest {
 
@@ -39,7 +43,9 @@ rule they can be mixed with other tests
             assertNotNull("Expecting to get a Configuration", cfg);
             assertEquals("Expecting the correct pid", pid, cfg.getPid());
         }
-    } 
+    }
+    
+That's all there is to it, the `TeleporterRule` takes care of the rest.     
 
 Using the teleporter module described below, the `TeleporterRule` creates a temporary bundle 
 that contains the test class along with any classes required to run it, adds the appropriate 
@@ -53,6 +59,11 @@ for examples or look at the
 [`integrationtest.teleporter`]( https://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/teleporter)
 package. 
 
+As I write this the teleporter mechanism is quite new, I suspect there might be some weird interactions 
+between things like `@AfterClass`, custom test runners and this mechanism but it works well to a growing
+number of tests in our `launchpad/integration-tests` module. Moving to JUnit `Rules` as much as possible, 
+and combining them using JUnit's `RuleChain`, should help work around such limitations if they arise.
+
 ### More details on the JUnitServlet
 To try the JUnitServlet interactively, you can install the 
 [org.apache.sling.testing.samples.sampletests](http://svn.apache.org/repos/asf/sling/trunk/testing/samples/sample-tests)