Author: buildbot
Date: Tue Sep 22 09:41:04 2015
New Revision: 966320
Log:
Staging update by buildbot for sling
Added:
websites/staging/sling/trunk/content/documentation/bundles/org-apache-sling-junit-bundles.html
Modified:
websites/staging/sling/trunk/content/ (props changed)
websites/staging/sling/trunk/content/documentation/bundles.html
Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Sep 22 09:41:04 2015
@@ -1 +1 @@
-1704398
+1704493
Modified: websites/staging/sling/trunk/content/documentation/bundles.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/bundles.html (original)
+++ websites/staging/sling/trunk/content/documentation/bundles.html Tue Sep 22
09:41:04 2015
@@ -152,6 +152,7 @@ h2:hover > .headerlink, h3:hover > .head
<li><a href="/documentation/bundles/models.html">Model Objects</a></li>
<li><a href="/documentation/pax-exam-utils.html">Sling Pax Exam
Utilities</a></li>
<li><a href="/documentation/bundles/sling-query.html">Sling Query
Library</a></li>
+<li><a href="/documentation/bundles/org-apache-sling-junit-bundles.html">Junit
Server-Side Tests Support</a></li>
</ul>
<h2 id="content-presentation">Content Presentation<a class="headerlink"
href="#content-presentation" title="Permanent link">¶</a></h2>
<ul>
@@ -175,7 +176,7 @@ h2:hover > .headerlink, h3:hover > .head
<li><a href="/documentation/bundles/log-tracers.html">Log Tracer</a></li>
</ul>
<div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
- Rev. 1703252 by sseifert on Tue, 15 Sep 2015 16:49:44 +0000
+ Rev. 1704493 by bdelacretaz on Tue, 22 Sep 2015 09:40:41 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache
Sling project
Added:
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
(added)
+++
websites/staging/sling/trunk/content/documentation/bundles/org-apache-sling-junit-bundles.html
Tue Sep 22 09:41:04 2015
@@ -0,0 +1,224 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
+<html>
+<!--
+
+ 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.
+-->
+ <head>
+ <title>Apache Sling - JUnit server-side testing support bundles</title>
+ <link rel="icon" href="/res/favicon.ico">
+ <link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
+ <link rel="stylesheet" href="/res/codehilite.css" type="text/css"
media="all">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/";>
+ <img border="0" alt="Apache Sling" src="/res/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/";>
+ <img border="0" alt="Apache" src="/res/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+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><strong><a href="/documentation.html">Documentation</a></strong> <br />
+<a href="/documentation/getting-started.html">Getting Started</a> <br />
+<a href="/documentation/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/documentation/development.html">Development</a> <br />
+<a href="/documentation/bundles.html">Bundles</a> <br />
+<a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a>
<br />
+<a href="/documentation/configuration.html">Configuration</a> </p>
+<p><a href="http://s.apache.org/sling.wiki";>Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq";>FAQ</a> </p>
+<p><strong>API Docs</strong> <br />
+<a href="/apidocs/sling7/index.html">Sling 7</a> <br />
+<a href="/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="/apidocs/sling5/index.html">Sling 5</a> </p>
+<p><strong>Project info</strong> <br />
+<a href="/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/";>License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a> <br />
+<a href="http://ci.apache.org/builders/sling-trunk";>Build Server</a> <br />
+<a href="/project-information/security.html">Security</a> </p>
+<p><strong>Source</strong> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a> <br />
+<a href="git://git.apache.org/sling.git">Git</a> <br />
+<a href="https://github.com/apache/sling";>Github Mirror</a> </p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html";>Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html";>Become a
Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html";>Buy Stuff</a> </p>
+<p><strong><a href="/sitemap.html">Site Map</a></strong></p>
+<!-- no valid ads for now, we'll reactivate this when needed
+<iframe
+ src="http://www.apache.org/ads/button.html";
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+-->
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a
href="/documentation.html">Documentation</a> » <a
href="/documentation/bundles.html">Bundles</a>
+ </div>
+
+
+
+ <h1>JUnit server-side testing support bundles</h1>
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+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>
+<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>The <code>org.apache.sling.junit.remote</code> bundle provides a
<code>JUnitServlet</code> that runs JUnit tests found
+in bundles. </p>
+<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>
+
+<div class="note">
+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>
+
+<p>To make tests available to that servlet, the bundle that contains them must
point to them
+with a <code>Sling-Test-Regexp</code> bundle header that defines a regular
expression that matches
+the test class names, like
<code>Sling-Test-Regexp=</code>com.example.*ServerSideTest` for example.</p>
+<p>The <code>TeleporterRule</code> 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. </p>
+<p>Using the teleporter module described below, the
<code>TeleporterRule</code> creates a temporary bundle
+that contains the test code along with any required classes, 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
+with the appropriate IDE settings.</p>
+<p>This teleporter mechanism is used in our integration tests, search for
<code>TeleporterRule</code> in there
+for examples or look at the
+<a
href="https://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/teleporter";><code>integrationtest.teleporter</code></a>
+package. </p>
+<h3 id="more-details-on-the-junitservlet">More details on the JUnitServlet<a
class="headerlink" href="#more-details-on-the-junitservlet" title="Permanent
link">¶</a></h3>
+<p>To try the JUnitServlet interactively, you can install the
+<a
href="http://svn.apache.org/repos/asf/sling/trunk/testing/samples/sample-tests";>org.apache.sling.testing.samples.sampletests</a>
+bundle, or any other bundle that contains tests and a
<code>Sling-Test-Regexp</code> bundle header that points to them, as
+described above. Or use the TeleporterRule`and set a breakpoint in the tests
execution, when the test bundle ins
+installed and will be listed by the test servlet.</p>
+<p>To list the available tests, open http://localhost:8080/system/sling/junit/
. The servlet shows available tests,
+and allows you to execute them via a POST request.</p>
+<p>Adding a path allows you to select a specific subset of tests, as in
+http://localhost:8080/system/sling/junit/org.apache.sling.junit.remote.html</p>
+<p>The JUnitServlet provides various output formats, including in particular
JSON, see
+ http://localhost:8080/system/sling/junit/.json 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 mostly provides the <code>ClientSideTeleporter</code> which the
<code>TeleporterRule</code> uses to teleport the tests
+to the server side. It is only used on the client as a dependency when running
the tests.</p>
+<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>
+<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
+to setup the <code>ClientSideTeleporter</code>, and passes the "author" string
to it as an option. This can be used to select
+which server to run the tests on, in this case the customizer could look for a
server that runs with the "author"
+run mode.</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>
+<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>
+<h2
id="orgapacheslingjunitscriptable-scriptable-server-side-tests">org.apache.sling.junit.scriptable:
scriptable server-side tests<a class="headerlink"
href="#orgapacheslingjunitscriptable-scriptable-server-side-tests"
title="Permanent link">¶</a></h2>
+<p>This bundle allows Sling scripts to be executed from the
<code>JUnitServlet</code>, as follows:</p>
+<ul>
+<li>A node that has the <code>sling:Test</code> mixin is a scriptable test
node.</li>
+<li>For security reasons, scriptable test nodes are only executed as tests if
they are found under <code>/libs</code> or <code>/apps</code>, or more
precisely under a path that's part of Sling's <code>ResourceResolver</code>
search path.</li>
+<li>To execute a test, the scriptable tests provider makes an HTTP request to
the test node's path, with a <code>.test.txt</code> selector and extension, and
expects the output to contain only the string <code>TEST_PASSED</code>. Empty
lines and comment lines starting with a hash sign (#) are ignored in the
output, and other lines are reported as failures.</li>
+</ul>
+<p>Here's a minimal example that sets up and executes a scriptable test:</p>
+<div class="codehilite"><pre>$ <span class="n">curl</span> <span
class="o">-</span><span class="n">u</span> <span class="n">admin</span><span
class="p">:</span><span class="n">admin</span> <span class="o">-</span><span
class="n">Fjcr</span><span class="p">:</span><span
class="n">primaryNodeType</span><span class="p">=</span><span
class="n">sling</span><span class="p">:</span><span class="n">Folder</span>
<span class="o">-</span><span class="n">Fsling</span><span
class="p">:</span><span class="n">resourceType</span><span
class="p">=</span><span class="n">foo</span> <span class="o">-</span><span
class="n">Fjcr</span><span class="p">:</span><span
class="n">mixinTypes</span><span class="p">=</span><span
class="n">sling</span><span class="p">:</span><span class="n">Test</span> <span
class="n">http</span><span class="p">:</span><span class="o">//</span><span
class="n">localhost</span><span class="p">:</span>8080<span
class="o">/</span><span class="n">apps</span><span class="o">/</span><sp
an class="n">foo</span>
+<span class="p">...</span>
+$ <span class="n">echo</span> <span class="n">TEST_PASSED</span> <span
class="o">></span> <span class="o">/</span><span class="n">tmp</span><span
class="o">/</span><span class="n">test</span><span class="p">.</span><span
class="n">txt</span><span class="p">.</span><span class="n">esp</span> <span
class="p">;</span> <span class="n">curl</span> <span class="o">-</span><span
class="n">u</span> <span class="n">admin</span><span class="p">:</span><span
class="n">admin</span> <span class="o">-</span><span class="n">T</span><span
class="o">/</span><span class="n">tmp</span><span class="o">/</span><span
class="n">test</span><span class="p">.</span><span class="n">txt</span><span
class="p">.</span><span class="n">esp</span> <span class="n">http</span><span
class="p">:</span><span class="o">//</span><span
class="n">localhost</span><span class="p">:</span>8080<span
class="o">/</span><span class="n">apps</span><span class="o">/</span><span
class="n">foo</span><span class="o">/</span><span cl
ass="n">test</span><span class="p">.</span><span class="n">txt</span><span
class="p">.</span><span class="n">esp</span>
+</pre></div>
+
+
+<p>At this point, foo.test.txt is what the scriptable test framework will
request, and that outputs just TEST_PASSED:</p>
+<div class="codehilite"><pre>$ <span class="n">curl</span> <span
class="o">-</span><span class="n">u</span> <span class="n">admin</span><span
class="p">:</span><span class="n">admin</span> <span class="n">http</span><span
class="p">:</span><span class="o">//</span><span
class="n">localhost</span><span class="p">:</span>8080<span
class="o">/</span><span class="n">apps</span><span class="o">/</span><span
class="n">foo</span><span class="p">.</span><span class="n">test</span><span
class="p">.</span><span class="n">txt</span>
+<span class="n">TEST_PASSED</span>
+</pre></div>
+
+
+<p>And a POST to the JUnit servlet returns information on the test's
execution:</p>
+<div class="codehilite"><pre><span class="n">curl</span> <span
class="o">-</span><span class="n">u</span> <span class="n">admin</span><span
class="p">:</span><span class="n">admin</span> <span class="o">-</span><span
class="n">XPOST</span> <span class="n">http</span><span class="p">:</span><span
class="o">//</span><span class="n">localhost</span><span
class="p">:</span>8080<span class="o">/</span><span
class="n">system</span><span class="o">/</span><span
class="n">sling</span><span class="o">/</span><span class="n">junit</span><span
class="o">/</span><span class="n">org</span><span class="p">.</span><span
class="n">apache</span><span class="p">.</span><span
class="n">sling</span><span class="p">.</span><span class="n">junit</span><span
class="p">.</span><span class="n">scriptable</span><span
class="p">.</span><span class="n">ScriptableTestsProvider</span><span
class="p">.</span><span class="n">json</span>
+<span class="p">[{</span>
+ "<span class="n">INFO_TYPE</span>"<span class="p">:</span>
"<span class="n">test</span>"<span class="p">,</span>
+ "<span class="n">description</span>"<span class="p">:</span>
"<span class="n">verifyContent</span><span class="p">[</span>0<span
class="p">](</span><span class="n">org</span><span class="p">.</span><span
class="n">apache</span><span class="p">.</span><span
class="n">sling</span><span class="p">.</span><span class="n">junit</span><span
class="p">.</span><span class="n">scriptable</span><span
class="p">.</span><span class="n">TestAllPaths</span><span
class="p">)</span>"<span class="p">,</span>
+ "<span class="n">test_metadata</span>"<span class="p">:</span>
<span class="p">{</span>
+ "<span class="n">test_execution_time_msec</span>"<span
class="p">:</span> 2
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">]</span>
+</pre></div>
+
+
+<p>Test failures would be included in this JSON representation - you can test
that by modifying the script to fail and making the
+same request again. </p>
+<h2 id="orgapacheslingjunitremote-obsolete">org.apache.sling.junit.remote:
obsolete<a class="headerlink" href="#orgapacheslingjunitremote-obsolete"
title="Permanent link">¶</a></h2>
+<p>The <code>org.apache.sling.junit.remote</code> bundle provides utilities to
run server-side JUnit tests,
+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. 1704493 by bdelacretaz on Tue, 22 Sep 2015 09:40:41 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache
Sling project
+ logo are trademarks of The Apache Software Foundation. All other marks
mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
