Changeset 30036

Timestamp:

02/11/08 17:55:54 (10 months ago)

Author:

gracinet

Message:

Documentation for NXRuntimeTestCase

Files:

• doc/nuxeo-book/trunk/src/docbook/nxruntime/index.xml (modified) (1 diff)

doc/nuxeo-book/trunk/src/docbook/nxruntime/index.xml

@@ -1048 +1048 @@
-
-  <section>
+    <title>Integration tests for Nuxeo Runtime applications</title>
+    <para>
+      While it's obviously a good thing to unit-test one's code, it's usually not enough for a 
+      module designed to be ran as part of a Nuxeo Runtime application. It's indeed likely in this situation that
+      the module will depend on services provided by other modules, and even maybe on their default configuration. It's 
+      even not uncommon that a project specific modules consists almost exclusively of calls to generic services provided
+      by the base software platform.
+    </para>
+
+    <section xml:id="nuxeo-runtime-test-NXRuntimeTestCase">
+      <title>The NXRuntimeTestCase base class</title>
+      <para><code>org.nuxeo.runtime.test.NXRuntimeTestCase</code> is a base class to write JUnit tests 
+      for Nuxeo Runtime applications. It sets up the Nuxeo Runtime environment (in the <code>setUp</code> method
+      and provides methods to control bundle and resources loading. It's designed to behave in the same manner in Maven 
+      and Eclipse situations. Therefore resources must be accessed in a way that does not depend on the actual ordering
+      of classpath.</para>
+      <section><title>Loading a bundle</title>
+        <para>To load a whole OSGI bundle, use the <code>deployBundle</code> method, whose parameter is the bundle symbolic
+        name, as specified in the manifest</para>
+      </section>
+      <section><title>Loading one contribution from a bundle</title>
+        <para>Loading a whole bundle can be too heavy, or bring unwanted default configurations. Therefore, the 
+        <code>deployContrib</code> method is 
+        provided to load just a resource (service definition, extension point contribution, etc.) from a given bundle. 
+        It takes two arguments: the bundle symbolic name, and the path to the contrib from the top of bundle.
+        </para>
+      </section>
+      <section><title>Loading a test resouce</title>
+        <para>For resources from the test packages, just make an OSGI bundle of the test package, which can be done 
+        by creating the META-INF/MANIFEST.MF at the top of the target jar, and use deployContrib as above.
+        </para>
+      </section>
+      <section><title>Sample usage</title>
+        <para>The following is an excerpt from <code>org.nuxeo.project.sample</code>:
+          <programlisting><![CDATA[
+public class TestBookTitleService extends NXRuntimeTestCase {
+
+    private BookTitleService service;
+
+    private static final String OSGI_BUNDLE_NAME = "org.nuxeo.project.sample";
+
+    private static final String OSGI_TEST_BUNDLE = "org.nuxeo.project.sample.tests";
+
+    public void setUp() throws Exception {
+        super.setUp();
+        // deployment of the whole nuxeo-project sample bundle
+        deployBundle(OSGI_BUNDLE_NAME);
+
+        service = Framework.getService(BookTitleService.class);
+    }
+
+    public void testServiceContribution() throws Exception {
+        // Lookup is ensured simply by making the 'test' sub-hierarchy a
+        // bundle of its own, with a MANIFEST file
+        deployContrib(OSGI_TEST_BUNDLE, "sample-booktitle-test.xml");
+        assertEquals("FOOBAR Test", service.correctTitle("foobar"));
+    }
+]]>
+          </programlisting>
+        </para>
+      </section>
+    </section>
+
+  <section><title>Frequent patterns</title>
+    <para>While working on an integration test, it's always worthwile to prescribe clearly what is
+    to be tested: either API calls to services provided by other modules, consistency with configuration provided
+    by other modules, default configuration for the module being tested. This is especially important for the 
+    non-regression aspect of the testing and the cost of maintaining the tests.</para>
+    
+    <para>The use-cases discussed below require basic knowledge of the Nuxeo ECM framework. Implicitely, it is somehow
+    assumed that the tested code has to interact with one service. In case of multiple target services, one'd have to 
+    choose a pattern for each of them.</para>
+
+    <section><title>Integration test against base services with testing configuration</title>
+      <para> We want to check that the API calls from the tested component to other components have the desired effect, but we don't want to rewrite the tests each time  the default configuration of the other components change. Typically, this means that we need to deploy the xml contributions that define the services we need, together with the minimal configuration to tie it up together.</para>
+
+      <para>Example: The search service is able to configure its indexes automatically from the schemas and core types declaration. We don't want to have to update tests if someone changes the default config that ships with nuxeo-core. Ideally, this test should use <code>deployBundle</code> to set up core services, test repository, etc. and then work on dedicated schemas and core types that are loaded by <code>deployContrib</code>.
+      </para>
+    </section>
+
+    <section><title>Integration test against base services and their default configuration</title>
+      <para>
+        One can imagine here a core event listener that uses a given schema, a component that needs access 
+      to the search service to manipulate some specific documents...
+      </para>
+      <para>In this case, we need to load the base service and its configuration exactly as they are in the real application and we do want the test to catch errors that are due to a change in said configuration. In this pattern, we'd use <code>deployBundle</code> all over the place.
+      </para>
+      <para>
+    It's likely however that one does not want the test to rely on the default (if any) configuration of the module being tested. If the tested component doesn't carry its configuration but still needs to be deployed within Nuxeo Runtime, <code>deployBundle</code> can be used on itself, and then <code>deployContrib</code> for the test configuration, after the test package has been upgraded to an OSGI bundle.
+      </para>
+      <para>Variant: testing of a component and the configuration that comes along.
+        Just think of your tested module as a "base service."</para>
+    </section>
+    <section><title>Reusing test resources from another component</title>
+      <para>
+        This is usually neither possible nor recommended. Such situations do appear in the Nuxeo code base, and the proper 
+        solution is to provide the wished resources or classes from a <code>package</code>, precisely like
+        <code>org.nuxeo.ecm.runtime.test</code> does.
+      </para>
+    </section>  
+  </section>
+  </section>
+  
+  <section>
-    <title>References</title>
-