You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by bu...@apache.org on 2016/09/23 08:11:21 UTC
svn commit: r998048 - in /websites/staging/sling/trunk/content: ./
documentation/bundles/org-apache-sling-junit-bundles.html
Author: buildbot
Date: Fri Sep 23 08:11:20 2016
New Revision: 998048
Log:
Staging update by buildbot for sling
Modified:
websites/staging/sling/trunk/content/ (props changed)
websites/staging/sling/trunk/content/documentation/bundles/org-apache-sling-junit-bundles.html
Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Fri Sep 23 08:11:20 2016
@@ -1 +1 @@
-1761922
+1762021
Modified: websites/staging/sling/trunk/content/documentation/bundles/org-apache-sling-junit-bundles.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/bundles/org-apache-sling-junit-bundles.html (original)
+++ websites/staging/sling/trunk/content/documentation/bundles/org-apache-sling-junit-bundles.html Fri Sep 23 08:11:20 2016
@@ -115,8 +115,8 @@ h2:hover > .headerlink, h3:hover > .head
}
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
<p>This is an overview of the Sling bundles that provide support for server-side JUnit tests. </p>
-<p>The <a href="https://svn.apache.org/repos/asf/sling/trunk/testing/samples/bundle-with-it"><code>bundle-with-it</code></a>
-module provides a complete example including HTTP-based and server-side teleported tests in a
+<p>The Maven modules below <a href="https://svn.apache.org/repos/asf/sling/trunk/testing/samples"><code>testing\samples</code></a>
+provide different examples including HTTP-based and server-side teleported tests in a
bundle module, running against a full Sling instance setup in the same Maven module.</p>
<h2 id="orgapacheslingjunitcore-server-side-junit-tests-support">org.apache.sling.junit.core: server-side JUnit tests support<a class="headerlink" href="#orgapacheslingjunitcore-server-side-junit-tests-support" title="Permanent link">¶</a></h2>
<p>This bundle provides a <code>JUnitServlet</code> that runs JUnit tests found in bundles. </p>
@@ -137,7 +137,15 @@ the test class names, like for example:<
<h3 id="the-teleporterrule">The TeleporterRule<a class="headerlink" href="#the-teleporterrule" title="Permanent link">¶</a></h3>
<p>The <code>TeleporterRule</code> supplied by this bundle (since V1.0.12) 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.</p>
+all the mechanics of </p>
+<ol>
+<li>creating the test bundle including all necessary classes for execution</li>
+<li>adding the <code>Sling-Test-Regexp</code> header to the bundles manifest</li>
+<li>deploy the bundle on an Sling server (with the help of the customizer)</li>
+<li>calling the <code>JUnitServlet</code> from the client-side and report back the results</li>
+<li>uninstalling the test bundle</li>
+</ol>
+<p>Most of these steps are done on the client-side by the org.apache.sling.junit.teleporter module (see below).</p>
<p>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 <code>junit.core</code> and <code>junit.teleporter</code> modules described on this page to create such tests. </p>
<p>Here's a basic example of a server-side test that accesses OSGi services:</p>
@@ -162,11 +170,8 @@ requires the <code>junit.core</code> and
<p>That's all there is to it, the <code>TeleporterRule</code> takes care of the rest. </p>
-<p>Using the teleporter module described below, the <code>TeleporterRule</code> creates a temporary bundle
-that contains the test class along with any classes required to run it, adds the appropriate
-<code>Sling-Test-Regexp</code> header to it, installs the bundle, runs the test via the <code>JUnitServlet</code>,
-collects the results and uninstalls the bundle. This happens quickly as the temporary bundle is
-very small, and both the client-side and server-side parts of the test can be debugged easily
+<p>The test bundle being build and deployed through this rule usually happens quickly as the temporary bundle is
+very small. Both the client-side and server-side parts of the test can be debugged easily
with the appropriate IDE settings.</p>
<p>The <code>Teleporter.getService</code> method takes an optional OSGi LDAP filter for service
selection, like for example:</p>
@@ -174,8 +179,9 @@ selection, like for example:</p>
</pre></div>
+<p>The method waits for the service to be available or until the timeout elapsed <a href="https://issues.apache.org/jira/browse/SLING-6031">SLING-6031</a>.</p>
<p>And starting with version 1.0.4 of the <code>org.apache.sling.junit.teleporter</code> bundle, you can specify
-resource to embed in the test bundle, as in this example:</p>
+resources to embed in the test bundle, as in this example:</p>
<div class="codehilite"><pre><span class="p">@</span><span class="n">Rule</span>
<span class="n">public</span> <span class="n">final</span> <span class="n">TeleporterRule</span> <span class="n">teleporter</span> <span class="p">=</span>
<span class="n">TeleporterRule</span><span class="p">.</span><span class="n">forClass</span><span class="p">(</span><span class="n">getClass</span><span class="p">(),</span> "<span class="n">Launchpad</span>"<span class="p">)</span>
@@ -206,22 +212,40 @@ you to execute them via a POST request.<
<code>/system/sling/junit/.json</code> for example.</p>
<h2 id="orgapacheslingjunitteleporter-client-side-teleporterrule-support">org.apache.sling.junit.teleporter: client-side TeleporterRule support<a class="headerlink" href="#orgapacheslingjunitteleporter-client-side-teleporterrule-support" title="Permanent link">¶</a></h2>
<p>This module provides the <code>ClientSideTeleporter</code> which the <code>TeleporterRule</code> uses to package the server-side tests
-in bundles that's installed temporarily on the test server. </p>
+in bundles that's installed temporarily on the test server. Almost all steps described above in <a href="#the-teleporterrule">The TeleporterRule</a> are being performed by this module.</p>
<p>This module is not a bundle, as it's used on the client only, as a dependency when running the tests.</p>
+<h3 id="teleporterrulecustomizer">TeleporterRule.Customizer<a class="headerlink" href="#teleporterrulecustomizer" title="Permanent link">¶</a></h3>
<p>A <code>TeleporterRule.Customizer</code> is used to setup the <code>ClientSideTeleporter</code>. That customizer is instantiated dynamically
-based on a String passed to the <code>TeleporterRule</code> creation code.</p>
-<p>As an example from our <code>launchpad/integration-tests</code> module, this call</p>
+based on a String passed to the <code>TeleporterRule.forClass</code> method as 2nd parameter. As an example from our <code>launchpad/integration-tests</code> module, this call</p>
<div class="codehilite"><pre><span class="n">TeleporterRule</span><span class="p">.</span><span class="n">forClass</span><span class="p">(</span><span class="n">getClass</span><span class="p">(),</span> "<span class="n">Launchpad</span><span class="p">:</span><span class="n">author</span>"<span class="p">);</span>
</pre></div>
-<p>Causes the <code>TeleporterRule</code> to use the <code>org.apache.sling.junit.teleporter.customizers.LaunchpadCustomizer</code> class
+<p>causes the <code>TeleporterRule</code> to use the <code>org.apache.sling.junit.teleporter.customizers.LaunchpadCustomizer</code> class
to setup the <code>ClientSideTeleporter</code>, and passes the "author" string to it as an option. Although our current <code>LaunchpadCustomizer</code>
does not use this options string, it is meant to select a specific server (of family of servers) to run the tests on.</p>
<p>The options string can also use a full class name instead of the <code>Launchpad</code> short form used here, if needed. The part
of that string that follows the first colon is passed to the customizer as is.</p>
<p>Using Strings for customization reduces the coupling with the <code>junit.core</code> bundle, as it does not need to know those
classes which are used only on the client side when running tests. </p>
+<p>If <code>TeleporterRule.forClass(getClass())</code> is used (the method without an additional 2nd parameter) the default customizer is used (<a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a>, since version 1.0.8). </p>
+<p>The following customizers are currently used in Sling</p>
+<ol>
+<li><em><a href="https://svn.apache.org/repos/asf/sling/trunk/testing/junit/teleporter/src/main/java/org/apache/sling/testing/teleporter/client/DefaultPropertyBasedCustomizer.java">Default Customizer</a></em> is used by default when no other customizer is referenced in <code>TeleporterRule.forClass(getClass())</code>. It relies on the following system properties:
+| Property Name | Description | Mandatory to set | Default value
+|------------------------------|-------------------------------------------------|------------------| -----
+| ClientSideTeleporter.baseUrl | base url of the Sling Server to which to deploy | yes | - |
+| ClientSideTeleporter.includeDependencyPrefixes | comma-separated list of package prefixes for classes referenced from the IT. Only the classes having one of the given package prefix are included in the bundle being deployed to the given Sling instance together with the IT class itself. They are only included though in case they are referenced! If this is not set, no referenced classes will be included. | no | - |
+| ClientSideTeleporter.excludeDependencyPrefixes | comma-separated list of package prefixes for classes referenced from the IT. Classes having one of the given package prefix will not be included in the bundle being deployed to the given Sling instance together with the IT class itself. This takes precedence over the <code>ClientSideTeleporter.includeDependencyPrefixes</code>. | no | - |
+| ClientSideTeleporter.testReadyTimeoutSeconds | how long to wait for our test to be ready on the server-side in seconds, after installing the test bundle. | no | 12 |
+| ClientSideTeleporter.serverUsername | the username with which to send requests to the Sling server. | no | admin |
+| ClientSideTeleporter.serverPassword | the password with which to send requests to the Sling server. | no | admin |
+The provisioning of an appropriate instance can be done with the <a href="/documentation/development/slingstart.html">slingstart-maven-plugin</a>. An example for that is given at <a href="https://svn.apache.org/viewvc/sling/trunk/testing/samples/module-with-it"><code>testing/samples/module-with-it</code></a>.</li>
+<li>The <em><a href="https://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests/src/main/java/org/apache/sling/junit/teleporter/customizers/LaunchpadCustomizer.java"><code>LaunchpadCustomizer</code></a></em>, which only verifies that a Sling instance is ready
+at a given port and configures the <code>ClientSideTeleporter</code> to deploy to <code>http://localhost:8888</code> with the credentials <code>admin</code>:<code>admin</code>. <code>LaunchpadCustomizer</code> uses the <code>HttpTestBase</code> therefore some parameters are customizable through System Parameters. There is no bootstrapping of an instance done here, so this must be done separately!</li>
+<li>The <em>[<code>BWIT_TeleporterCustomizer</code>](http://svn.apache.org/viewvc/sling/trunk/testing/samples/bundle-with-it/src/test/java/org/apache/sling/junit/teleporter/customizers/BWIT_TeleporterCustomizer.java]</em> which is based on <code>SlingTestBase</code> to set the server's base url and credentials. Additionally the test bundle is adjusted so that the API is not included in it (but rather referenced from another bundle). The bootstrapping of the Sling instance is tweaked through system properties which are desribed <a href="http://labs.6dglobal.com/blog/2013-06-05/creating-integration-tests-apache-sling/">here</a> and implicitly done by the customizer itself.</li>
+</ol>
+<p>Those should give you an overview on what can be done with a customizer and decide whether you need to write your own one or using the default customizer is just enough.</p>
<h2 id="orgapacheslingjunithealthcheck-run-junit-tests-as-sling-health-checks">org.apache.sling.junit.healthcheck: run JUnit tests as Sling Health Checks<a class="headerlink" href="#orgapacheslingjunithealthcheck-run-junit-tests-as-sling-health-checks" title="Permanent link">¶</a></h2>
<p>This bundle allows JUnit tests to run as <a href="/documentation/bundles/sling-health-check-tool.html">Sling Health Checks</a>,
which can be useful when defining smoke tests for example, allowing them to be used both at build time and run time.</p>
@@ -266,7 +290,7 @@ same request again. </p>
but using the newer <code>TeleporterRule</code> described above is much simpler. As a result, this bundle
should only be needed for existing tests that were written using its mechanisms. </p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1735143 by bdelacretaz on Tue, 15 Mar 2016 17:07:11 +0000
+ Rev. 1762021 by kwin on Fri, 23 Sep 2016 08:11:05 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project