You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2015/07/03 11:15:18 UTC
isis-site git commit: ISIS-1166 - SoapEndpointPulishingRule
Repository: isis-site
Updated Branches:
refs/heads/asf-site 2d5883a75 -> e3363caa5
ISIS-1166 - SoapEndpointPulishingRule
added to ug/unitestsupport
Project: http://git-wip-us.apache.org/repos/asf/isis-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis-site/commit/e3363caa
Tree: http://git-wip-us.apache.org/repos/asf/isis-site/tree/e3363caa
Diff: http://git-wip-us.apache.org/repos/asf/isis-site/diff/e3363caa
Branch: refs/heads/asf-site
Commit: e3363caa5525705b5eb305e257e22b5c669dd296
Parents: 2d5883a
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Jul 3 10:10:18 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Fri Jul 3 10:10:18 2015 +0100
----------------------------------------------------------------------
content/guides/ug.html | 179 +++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 177 insertions(+), 2 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis-site/blob/e3363caa/content/guides/ug.html
----------------------------------------------------------------------
diff --git a/content/guides/ug.html b/content/guides/ug.html
index 90215bd..8bb1afe 100644
--- a/content/guides/ug.html
+++ b/content/guides/ug.html
@@ -14197,7 +14197,176 @@ CustomerRepository customers;</code></pre>
</div>
</div>
<div class="sect3">
-<h4 id="_ug_testing_unit-test-support_maven-configuration">12.2.3. Maven Configuration</h4>
+<h4 id="_ug_testing_unit-test-support_soap-fake-server-junit-rule">12.2.3. SOAP Fake Servers</h4>
+<div class="paragraph">
+<p>No man is an island, and neither are most applications. Chances are that at some point you may need to integrate your Apache Isis application to other external systems, possibly using old-style SOAP web services. The SOAP client in this case could be a domain service within your app, or it might be externalized, eg invoked through a scheduler or using <a href="http://camel.apache.org">Apache Camel</a>.</p>
+</div>
+<div class="paragraph">
+<p>While you will want to (of course) perform manual system testing/UAT with a test instance of that external system, it’s also useful to be able to perform unit testing of your SOAP client component.</p>
+</div>
+<div class="paragraph">
+<p>The <code>SoapEndpointPublishingRule</code> is a simple JUnit rule that allows you to run a fake SOAP endpoint within an unit test.</p>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>The (non-ASF) <a href="http://github.com/isisaddons/isis-module-publishmq">Isis addons' publishmq</a> module provides a full example of how to integrate and test an Apache Isis application with a (faked out) external system.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="sect4">
+<h5 id="__code_soapendpointpublishingrule_code"><code>SoapEndpointPublishingRule</code></h5>
+<div class="paragraph">
+<p>The idea behing this rule is that you write a fake server that implements the same WSDL contract as the "real" external system does, but which also exposes additional API to specify responses (or throw exceptions) from SOAP calls. It also typically records the requests and allows these to be queried.</p>
+</div>
+<div class="paragraph">
+<p>In its setup your unit test instantiates the fake server, and gets the rule to host that fake server on an SOAP endpoint. It also instantiates the SOAP client, pointing it at the endpoint address (that is, a URL) that the fake server is runnig on.</p>
+</div>
+<div class="paragraph">
+<p>In the test methods your unit test sets up expectations on your fake server, and then exercises the SOAP client. The SOAP client calls the fake server, which then responds accordingly. The test can then assert that all expected interactions have occurred.</p>
+</div>
+<div class="paragraph">
+<p>So that tests don’t take too long to run, the rule puts the server onto a thread-local. Therefore the unit tests should clear up any state on the fake server.</p>
+</div>
+<div class="paragraph">
+<p>The easiest way to use the rule is to subclass it for your particular fake server, eg:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">ExternalSystemFakeServerRule</span>
+ <span class="directive">extends</span> SoapEndpointPublishingRule<ExternalSystemFakeServer> { <i class="conum" data-value="1"></i><b>(1)</b>
+ <span class="directive">public</span> ExternalSystemFakeServerRule() {
+ <span class="local-variable">this</span>(<span class="integer">54345</span>); <i class="conum" data-value="2"></i><b>(2)</b>
+ }
+ <span class="directive">public</span> ExternalSystemFakeServerRule(<span class="directive">final</span> <span class="type">int</span> port) {
+ <span class="local-variable">super</span>(
+ buildAddress(port), <i class="conum" data-value="3"></i><b>(3)</b>
+ () -> <span class="keyword">new</span> ExternalSystemFakeServer()); <i class="conum" data-value="4"></i><b>(4)</b>
+ }
+ <span class="directive">protected</span> <span class="directive">static</span> <span class="predefined-type">String</span> buildAddress(<span class="directive">final</span> <span class="type">int</span> port) {
+ <span class="keyword">return</span> <span class="predefined-type">String</span>.format(<span class="string"><span class="delimiter">"</span><span class="content">http://localhost:%d/any/old/string/will/work</span><span class="delimiter">"</span></span>, port);
+ }
+}</code></pre>
+</div>
+</div>
+<div class="colist arabic">
+<table>
+<tr>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>generic type specifies the class that implements the endpoint</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="2"></i><b>2</b></td>
+<td>hardcoded port (or could choose one at random from within a range)</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="3"></i><b>3</b></td>
+<td>build an address based on the port</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="4"></i><b>4</b></td>
+<td>provide a <code>Supplier</code> that will instantiate the fake server</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p>Your unit test should then look something like:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">ExternalSystemFakeServerRuleTest</span> {
+ <span class="annotation">@Rule</span>
+ <span class="directive">public</span> ExternalSystemFakeServerRule serverRule = <span class="keyword">new</span> ExternalSystemFakeServerRule();
+ <span class="directive">private</span> ExternalSystemFakeServer externalSystemFakeServer;
+ <span class="directive">private</span> DemoObject externalSystemContract; <i class="conum" data-value="1"></i><b>(1)</b>
+ <span class="annotation">@Before</span>
+ <span class="directive">public</span> <span class="type">void</span> setUp() <span class="directive">throws</span> <span class="exception">Exception</span> {
+ <span class="directive">final</span> DemoObjectService externalSystemService = <i class="conum" data-value="2"></i><b>(2)</b>
+ <span class="keyword">new</span> DemoObjectService(ExternalSystemWsdl.getWsdl()); <i class="conum" data-value="3"></i><b>(3)</b>
+ externalSystemContract = externalSystemService.getDemoObjectOverSOAP();
+ BindingProvider provider = (BindingProvider) externalSystemContract;
+ provider.getRequestContext().put(
+ BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
+ serverRule.getEndpointAddress()
+ );
+ externalSystemFakeServer = serverRule.getPublishedEndpoint(); <i class="conum" data-value="4"></i><b>(4)</b>
+ }
+ <span class="annotation">@Test</span>
+ <span class="directive">public</span> <span class="type">void</span> happy_case() <span class="directive">throws</span> <span class="exception">Exception</span> {
+ <span class="comment">// given</span>
+ <span class="directive">final</span> Update update = <span class="keyword">new</span> Update(); <i class="conum" data-value="5"></i><b>(5)</b>
+ ...
+
+ <span class="comment">// expect</span>
+ final UpdateResponse response = <span class="keyword">new</span> UpdateResponse(); <i class="conum" data-value="6"></i><b>(6)</b>
+ ...
+ externalSystemFakeServer.control().setResponse(updateResponse);
+
+ <span class="comment">// when</span>
+ PostResponse response = externalSystemContract.post(update); <i class="conum" data-value="7"></i><b>(7)</b>
+
+ <span class="comment">// then</span>
+ <span class="directive">final</span> <span class="predefined-type">List</span><Update> updates = <i class="conum" data-value="8"></i><b>(8)</b>
+ externalSystemFakeServer.control().getUpdates();
+ ...
+ }
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="colist arabic">
+<table>
+<tr>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>the SOAP contract as defined in WSDL and generated by wsdl2java</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="2"></i><b>2</b></td>
+<td>also generated by wsdl2java</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="3"></i><b>3</b></td>
+<td><code>getWsdl()</code> is a utility method to return a URL for the WSDL (eg from the classpath)</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="4"></i><b>4</b></td>
+<td>get hold of the fake server running at the end point</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="5"></i><b>5</b></td>
+<td>create a request (generated from the WSDL and wsdl2java)</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="6"></i><b>6</b></td>
+<td>instruct fake server how to respond</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="7"></i><b>7</b></td>
+<td>invoke the service</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="8"></i><b>8</b></td>
+<td>check service was correctly invoked etc.</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_xml_marshalling_support">XML Marshalling Support</h5>
+<div class="paragraph">
+<p>Apache Isis' unit testing support also provides helper <code>JaxbUtil</code> and <code>JaxbMatchers</code> classes. These are useful if you have exampler XML-serialized representations of the SOAP requests and response payloads and want to use these within your tests.</p>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_ug_testing_unit-test-support_maven-configuration">12.2.4. Maven Configuration</h4>
<div class="paragraph">
<p>Apache Isis' unit test support is automatically configured if you use the <a href="#_ug_getting-started_simpleapp-archetype">SimpleApp archetype</a>. To set it up manually, update the <code>pom.xml</code> of your domain object model module:</p>
</div>
@@ -17847,7 +18016,13 @@ TODO
</ul>
</li>
<li><a href="#_ug_testing_unit-test-support_jmock-extensions">12.2.2. JMock Extensions</a></li>
-<li><a href="#_ug_testing_unit-test-support_maven-configuration">12.2.3. Maven Configuration</a></li>
+<li><a href="#_ug_testing_unit-test-support_soap-fake-server-junit-rule">12.2.3. SOAP Fake Servers</a>
+<ul class="sectlevel4">
+<li><a href="#__code_soapendpointpublishingrule_code"><code>SoapEndpointPublishingRule</code></a></li>
+<li><a href="#_xml_marshalling_support">XML Marshalling Support</a></li>
+</ul>
+</li>
+<li><a href="#_ug_testing_unit-test-support_maven-configuration">12.2.4. Maven Configuration</a></li>
</ul>
</li>
<li><a href="#_ug_testing_integ-test-support">12.3. Integration Test Support</a>