Author: thomas.diesler(a)jboss.com Date: 2009-04-22 05:58:15 -0400 (Wed, 22 Apr 2009) New Revision: 87665 Modified: projects/jboss-osgi/trunk/build/docbook/en/modules/ch04-developer-guide.xml Log: Add section on testing Modified: projects/jboss-osgi/trunk/build/docbook/en/modules/ch04-developer-guide.xml =================================================================== --- projects/jboss-osgi/trunk/build/docbook/en/modules/ch04-developer-guide.xml 2009-04-22 09:31:55 UTC (rev 87664) +++ projects/jboss-osgi/trunk/build/docbook/en/modules/ch04-developer-guide.xml 2009-04-22 09:58:15 UTC (rev 87665) @@ -273,4 +273,128 @@ </note> </sect1> + <sect1 xml:id="SecWritingTests"> + <title>Writing Testcases</title> + + <para>JBossOSGi comes with <ulink url="http://www.junit.org">JUnit</ulink> test support as part of the SPI provided + <ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/junit/package-summary.html">org.jboss.osgi.spi.junit</ulink> + package. There are two distinct test scenarios that we support</para> + + <itemizedlist> + <listitem>Embedded OSGi Framework</listitem> + <listitem>Remote OSGi Framework</listitem> + </itemizedlist> + + <emphasis role="bold">Testing an embedded OSGi Framework</emphasis> + + <para>In the embedded scenario the testcase bootstraps the OSGi Framework and installes and tests the bundles locally. The base class for + embedded OSGi testing is <ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/junit/OSGiTest.html">org.jboss.osgi.spi.junit.OSGiTest</ulink>. + </para> + + <programlisting role="JAVA"> + public class EmbeddedTestCase extends OSGiTest + { + public void testSomeBundle() throws Exception + { + // Bootstrap the Framework and get the system bundle + OSGiFramework framework = getBootstrapProvider().getFramework(); + BundleContext sysContext = framework.getSystemBundleContext(); + + // Install and start the test bundle + Bundle bundleA = installBundle(sysContext, "some-bundle.jar", true); + + // Verify that the bundle is active + assertEquals("Test bundle ACTIVE", Bundle.ACTIVE, bundleA.getState()); + } + } + </programlisting> + + <para>Due to classloading restrictions it is not possible to interact with the services that get registered in the OSGi Framework + directly. Instead, there must be some means for the bundle under test to communicate with the test case that lives outside the + Framework. We use an approach where the test case registeres a <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogListe... + with the <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogReade...;. Log messages are filtered and + can be verified by the test case. For this to work certain conditions must be true:</para> + + <itemizedlist> + <listitem>The Framework must have a LogService installed</listitem> + <listitem>The bundle under test must write log messages to LogService</listitem> + <listitem>The LogListener must be seen by the classloader that loads the test case</listitem> + </itemizedlist> + + <programlisting role="JAVA"> + // Setup log entry tracking + LogEntryCache logEntryCache = new LogEntryCache(); + logEntryCache.addFilter(new LogEntryFilter("example-log(.*)", LogService.LOG_INFO, "\\[ServiceA\\](.*)")); + + // Start log entry tracking + startLogEntryTracking(logEntryCache); + + // do stuff + + // Verify the received log entries + List entries = logEntryCache.getLog(); + assertEquals("Number of entries", 1, entries.size()); + assertEquals("[ServiceA] new Service", entries.get(0).getMessage()); + + // Stop log entry tracking + stopLogEntryTracking(); + </programlisting> + + <emphasis role="bold">Testing a remote OSGi Framework</emphasis> + + <para>In the remote scenario the testcase deploys the test bundle on the remote OSGi Framework. The base class for embedded OSGi testing + is <ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/junit/IntegrationTest.html">org.jboss.osgi.spi.junit.IntegrationTest</ulink>. + </para> + + <programlisting role="JAVA"> + public class RemoteTestCase extends IntegrationTest + { + public void testSomeBundle() throws Exception + { + // Deploy the test bundle + RemoteBundle bundleA = deployBundle("some-bundle.jar"); + + // Verify that the bundle is active + assertEquals("Test bundle ACTIVE", Bundle.ACTIVE, bundleA.getState()); + + // Undeploy the test bundle + undeployBundle("some-bundle.jar"); + } + } + </programlisting> + + <para>The test approach is simmilar to the embedded scenario. The test bundle writes log messages to the LogService. A RemoteLogListener transmits + the log messages to the RemoteLogReaderService that is installed locally. The test case registeres a LogListener with the RemoteLogReaderService. + Log messages are filtered and can be verified by the test case. Again, certain conditions must be true:</para> + + <itemizedlist> + <listitem>The remote Framework must have a LogService installed</listitem> + <listitem>The jboss-osgi-remotelog.jar bundle must be installed in both the remote and local Framework</listitem> + <listitem>The bundle under test must write log messages to LogService</listitem> + <listitem>The LogListener must be seen by the classloader that loads the test case</listitem> + </itemizedlist> + + <programlisting role="JAVA"> + // Setup log entry tracking + LogEntryCache logEntryCache = new LogEntryCache(); + logEntryCache.addFilter(new LogEntryFilter("example-log(.*)", LogService.LOG_INFO, "\\[ServiceA\\](.*)")); + + // Start log entry tracking + startRemoteLogEntryTracking(logEntryCache); + + // do stuff + + // Verify the received log entries + List entries = logEntryCache.getLog(); + assertEquals("Number of entries", 1, entries.size()); + assertEquals("[ServiceA] new Service", entries.get(0).getMessage()); + + // Stop log entry tracking + stopRemoteLogEntryTracking(); + </programlisting> + + <para>For details on how to setup remote log message tracking, have a look at <xref linkend="SecRemoteLogService"/>.</para> + + </sect1> + </chapter>