ace-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r930358 [10/10] - in /websites/staging/ace/trunk/content: ./ dev-doc/ docs/ docs/analysis/ docs/analysis/src/ docs/design/ docs/design/src/ docs/use-cases/ user-doc/
Date Mon, 24 Nov 2014 22:42:14 GMT
Added: websites/staging/ace/trunk/content/docs/writing-tests.html
==============================================================================
--- websites/staging/ace/trunk/content/docs/writing-tests.html (added)
+++ websites/staging/ace/trunk/content/docs/writing-tests.html Mon Nov 24 22:42:13 2014
@@ -0,0 +1,309 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+  <head>
+    <title>Writing unit/integration tests</title>
+    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+    <meta property="og:image" content="//www.apache.org/images/asf_logo.gif" />
+    <link href="/css/bootstrap.min.css" rel="stylesheet" media="screen">
+    <link href="/css/prettify.css" rel="stylesheet" media="screen">
+    <link href="/css/code.css" rel="stylesheet" media="screen">
+    <script src="//code.jquery.com/jquery.js"></script>
+    <script src="/js/bootstrap.min.js"></script>    
+    <script src="/js/prettify.js"></script>
+    
+    
+    
+    <script>
+    $(function () { prettyPrint() })
+    $().dropdown()
+    </script>
+  </head>
+  <body style="padding-top: 50px;">
+    <div class="navbar navbar-fixed-top navbar-inverse">
+      <div class="navbar-inner">
+        <div class="container">
+          <a class="brand" href="/index.html">Apache ACE&trade;</a>
+          <ul class="nav">
+  <li class="dropdown">
+    <a href="#" class="dropdown-toggle" data-toggle="dropdown">News <b class="caret"></b></a>
+    <ul class="dropdown-menu">
+      <li>
+        <a href="/news.html">News</a>
+      </li>
+      <li>
+        <a href="/on-the-web.html">On the web</a>
+      </li>
+    </ul>
+  </li>
+  <li>
+    <a href="/downloads.html">Downloads</a>
+  </li>
+  <li class="dropdown">
+    <a href="#" class="dropdown-toggle" data-toggle="dropdown">Users <b class="caret"></b></a>
+    <ul class="dropdown-menu">
+      <li>
+        <a href="/user-doc/introduction.html">Introduction</a>
+      </li>
+      <li>
+        <a href="/user-doc/getting-started.html">Getting Started</a>
+      </li>
+      <li>
+        <a href="/user-doc/user-guide.html">User Guide</a>
+      </li>
+      <li>
+        <a href="/user-doc/features.html">Features</a>
+      </li>
+      <li>
+        <a href="/user-doc/shellapi.html">Client Shell API</a>
+      </li>
+	    <li>
+        <a href="/user-doc/restapi.html">Client REST API</a>
+      </li>
+      <li>
+        <a href="/user-doc/useradmin-ui.html">User Management Guide</a>
+      </li>
+      <li>
+        <a href="/user-doc/faq.html">FAQ</a>
+      </li>
+      <li>
+        <a href="/user-doc/support.html">Support</a>
+      </li>
+    </ul>
+  </li>
+  <li class="dropdown">
+    <a href="#" class="dropdown-toggle" data-toggle="dropdown">Developers <b class="caret"></b></a>
+    <ul class="dropdown-menu">
+      <li>
+        <a href="/dev-doc/getting-started.html">Getting Started</a>
+      </li>
+      <li>
+        <a href="/dev-doc/requirements/">Requirements</a>
+      </li>
+      <li>
+        <a href="/dev-doc/architecture.html">Architecture</a>
+      </li>
+      <li>
+        <a href="/dev-doc/analysis/">Analysis</a>
+      </li>
+      <li>
+        <a href="/dev-doc/design/">Design</a>
+      </li>
+      <li>
+        <a href="/dev-doc/coding-standards.html">Coding Standards</a>
+      </li>
+      <li>
+        <a href="/dev-doc/release-guide.html">Release Guide</a>
+      </li>
+      <li>
+        <a href="/dev-doc/writing-tests.html">Writing unit/integration tests</a>
+      </li>
+      <li>
+        <a href="/dev-doc/adding-custom-artifact-types.html">Adding custom artifact
types</a>
+      </li>
+      <li>
+        <a href="/dev-doc/configuring-relay-servers.html">Configuring and using relay
servers</a>
+      </li>
+    </ul>
+  </li>
+  <li class="dropdown">
+    <a href="#" class="dropdown-toggle" data-toggle="dropdown">Get Involved <b class="caret"></b></a>
+    <ul class="dropdown-menu">
+      <li>
+        <a href="/get-involved/mailing-lists.html">Mailing Lists</a>
+      </li>
+      <li>
+        <a href="/get-involved/issue-tracking.html">Issue Tracking</a>
+      </li>
+      <li>
+        <a href="/get-involved/continuous-integration.html">Continuous Integration</a>
+      </li>
+      <li>
+        <a href="/get-involved/source-code.html">Source Code</a>
+      </li>
+      <li>
+        <a href="/get-involved/project-team.html">Project Team</a>
+      </li>
+    </ul>
+  </li>
+  <li class="dropdown">
+    <a href="#" class="dropdown-toggle" data-toggle="dropdown">Wiki <b class="caret"></b></a>
+    <ul class="dropdown-menu">
+      <li>
+        <a href="https://cwiki.apache.org/confluence/display/ACE/Board+Reports">Board
Reports <i class="icon-share-alt"></i></a>
+      </li>
+      <li>
+        <a href="https://cwiki.apache.org/confluence/display/ACE/Index">Homepage <i
class="icon-share-alt"></i></a>
+      </li>
+    </ul>
+  </li>
+  <li class="dropdown">
+    <a href="#" class="dropdown-toggle" data-toggle="dropdown">Apache <b class="caret"></b></a>
+    <ul class="dropdown-menu">
+      <li>
+        <a href="http://www.apache.org/">Apache Homepage <i class="icon-share-alt"></i></a>
+      </li>
+      <li>
+        <a href="http://www.apache.org/licenses/">Licenses <i class="icon-share-alt"></i></a>
+      </li>
+      <li>
+        <a href="http://www.apache.org/security/">Security <i class="icon-share-alt"></i></a>
+      </li>
+      <li>
+        <a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship <i
class="icon-share-alt"></i></a>
+      </li>
+      <li>
+        <a href="http://www.apache.org/foundation/thanks.html">Thanks <i class="icon-share-alt"></i></a>
+      </li>
+    </ul>
+  </li>
+</ul>
+
+        </div>
+      </div>
+    </div>
+    <div class="container">
+      <p><a href="/"><i class='icon-home'></i> Home</a>&nbsp;&raquo&nbsp;<a
href="/docs/">Docs</a></p>
+      <h1>Writing unit/integration tests</h1>
+      <div class="clear"></div>
+      <div id="content"><p>This tutorial describes how to write unit and integration
tests for ACE. For its unit tests, ACE relies on <a href="http://testng.org">TestNG</a>,
while for the integration tests a combination of <a href="http://www.bndtools.org">BndTools</a>
and <a href="http://junit.org">JUnit</a> is used.</p>
+<h2 id="writing-unit-tests">Writing unit tests</h2>
+<p>Unit tests test the behavior of classes or methods in complete isolation. In case
this is not possible, due to dependencies on other classes, one can make use of a mocking
framework such as <a href="http://code.google.com/p/mockito/">Mockito</a> to replace
those dependencies with stub implementations.</p>
+<p>Writing unit tests with TestNG is much like writing tests with JUnit: you create
a class which contains methods annotated with the <code>@Test</code> annotation.
Also, you can add methods that are run before or after each test or test case. One feature
that is distinct to TestNG is the ability to group tests, making it possible to run only a
certain group of tests instead of all<sup id="fnref:1"><a class="footnote-ref" href="#fn:1"
rel="footnote">1</a></sup>.</p>
+<p>All unit tests are placed in the same project they are testing, in a separate directory
named <code>test</code>. This allows the tests to be compiled and run independently
from the remaining code. It is good practice to have the same package structure for your tests
and other code. </p>
+<h3 id="example">Example</h3>
+<p>Lets take a look at an excerpt from the unit test<sup id="fnref:2"><a class="footnote-ref"
href="#fn:2" rel="footnote">2</a></sup> for <code>AuthenticationServiceImpl</code>:</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">class</span> <span class="nc">AuthenticationServiceImplTest</span>
<span class="o">{</span>
+   <span class="kd">private</span> <span class="n">LogService</span>
<span class="n">m_log</span><span class="o">;</span>
+
+   <span class="nd">@BeforeMethod</span><span class="o">(</span><span
class="n">alwaysRun</span> <span class="o">=</span> <span class="kc">true</span><span
class="o">)</span>
+   <span class="kd">public</span> <span class="kt">void</span> <span
class="nf">setUp</span><span class="o">()</span> <span class="o">{</span>
+       <span class="n">m_log</span> <span class="o">=</span> <span
class="n">Mockito</span><span class="o">.</span><span class="na">mock</span><span
class="o">(</span><span class="n">LogService</span><span class="o">.</span><span
class="na">class</span><span class="o">);</span>
+   <span class="o">}</span>
+
+   <span class="cm">/**</span>
+<span class="cm">    * Tests that an exception is thrown if a null context is given.</span>
+<span class="cm">    */</span>
+   <span class="nd">@Test</span><span class="o">(</span><span
class="n">groups</span> <span class="o">=</span> <span class="o">{</span>
<span class="s">&quot;UNIT&quot;</span> <span class="o">},</span>
<span class="n">expectedExceptions</span> <span class="o">=</span>
<span class="n">IllegalArgumentException</span><span class="o">.</span><span
class="na">class</span><span class="o">)</span>
+   <span class="kd">public</span> <span class="kt">void</span> <span
class="nf">testAuthenticateFailsWithNullContext</span><span class="o">()</span>
<span class="o">{</span>
+      <span class="k">new</span> <span class="nf">AuthenticationServiceImpl</span><span
class="o">(</span><span class="n">m_log</span><span class="o">).</span><span
class="na">authenticate</span><span class="o">((</span><span class="n">Object</span><span
class="o">[])</span> <span class="kc">null</span><span class="o">);</span>
+   <span class="o">}</span>
+
+   <span class="cm">/**</span>
+<span class="cm">    * Tests that without any authentication processors, no authentication
will take place.</span>
+<span class="cm">    */</span>
+   <span class="nd">@Test</span><span class="o">(</span><span
class="n">groups</span> <span class="o">=</span> <span class="o">{</span>
<span class="s">&quot;UNIT&quot;</span> <span class="o">})</span>
+   <span class="kd">public</span> <span class="kt">void</span> <span
class="nf">testAuthenticateFailsWithoutAuthProcessors</span><span class="o">()</span>
<span class="o">{</span>
+       <span class="n">Assert</span><span class="o">.</span><span
class="na">assertNull</span><span class="o">(</span><span class="n">createAuthenticationService</span><span
class="o">().</span><span class="na">authenticate</span><span class="o">(</span><span
class="s">&quot;foo&quot;</span><span class="o">,</span> <span
class="s">&quot;bar&quot;</span><span class="o">),</span> <span
class="s">&quot;Expected authentication to fail!&quot;</span><span class="o">);</span>
+   <span class="o">}</span>
+
+   <span class="c1">// ...</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>This snippet shows us almost all important concepts for TestNG:</p>
+<ul>
+<li>The <tt>@BeforeMethod</tt> annotation allows us to run a method before
each individual test. In this 'setUp' method, we create a stub implementation of a <tt>LogService</tt>.
<strong>Note:</strong> the <code>alwaysRun = true</code> is needed
to ensure that this method is run, even though it does not belong to any test-group;</li>
+<li>The method <tt>testAuthenticateFailsWithNullContext</tt> is annotated
with the <tt>@Test</tt> annotation, and its parameters tell us two more things:
it belongs to a group UNIT, and there's a failure to expect in the form of an 'IllegalArgumentException'.
In this method, we instantiate the class-under-test (using the stub 'LogService') and invoke
a method on it;</li>
+<li>The last method (<tt>testAuthenticateFailsWithoutAuthProcessors</tt>)
shows us how to make assertions on the results of methods. The <tt>Assert</tt>
class of TestNG is almost equivalent to its equally named counterpart in JUnit with one difference:
the failure message always comes last.</li>
+</ul>
+<p>To run the unit tests for a project, you simply go to the root directory of the
project itself, and call:</p>
+<div class="codehilite"><pre><span class="nv">$ </span>ant testng
+</pre></div>
+
+
+<p>This will run the unit tests using TestNG. The output of the tests can be found
in the <tt>test-output</tt> directory of your project. To run the test from Eclipse,
you can right click on it, and select "Run As -&gt; TestNG Test" from its context menu.</p>
+<h2 id="writing-integration-tests">Writing integration tests</h2>
+<p>In an integration test you test whether a small part of your system works as expected.
For this, you need to set up an environment which resembles the situation in which the system
is finally deployed. For ACE, this means that we need to set up an OSGi environment and a
subset of the bundles we want to test. Fortunately, BndTools provides us with easy tooling
to just do that with the use of <a href="http://pub.admc.com/howtos/junit3x/">JUnit3</a><sup
id="fnref:3"><a class="footnote-ref" href="#fn:3" rel="footnote">3</a></sup>.</p>
+<h3 id="integration-test-principles">Integration test principles</h3>
+<p>To write a very basic (OSGi) integration test, you need to extend your test from
<tt>junit.framework.TestCase</tt>. To access the bundle context of your test case,
you can make use of some standard OSGi utility code:</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">class</span> <span class="nc">MyIntegrationTest</span> <span
class="kd">extends</span> <span class="n">junit</span><span class="o">.</span><span
class="na">framework</span><span class="o">.</span><span class="na">TestCase</span>
<span class="o">{</span>
+    <span class="kd">private</span> <span class="kd">volatile</span>
<span class="n">org</span><span class="o">.</span><span class="na">osgi</span><span
class="o">.</span><span class="na">framework</span><span class="o">.</span><span
class="na">BundleContext</span> <span class="n">m_context</span><span
class="o">;</span>
+
+    <span class="c1">//...</span>
+
+    <span class="kd">protected</span> <span class="kt">void</span>
<span class="nf">setUp</span><span class="o">()</span> <span class="kd">throws</span>
<span class="n">Exception</span> <span class="o">{</span>
+        <span class="n">m_context</span> <span class="o">=</span>
<span class="n">org</span><span class="o">.</span><span class="na">osgi</span><span
class="o">.</span><span class="na">framework</span><span class="o">.</span><span
class="na">FrameworkUtil</span><span class="o">.</span><span class="na">getBundle</span><span
class="o">(</span><span class="n">getClass</span><span class="o">()).</span><span
class="na">getBundleContext</span><span class="o">();</span>
+    <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>With this in place, we can now make OSGi calls from our test methods.</p>
+<p>To ease the writing of integration tests, ACE provides a <code>IntegrationTestBase</code><sup
id="fnref:4"><a class="footnote-ref" href="#fn:4" rel="footnote">4</a></sup>
helper class that provides you with some  boilerplate code commonly used in integration tests.
Internally, it makes use of Felix Dependency Manager to control and manage the desired service
dependencies. </p>
+<h3 id="example_1">Example</h3>
+<p>In this section, we'll describe how to write an integration test that makes use
of a 'UserAdmin' service in its test method.</p>
+<p>The first we need to do is create our test class:</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">class</span> <span class="nc">UserAdminIntegrationTest</span>
<span class="kd">extends</span> <span class="n">IntegrationTestBase</span>
<span class="o">{</span>
+    <span class="kd">private</span> <span class="kd">volatile</span>
<span class="n">org</span><span class="o">.</span><span class="na">osgi</span><span
class="o">.</span><span class="na">service</span><span class="o">.</span><span
class="na">useradmin</span><span class="o">.</span><span class="na">UserAdmin</span>
<span class="n">m_userAdmin</span><span class="o">;</span>
+
+    <span class="kd">protected</span> <span class="n">org</span><span
class="o">.</span><span class="na">apache</span><span class="o">.</span><span
class="na">felix</span><span class="o">.</span><span class="na">dm</span><span
class="o">.</span><span class="na">Component</span><span class="o">[]</span>
<span class="nf">getDependencies</span><span class="o">()</span> <span
class="o">{</span>
+        <span class="k">return</span> <span class="k">new</span>
<span class="n">org</span><span class="o">.</span><span class="na">apache</span><span
class="o">.</span><span class="na">felix</span><span class="o">.</span><span
class="na">dm</span><span class="o">.</span><span class="na">Component</span><span
class="o">[]</span> <span class="o">{</span>
+            <span class="n">createComponent</span><span class="o">()</span>
+                <span class="o">.</span><span class="na">setImplementation</span><span
class="o">(</span><span class="k">this</span><span class="o">)</span>
+                <span class="o">.</span><span class="na">add</span><span
class="o">(</span><span class="n">createServiceDependency</span><span
class="o">().</span><span class="na">setService</span><span class="o">(</span><span
class="n">org</span><span class="o">.</span><span class="na">osgi</span><span
class="o">.</span><span class="na">service</span><span class="o">.</span><span
class="na">useradmin</span><span class="o">.</span><span class="na">UserAdmin</span><span
class="o">.</span><span class="na">class</span><span class="o">).</span><span
class="na">setRequired</span><span class="o">(</span><span class="kc">true</span><span
class="o">))</span>
+        <span class="o">};</span>
+    <span class="o">}</span>
+
+    <span class="c1">// ...</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Having explained that our test depends upon the 'UserAdmin' service, and that its
a required dependency, means that our test won't run if this service is not available<sup
id="fnref:5"><a class="footnote-ref" href="#fn:5" rel="footnote">5</a></sup>.</p>
+<p>Sometimes, you need to do some additional set up before or after the dependencies
are resolved. For example, one might need to provision some configuration in order to get
dependencies in the correct state, or wait until some other condition is met after all dependencies
have been resolved. In order to do this, one can override the <code>before()</code>
or <code>after()</code> methods<sup id="fnref:6"><a class="footnote-ref"
href="#fn:6" rel="footnote">6</a></sup> in <code>IntegrationTestBase</code>.<br
/>
+For our simple integration test, however, we do not need such "advanced" set up.</p>
+<p>The only thing left is the actual test itself. As the 'UserAdmin' service is being
tracked for us, we can simply direct use it in our test:</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">class</span> <span class="nc">UserAdminIntegrationTest</span>
<span class="kd">extends</span> <span class="n">IntegrationTestBase</span>
<span class="o">{</span>
+    <span class="c1">// ...</span>
+
+    <span class="kd">public</span> <span class="kt">void</span> <span
class="nf">testUserAdminCreateGroupRoleOk</span><span class="o">()</span>
<span class="kd">throws</span> <span class="n">Exception</span> <span
class="o">{</span>
+        <span class="n">org</span><span class="o">.</span><span
class="na">osgi</span><span class="o">.</span><span class="na">service</span><span
class="o">.</span><span class="na">useradmin</span><span class="o">.</span><span
class="na">Role</span> <span class="n">group</span> <span class="o">=</span>

+            <span class="n">m_userAdmin</span><span class="o">.</span><span
class="na">createRole</span><span class="o">(</span><span class="s">&quot;MyGroup&quot;</span><span
class="o">,</span> <span class="n">org</span><span class="o">.</span><span
class="na">osgi</span><span class="o">.</span><span class="na">service</span><span
class="o">.</span><span class="na">useradmin</span><span class="o">.</span><span
class="na">Role</span><span class="o">.</span><span class="na">GROUP</span><span
class="o">);</span>
+
+        <span class="n">Assert</span><span class="o">.</span><span
class="na">assertNotNull</span><span class="o">(</span><span class="n">group</span><span
class="o">);</span>
+        <span class="n">Assert</span><span class="o">.</span><span
class="na">assertEquals</span><span class="o">(</span><span class="s">&quot;MyGroup&quot;</span><span
class="o">,</span> <span class="n">group</span><span class="o">.</span><span
class="na">getName</span><span class="o">());</span>
+    <span class="o">}</span>
+
+    <span class="c1">// ...</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>That is it! The only thing left is to run the test, which is as simple as:</p>
+<div class="codehilite"><pre><span class="nv">$ </span>ant <span
class="nb">test</span>
+</pre></div>
+
+
+<p>When running Eclipse, you can also run your integration test by right clicking on
it, and selecting <tt>Run As -&gt; OSGi JUnit Test</tt> from its context menu.</p>
+<h2 id="notes">Notes</h2>
+<div class="footnote">
+<hr />
+<ol>
+<li id="fn:1">
+<p>The consequence is that TestNG also allows you to write other kinds of tests than
unit tests, like integration tests or performance tests. ACE does not make use of this kind
of functionality, and only uses TestNG for its unit testing.&#160;<a class="footnote-backref"
href="#fnref:1" rev="footnote" title="Jump back to footnote 1 in the text">&#8617;</a></p>
+</li>
+<li id="fn:2">
+<p>This test can be found in the <code>org.apache.ace.authentication</code>
project.&#160;<a class="footnote-backref" href="#fnref:2" rev="footnote" title="Jump
back to footnote 2 in the text">&#8617;</a></p>
+</li>
+<li id="fn:3">
+<p>The current version of BndTools still uses JUnit3, while there is some effort already
to support JUnit4 as well, see: <a href="https://github.com/bndtools/bnd/issues/156">https://github.com/bndtools/bnd/issues/156</a>.&#160;<a
class="footnote-backref" href="#fnref:3" rev="footnote" title="Jump back to footnote 3 in
the text">&#8617;</a></p>
+</li>
+<li id="fn:4">
+<p>This helper class can be found in the <code>org.apache.ace.test</code>
project.&#160;<a class="footnote-backref" href="#fnref:4" rev="footnote" title="Jump
back to footnote 4 in the text">&#8617;</a></p>
+</li>
+<li id="fn:5">
+<p>To be more precise: the test will wait a couple of seconds to allow all dependencies
to be satisfied. If after this waiting period any dependency is not satisfied, the test will
fail.&#160;<a class="footnote-backref" href="#fnref:5" rev="footnote" title="Jump back
to footnote 5 in the text">&#8617;</a></p>
+</li>
+<li id="fn:6">
+<p>The naming of these methods could use a second thought, see also: <a href="https://issues.apache.org/jira/browse/ACE-289">https://issues.apache.org/jira/browse/ACE-289</a>.&#160;<a
class="footnote-backref" href="#fnref:6" rev="footnote" title="Jump back to footnote 6 in
the text">&#8617;</a></p>
+</li>
+</ol>
+</div></div>
+      <hr>
+      <footer>
+        <p>Copyright &#169; 2012-2014 <a href="http://www.apache.org/">The
Apache Software Foundation</a>, Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache
License, Version 2.0</a>.<br/>Apache ACE, the Apache ACE logo, Apache and the
Apache feather logo are trademarks of The Apache Software Foundation. All other marks mentioned
may be trademarks or registered trademarks of their respective owners.</p>
+      </footer>
+    </div>
+  </body>
+</html>

Modified: websites/staging/ace/trunk/content/sitemap.html
==============================================================================
--- websites/staging/ace/trunk/content/sitemap.html (original)
+++ websites/staging/ace/trunk/content/sitemap.html Mon Nov 24 22:42:13 2014
@@ -166,6 +166,7 @@
       <h1>Sitemap</h1>
       <div class="clear"></div>
       <div id="content"><ul>
+<li><a href="/docs.html">Documentation</a></li>
 <li><a href="/downloads.html">Downloads</a></li>
 <li><a href="/index.html"></a></li>
 <li><a href="/news.html">News</a></li>



Mime
View raw message