Author: buildbot
Date: Thu Sep 17 07:36:21 2015
New Revision: 965724
Log:
Staging update by buildbot for sling
Modified:
websites/staging/sling/trunk/content/ (props changed)
websites/staging/sling/trunk/content/documentation/development/sling-testing-tools.html
Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Sep 17 07:36:21 2015
@@ -1 +1 @@
-1703306
+1703508
Modified:
websites/staging/sling/trunk/content/documentation/development/sling-testing-tools.html
==============================================================================
---
websites/staging/sling/trunk/content/documentation/development/sling-testing-tools.html
(original)
+++
websites/staging/sling/trunk/content/documentation/development/sling-testing-tools.html
Thu Sep 17 07:36:21 2015
@@ -39,7 +39,18 @@
</div>
<div class="menu">
- <p><strong><a href="/documentation.html">Documentation</a></strong> <br
/>
+ <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 />
@@ -90,7 +101,18 @@
<h1>Sling Testing Tools</h1>
- <p>Sling provides a number of testing tools to support the following use
cases:</p>
+ <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>Sling provides a number of testing tools to support the following use
cases:</p>
<ul>
<li>Run JUnit tests contributed by OSGi bundles in an OSGi system. This does
not require Sling and should work in other OSGi environments.</li>
<li>Run scriptable tests in a Sling instance, using any supported scripting
language.</li>
@@ -100,10 +122,10 @@
<p>The <a
href="http://svn.apache.org/repos/asf/sling/trunk/testing/samples/integration-tests";>testing/samples/integration-tests</a>
module demonstrates these tools, and is also meant as a sample project to show
how to run integration tests for Sling-based applications.</p>
<p>The main Sling integration tests at <a
href="https://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests";>launchpad/integration-tests</a>
were created before this testing framework, and do not use it yet (as of March
2011). The new testing tools are simpler to use, but the "old" tests (all 400
of them as I write this) fulfill their validation role for testing Sling
itself, there's no real need to modify them to use the new tools.</p>
<p>See also <a
href="/documentation/tutorials-how-tos/testing-sling-based-applications.html">Testing
Sling-based applications</a> which discusses testing in general.</p>
-<h2 id="required-bundles">Required bundles</h2>
+<h2 id="required-bundles">Required bundles<a class="headerlink"
href="#required-bundles" title="Permanent link">¶</a></h2>
<p>These tools require a number of bundles on top of the standard Sling
launchpad. See the <a
href="http://svn.apache.org/repos/asf/sling/trunk/testing/samples/integration-tests/pom.xml";>sample
tests pom.xml</a>
for an up-to-date list. Look for <code>sling.additional.bundle.*</code>
entries in that pom for the bundle artifact IDs, and see the
<code>dependencies</code> section for their version numbers.</p>
-<h1 id="server-side-junit-tests-contributed-by-bundles">Server-side JUnit
tests contributed by bundles</h1>
+<h1 id="server-side-junit-tests-contributed-by-bundles">Server-side JUnit
tests contributed by bundles<a class="headerlink"
href="#server-side-junit-tests-contributed-by-bundles" title="Permanent
link">¶</a></h1>
<p>The services provided by the <a
href="http://svn.apache.org/repos/asf/sling/trunk/testing/junit/core";>org.apache.sling.junit.core</a>
bundle allow bundles to register JUnit tests, which are executed server-side
by the JUnitServlet registered by default at <code>/system/sling/junit</code>.
This bundle is not dependent on Sling, it should work in other OSGi
environments.</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.
@@ -118,9 +140,9 @@ For tighter integration with Sling, the
<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 -
the example integration tests described below use this to selectively execute
server-side tests. The JUnitServlet provides various output formats, including
in particular JSON, see http://localhost:8080/system/sling/junit/.json for
example.</p>
<p>To supply tests from your own bundles, simply export the tests classes and
add the <code>Sling-Test-Regexp</code> header to the bundle so that the Sling
JUnit core services register them as tests.</p>
-<h3 id="injection-of-osgi-services">Injection of OSGi services</h3>
+<h3 id="injection-of-osgi-services">Injection of OSGi services<a
class="headerlink" href="#injection-of-osgi-services" title="Permanent
link">¶</a></h3>
<p>The <code>@TestReference</code> annotation is used to inject OSGi services
in tests that are executed server side.The <code>BundleContext</code> can also
be injected in this way, see the <a
href="http://svn.apache.org/repos/asf/sling/trunk/testing/samples/sample-tests/src/main/java/org/apache/sling/testing/samples/sampletests/OsgiAwareTest.java";>OsgiAwareTest</a>
for an example.</p>
-<h2 id="curl-examples">Curl examples</h2>
+<h2 id="curl-examples">Curl examples<a class="headerlink"
href="#curl-examples" title="Permanent link">¶</a></h2>
<p>Here's an example executing a few tests using curl:</p>
<div class="codehilite"><pre>$ <span class="n">curl</span> <span
class="o">-</span><span class="n">X</span> <span class="n">POST</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">testing</span><span class="p">.</span><span
class="n">samples</span><span class="p">.</span><span
class="n">sampletests</span><span class="p">.</span><span
class="n">JUnit</span><span class="p">.</span><span class="n">json</span>
<span class="p">[{</span>
@@ -142,7 +164,7 @@ For tighter integration with Sling, the
</pre></div>
-<h1 id="scriptable-server-side-tests">Scriptable server-side tests</h1>
+<h1 id="scriptable-server-side-tests">Scriptable server-side tests<a
class="headerlink" href="#scriptable-server-side-tests" title="Permanent
link">¶</a></h1>
<p>If the <a
href="http://svn.apache.org/repos/asf/sling/trunk/testing/junit/scriptable";>org.apache.sling.junit.scriptable</a>
bundle is active in a Sling system, (in addition to the
<code>org.apache.sling.junit.core</code> bundle), scriptable tests can be
executed by the <code>JUnitServlet</code> according to the following rules:</p>
<ul>
<li>A node that has the <code>sling:Test</code> mixin is a scriptable test
node.</li>
@@ -178,7 +200,7 @@ $ <span class="n">echo</span> <span clas
<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>
-<h1 id="integration-tests-example">Integration tests example</h1>
+<h1 id="integration-tests-example">Integration tests example<a
class="headerlink" href="#integration-tests-example" title="Permanent
link">¶</a></h1>
<p>The <a
href="http://svn.apache.org/repos/asf/sling/trunk/testing/samples/integration-tests";>testing/samples/integration-tests</a>
module runs some simple integration tests against a Sling Launchpad instance
that's setup from scratch before running the tests.</p>
<p>This module's pom and Java code can be used as examples to setup your own
integration testing modules for Sling-based apps - or for any other runnable
jar that provides an http service.</p>
<p>Besides serving as examples, some of the tests in this module are used to
validate the testing tools. They run as part of the full Sling <a
href="/project-information.html">continuous integration</a> build, so they're
guaranteed to be correct examples if that build is successful.</p>
@@ -195,18 +217,23 @@ same request again. </p>
<li>The test results are reported via the usual Maven mechanisms.</li>
</ol>
<p>If <code>-DkeepJarRunning</code> is used on the Maven command line, the
Sling runnable jar does not exit, to allow for running individual tests against
this instance, for example when debugging the tests or the server code. See the
pom for details.</p>
-<h1 id="remote-test-execution">Remote test execution</h1>
+<h2 id="running-tests-against-existing-server">Running tests against existing
server<a class="headerlink" href="#running-tests-against-existing-server"
title="Permanent link">¶</a></h2>
+<p>Instead of provisioning a completely new Sling server, the ITs can also be
executed on an already existing server instance. For that the
+<code>test-server-url</code> system property has to point to the existing
server url.
+Additional bundles can still be deployed by using the
<code>sling.additional.bundle.<num></code> system property.</p>
+<p>Optionally, the additional bundles can be undeployed after the execution of
the IT by setting <code>additional.bundles.uninstall</code> to
<code>true</code>. (since Sling Testing Tools 1.0.12, <a
href="https://issues.apache.org/jira/browse/SLING-4819";>SLING-4819</a>)</p>
+<h1 id="remote-test-execution">Remote test execution<a class="headerlink"
href="#remote-test-execution" title="Permanent link">¶</a></h1>
<p>The testing tools support two types of remote test execution.</p>
-<h2 id="slingremotetestrunner">SlingRemoteTestRunner</h2>
+<h2 id="slingremotetestrunner">SlingRemoteTestRunner<a class="headerlink"
href="#slingremotetestrunner" title="Permanent link">¶</a></h2>
<p>The <a
href="http://svn.apache.org/repos/asf/sling/trunk/testing/junit/remote/src/main/java/org/apache/sling/junit/remote/testrunner/SlingRemoteTestRunner.java";>SlingRemoteTestRunner</a>
is used to run tests using the <code>JUnitServlet</code> described above. In
this case, the client-side JUnit test only defines which tests to run and some
optional assertions. Checking the number of tests executed, for example, can be
useful to make sure all test bundles have been activated as expected, to avoid
ignoring missing test bundles.</p>
<p>See the <a
href="https://svn.apache.org/repos/asf/sling/trunk/testing/samples/integration-tests/src/test/java/org/apache/sling/testing/samples/integrationtests/serverside/ServerSideSampleTest.java";>ServerSideSampleTest</a>
class for an example.</p>
<p>It's a good idea to check that the JUnit servlet is ready before running
those tests, see the
<a
href="https://svn.apache.org/repos/asf/sling/trunk/testing/samples/integration-tests/src/test/java/org/apache/sling/testing/samples/integrationtests/serverside/sling/SlingServerSideTestsBase.java";>ServerSideTestsBase</a>
for an example of how to do that.</p>
-<h2 id="slingremoteexecutionrule">SlingRemoteExecutionRule</h2>
+<h2 id="slingremoteexecutionrule">SlingRemoteExecutionRule<a
class="headerlink" href="#slingremoteexecutionrule" title="Permanent
link">¶</a></h2>
<p>The <a
href="http://svn.apache.org/repos/asf/sling/trunk/testing/junit/remote/src/main/java/org/apache/sling/junit/remote/ide/SlingRemoteExecutionRule.java";>SlingRemoteExecutionRule</a>
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.</p>
<p>The <a
href="https://svn.apache.org/repos/asf/sling/trunk/testing/junit/remote/src/main/java/org/apache/sling/junit/remote/exported/ExampleRemoteTest.java";>ExampleRemoteTest</a>
class demonstrates this. To run it from your IDE, set the
<code>sling.remote.test.url</code> in the IDE to the URL of the JUnitServlet,
like http://localhost:8080/system/sling/junit for example.</p>
-<h1 id="debugging-its">Debugging ITs</h1>
+<h1 id="debugging-its">Debugging ITs<a class="headerlink"
href="#debugging-its" title="Permanent link">¶</a></h1>
<p>The JVM is usually forked twice during the execution of integration tests.
The first time by the <code>maven-surefire-plugin</code> which executes the
client-side (i.e. Maven-side) part of the tests. To debug this side the option
<code>-Dmaven.surefire.debug</code> 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 <a
href="http://maven.apache.org/surefire/maven-surefire-plugin/examples/debugging.html";>documentation
of the maven-surefire-plugin</a>.</p>
<p>Then the <code>JarExecutor</code> 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 <code>jar.executor.vm.options</code> can be
used to start that VM with debug options. All debug options are described at
the <a
href="http://docs.oracle.com/javase/7/docs/technotes/guides/jpda/conninv.html#Invocation";>JPDA
documentation</a>. If running </p>
<div class="codehilite"><pre><span class="n">mvn</span> <span
class="n">test</span> <span class="o">-</span><span class="n">Djar</span><span
class="p">.</span><span class="n">executor</span><span class="p">.</span><span
class="n">vm</span><span class="p">.</span><span class="n">options</span><span
class="p">=</span>"<span class="o">-</span><span
class="n">agentlib</span><span class="p">:</span><span
class="n">jdwp</span><span class="p">=</span><span
class="n">transport</span><span class="p">=</span><span
class="n">dt_socket</span><span class="p">,</span><span
class="n">server</span><span class="p">=</span><span class="n">y</span><span
class="p">,</span><span class="n">suspend</span><span class="p">=</span><span
class="n">y</span><span class="p">,</span><span class="n">address</span><span
class="p">=</span>8000"
@@ -215,7 +242,7 @@ for an example of how to do that.</p>
<p>the server start is interrupted until a debugger is connected on port
8000.</p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
- Rev. 1685039 by kwin on Fri, 12 Jun 2015 07:15:19 +0000
+ Rev. 1703508 by kwin on Thu, 17 Sep 2015 07:36:02 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache
Sling project
