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 2018/01/03 14:48:38 UTC
[06/87] [abbrv] [partial] isis-site git commit: adds SNAPSHOT version
http://git-wip-us.apache.org/repos/asf/isis-site/blob/d215fa50/content/versions/SNAPSHOT/guides/ugtst/ugtst.html
----------------------------------------------------------------------
diff --git a/content/versions/SNAPSHOT/guides/ugtst/ugtst.html b/content/versions/SNAPSHOT/guides/ugtst/ugtst.html
new file mode 100644
index 0000000..799bd91
--- /dev/null
+++ b/content/versions/SNAPSHOT/guides/ugtst/ugtst.html
@@ -0,0 +1,3416 @@
+<!doctype html>
+<html>
+ <head>
+ <!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ -->
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <meta charset="utf-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <!-- No caching headers -->
+ <meta http-equiv="cache-control" content="no-cache">
+ <meta http-equiv="pragma" content="no-cache">
+ <meta http-equiv="expires" content="-1">
+ <title>Testing</title>
+ <link rel="icon" type="image/png" href="../../images/isis-favicon.png">
+ <!--
+ Based on DataNucleus' template,
+ that was in turn based on an earlier version of Apache Isis' template,
+ that was in turn based on Apache Deltaspike's template.
+
+ This template uses
+ * Bootstrap v3.3.7 (https://getbootstrap.com/) for navbar.
+ * Bootstrap TOC plugin v0.4.1 (https://afeld.github.io/bootstrap-toc/)
+ for the table of contents.
+ * jQuery (necessary for Bootstrap's JavaScript plugins)
+ * Font-Awesome for some icons used by Asciidoctor
+
+ Also:
+ * Bootswatch "flatly" theme for Bootstrap (https://bootswatch.com/flatly).
+ * slick.js (carousel)
+ * add a link to all headers (home-grown, adapted from blog posts)
+ * integration of elasticlunr.js (home-grown, adapted from blog posts)
+ -->
+ <link href="https://cdnjs.cloudflare.com/ajax/libs/bootswatch/3.3.7/flatly/bootstrap.min.css" rel="stylesheet">
+ <link href="../../css/bootstrap-toc/0.4.1/bootstrap-toc.min.css" rel="stylesheet">
+ <link href="../../css/asciidoctor/foundation.css" rel="stylesheet">
+ <link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.3.0/css/font-awesome.min.css" rel="stylesheet">
+ <link href="../../css/slick/1.5.0/slick.css" rel="stylesheet">
+ <link href="../../css/slick/1.5.0/slick-theme.css" rel="stylesheet">
+ <link href="../../css/search-panel/search-panel.css" rel="stylesheet">
+ <link href="../../css/header-links/header-links.css" rel="stylesheet">
+ <link href="../../css/sticky-header/sticky-header.css" rel="stylesheet">
+ <link href="../../css/customisations.css" rel="stylesheet">
+ <!-- Coderay syntax formatter -->
+ <style type="text/css">
+ /* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */
+/*pre.CodeRay {background-color:#f7f7f8;}*/
+.CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em}
+.CodeRay span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)}
+.CodeRay .line-numbers strong{color:rgba(0,0,0,.4)}
+table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none}
+table.CodeRay td{vertical-align: top;line-height:1.45}
+table.CodeRay td.line-numbers{text-align:right}
+table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)}
+table.CodeRay td.code{padding:0 0 0 .5em}
+table.CodeRay td.code>pre{padding:0}
+.CodeRay .debug{color:#fff !important;background:#000080 !important}
+.CodeRay .annotation{color:#007}
+.CodeRay .attribute-name{color:#000080}
+.CodeRay .attribute-value{color:#700}
+.CodeRay .binary{color:#509}
+.CodeRay .comment{color:#998;font-style:italic}
+.CodeRay .char{color:#04d}
+.CodeRay .char .content{color:#04d}
+.CodeRay .char .delimiter{color:#039}
+.CodeRay .class{color:#458;font-weight:bold}
+.CodeRay .complex{color:#a08}
+.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
+.CodeRay .color{color:#099}
+.CodeRay .class-variable{color:#369}
+.CodeRay .decorator{color:#b0b}
+.CodeRay .definition{color:#099}
+.CodeRay .delimiter{color:#000}
+.CodeRay .doc{color:#970}
+.CodeRay .doctype{color:#34b}
+.CodeRay .doc-string{color:#d42}
+.CodeRay .escape{color:#666}
+.CodeRay .entity{color:#800}
+.CodeRay .error{color:#808}
+.CodeRay .exception{color:inherit}
+.CodeRay .filename{color:#099}
+.CodeRay .function{color:#900;font-weight:bold}
+.CodeRay .global-variable{color:#008080}
+.CodeRay .hex{color:#058}
+.CodeRay .integer,.CodeRay .float{color:#099}
+.CodeRay .include{color:#555}
+.CodeRay .inline{color:#000}
+.CodeRay .inline .inline{background:#ccc}
+.CodeRay .inline .inline .inline{background:#bbb}
+.CodeRay .inline .inline-delimiter{color:#d14}
+.CodeRay .inline-delimiter{color:#d14}
+.CodeRay .important{color:#555;font-weight:bold}
+.CodeRay .interpreted{color:#b2b}
+.CodeRay .instance-variable{color:#008080}
+.CodeRay .label{color:#970}
+.CodeRay .local-variable{color:#963}
+.CodeRay .octal{color:#40e}
+.CodeRay .predefined{color:#369}
+.CodeRay .preprocessor{color:#579}
+.CodeRay .pseudo-class{color:#555}
+.CodeRay .directive{font-weight:bold}
+.CodeRay .type{font-weight:bold}
+.CodeRay .predefined-type{color:inherit}
+.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
+.CodeRay .key{color:#808}
+.CodeRay .key .delimiter{color:#606}
+.CodeRay .key .char{color:#80f}
+.CodeRay .value{color:#088}
+.CodeRay .regexp .delimiter{color:#808}
+.CodeRay .regexp .content{color:#808}
+.CodeRay .regexp .modifier{color:#808}
+.CodeRay .regexp .char{color:#d14}
+.CodeRay .regexp .function{color:#404;font-weight:bold}
+.CodeRay .string{color:#d20}
+.CodeRay .string .string .string{background:#ffd0d0}
+.CodeRay .string .content{color:#d14}
+.CodeRay .string .char{color:#d14}
+.CodeRay .string .delimiter{color:#d14}
+.CodeRay .shell{color:#d14}
+.CodeRay .shell .delimiter{color:#d14}
+.CodeRay .symbol{color:#990073}
+.CodeRay .symbol .content{color:#a60}
+.CodeRay .symbol .delimiter{color:#630}
+.CodeRay .tag{color:#008080}
+.CodeRay .tag-special{color:#d70}
+.CodeRay .variable{color:#036}
+.CodeRay .insert{background:#afa}
+.CodeRay .delete{background:#faa}
+.CodeRay .change{color:#aaf;background:#007}
+.CodeRay .head{color:#f8f;background:#505}
+.CodeRay .insert .insert{color:#080}
+.CodeRay .delete .delete{color:#800}
+.CodeRay .change .change{color:#66f}
+.CodeRay .head .head{color:#f4f}
+ </style>
+ </head>
+ <body data-spy="scroll" data-target="#toc">
+ <div id="basedir" style="display:none;">
+ ../../
+ </div>
+ <div id="docname" style="display:none;">
+ ugtst
+ </div>
+ <div id="filetype" style="display:none;">
+ html
+ </div>
+ <!-- Navbar -->
+ <nav class="navbar navbar-default navbar-static-top header">
+ <div class="container">
+ <div class="navbar-header">
+ <!-- Three line menu button for use on mobile screens -->
+ <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar"> <span class="sr-only">Toggle navigation</span> <span class="icon-bar"></span> <span class="icon-bar"></span> <span class="icon-bar"></span> </button>
+ <a class="navbar-brand" href="../../index.html"> <img alt="Brand" src="../../images/isis-logo-48x48.png"> </a>
+ <a class="navbar-brand" href="../../index.html">Apache Isis</a>
+ </div>
+ <!-- Navbar that will collapse on mobile screens -->
+ <div id="navbar" class="navbar-collapse collapse">
+ <ul class="nav navbar-nav">
+ <li class="dropdown"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Documentation<span class="caret"></span></a>
+ <ul class="dropdown-menu">
+ <li><a href="../../documentation.html">Table of Contents</a></li>
+ <li role="separator" class="divider"></li>
+ <li class="dropdown-header">User Guides</li>
+ <li><a href="../../guides/ugfun/ugfun.html">Fundamentals</a></li>
+ <li><a href="../../guides/ugvw/ugvw.html">Wicket Viewer</a></li>
+ <li><a href="../../guides/ugvro/ugvro.html">Restful Objects Viewer</a></li>
+ <li><a href="../../guides/ugodn/ugodn.html">DataNucleus Object Store</a></li>
+ <li><a href="../../guides/ugsec/ugsec.html">Security</a></li>
+ <li><a href="../../guides/ugtst/ugtst.html">Testing</a></li>
+ <li><a href="../../guides/ugbtb/ugbtb.html">Beyond the Basics</a></li>
+ <li role="separator" class="divider"></li>
+ <li class="dropdown-header">Reference Guides</li>
+ <li><a href="../../guides/rgant/rgant.html">Annotations</a></li>
+ <li><a href="../../guides/rgsvc/rgsvc.html">Domain Services</a></li>
+ <li><a href="../../guides/rgcfg/rgcfg.html">Core Config' Properties</a></li>
+ <li><a href="../../guides/rgcms/rgcms.html">Classes, Methods and Schema</a></li>
+ <li><a href="../../guides/rgmvn/rgmvn.html">Maven plugin</a></li>
+ <li><a href="../../guides/rgfis/rgfis.html">Framework Internal Services</a></li>
+ <li role="separator" class="divider"></li>
+ <li class="dropdown-header">Javadoc</li>
+ <li><a href="http://javadoc.io/doc/org.apache.isis.core/isis-core-applib">Applib</a></li>
+ </ul> </li>
+ <li class="dropdown hidden-sm hidden-md"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Downloads<span class="caret"></span></a>
+ <ul class="dropdown-menu">
+ <li class="dropdown-header">Maven archetypes</li>
+ <li><a href="../../guides/ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype">helloworld</a></li>
+ <li><a href="../../guides/ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">simpleapp</a></li>
+ <li role="separator" class="divider"></li>
+ <li><a href="../../downloads.html">Downloads</a></li>
+ <li><a href="../../release-notes/release-notes.html">Release Notes</a></li>
+ <li><a href="../../migration-notes/migration-notes.html">Migration Notes</a></li>
+ <li role="separator" class="divider"></li>
+ <li><a href="https://github.com/apache/isis">Github mirror</a></li>
+ </ul> </li>
+ <li class="dropdown hidden-sm"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Support<span class="caret"></span></a>
+ <ul class="dropdown-menu">
+ <li class="dropdown-header">Guides</li>
+ <li><a href="../../guides/dg/dg.html">Developers' Guide</a></li>
+ <li><a href="../../guides/cgcom/cgcom.html">Committers' Guide</a></li>
+ <li><a href="../../guides/htg.html">Hints-n-Tips Guide</a></li>
+ <li role="separator" class="divider"></li>
+ <li class="dropdown-header">Mailing Lists</li>
+ <li><a href="../../support.html">How to subscribe</a></li>
+ <li><a href="https://lists.apache.org/list.html?users@isis.apache.org">Archives (ASF Pony mail)</a></li>
+ <li><a href="http://isis.markmail.org/search/?q=">Archives (Markmail)</a></li>
+ <li role="separator" class="divider"></li>
+ <li class="dropdown-header">Other Resources</li>
+ <li><a href="https://issues.apache.org/jira/browse/ISIS">ASF JIRA</a></li>
+ <li><a href="http://stackoverflow.com/questions/tagged/isis">Stack Overflow</a></li>
+ <li><a href="../../help.html">Wiki, Fisheye etc.</a></li>
+ </ul> </li>
+ <li class="dropdown hidden-sm hidden-md"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">@ASF<span class="caret"></span></a>
+ <ul class="dropdown-menu">
+ <li><a href="http://www.apache.org/">Apache Homepage</a></li>
+ <li><a href="http://www.apache.org/licenses/">Licenses</a></li>
+ <li><a href="http://www.apache.org/security/">Security</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+ <li role="separator" class="divider"></li>
+ <li><a href="https://whimsy.apache.org/board/minutes/Isis.html">PMC board minutes</a></li>
+ </ul> </li>
+ </ul>
+ <div class="nav navbar-nav navbar-right">
+ <!-- 'style' added to fix height of input box. FIX THIS -->
+ <form class="navbar-form" role="search" id="search-form" style="padding: 1px 15px;">
+ <div class="form-group">
+ <input class="form-control" id="search-field" type="text" size="30" placeholder="Search">
+ </div>
+ </form>
+ </div>
+ </div>
+ </div>
+ </nav>
+ <div class="container">
+ <div class="row-fluid">
+ <div class="col-xs-12 col-sm-12 col-md-12 col-lg-9">
+ <div id="search-panel">
+ <div id="search-results"></div>
+ <div>
+ <br>
+ <a href="#" id="search-results-clear">clear</a>
+ </div>
+ </div>
+ <span class="pdf-link"><a href="ugtst.pdf"><img src="../../images/PDF-50.png"></a></span>
+ <div class="page-title">
+ <h1>Testing</h1>
+ </div>
+ <div id="doc-content">
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugtst/ugtst.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugtst/ugtst.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugtst/ugtst.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugtst/ugtst.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugtst/ugtst.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="sect1">
+ <h2 id="__ugtst">1. Testing</h2>
+ <div class="sectionbody">
+ <div class="paragraph">
+ <p>If you are going to use Apache Isis for developing complex business-critical applications, then being able to write automated tests for those applications becomes massively important. As such Apache Isis treats the topic of testing very seriously. (Though we say it ourselves), the framework has support that goes way above what is provided by other application frameworks.</p>
+ </div>
+ <div class="paragraph">
+ <p>This guide describes those features available to you for testing your Apache Isis application.</p>
+ </div>
+ <div class="sect2">
+ <h3 id="_other_guides">1.1. Other Guides</h3>
+ <div class="paragraph">
+ <p>Apache Isis documentation is broken out into a number of user, reference and "supporting procedures" guides.</p>
+ </div>
+ <div class="paragraph">
+ <p>The user guides available are:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><a href="../ugfun/ugfun.html">Fundamentals</a></p> </li>
+ <li> <p><a href="../ugvw/ugvw.html">Wicket viewer</a></p> </li>
+ <li> <p><a href="../ugvro/ugvro.html">Restful Objects viewer</a></p> </li>
+ <li> <p><a href="../ugodn/ugodn.html">DataNucleus object store</a></p> </li>
+ <li> <p><a href="../ugsec/ugsec.html">Security</a></p> </li>
+ <li> <p><a href="../ugtst/ugtst.html">Testing</a> (this guide)</p> </li>
+ <li> <p><a href="../ugbtb/ugbtb.html">Beyond the Basics</a></p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>The reference guides are:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><a href="../rgant/rgant.html">Annotations</a></p> </li>
+ <li> <p><a href="../rgsvc/rgsvc.html">Domain Services</a></p> </li>
+ <li> <p><a href="../rgcfg/rgcfg.html">Configuration Properties</a></p> </li>
+ <li> <p><a href="../rgcms/rgcms.html">Classes, Methods and Schema</a></p> </li>
+ <li> <p><a href="../rgmvn/rgmvn.html">Apache Isis Maven plugin</a></p> </li>
+ <li> <p><a href="../rgfis/rgfis.html">Framework Internal Services</a></p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>The remaining guides are:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><a href="../dg/dg.html">Developers' Guide</a> (how to set up a development environment for Apache Isis and contribute back to the project)</p> </li>
+ <li> <p><a href="../cgcom/cgcom.html">Committers' Guide</a> (release procedures and related practices)</p> </li>
+ </ul>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="sect1">
+ <h2 id="_ugtst_overview">2. Overview</h2>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_overview.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_overview.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_overview.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_overview.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_overview.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="sectionbody">
+ <div class="sect2">
+ <h3 id="_unit_tests_vs_integ_tests">2.1. Unit tests vs Integ tests</h3>
+ <div class="paragraph">
+ <p>We divide automated tests into two broad categories:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>unit tests exercise a single unit (usually a method) of a domain object, in isolation. <br></p>
+ <div class="paragraph">
+ <p>Dependencies of that object are mocked out. These are written by a developer and for a developer; they are to ensure that a particular "cog in the machine" works correctly</p>
+ </div> </li>
+ <li> <p>integration tests exercise the application as a whole, usually focusing on one particular business operation (action). <br></p>
+ <div class="paragraph">
+ <p>These are tests that represent the acceptance criteria of some business story; their intent should make sense to the domain expert (even if the domain expert is "non-technical")</p>
+ </div> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>To put it another way:</p>
+ </div>
+ <div class="admonitionblock tip">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>Integration tests help ensure that you are <strong><em>building the right system</em></strong></p>
+ </div>
+ <div class="paragraph">
+ <p>Unit tests help ensure that you are <strong><em>building the system right</em></strong>.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_integ_tests_vs_bdd_specs">2.2. Integ tests vs BDD Specs</h3>
+ <div class="paragraph">
+ <p>We further sub-divide integration tests into:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>those that are implemented in Java and JUnit (we call these simply <em>"integration tests"</em>)<br></p>
+ <div class="paragraph">
+ <p>Even if a domain expert understands the intent of these tests, the actual implementation will be opaque to them. Also, the only output from the tests is a (hopefully) green CI job</p>
+ </div> </li>
+ <li> <p>tests (or rather, specifications) that are implemented in a <em>behaviour-driven design</em> (BDD) language such as <a href="https://cucumber.io/">Cucumber</a> (we call these <em>"BDD specs"</em>)<br></p>
+ <div class="paragraph">
+ <p>The natural language specification then maps down onto some glue code that is used to drive the application. But the benefits of taking a BDD approach include the fact that your domain expert will be able to read the tests/specifications, and that when you run the specs, you also get documentation of the application’s behaviour ("living documentation").</p>
+ </div> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>It’s up to you whether you use BDD specs for your apps; it will depend on your development process and company culture. But if you don’t then you certainly should write integration tests: acceptance criteria for user stories should be automated!</p>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_simulated_ui_code_wrapperfactory_code">2.3. Simulated UI (<code>WrapperFactory</code>)</h3>
+ <div class="paragraph">
+ <p>When we talk about integration tests/specs here, we mean tests that exercise the domain object logic, through to the actual database. But we also want the tests to exercise the app from the users’s perspective, which means including the user interface.</p>
+ </div>
+ <div class="paragraph">
+ <p>For most other frameworks that would require having to test the application in a very heavy weight/fragile fashion using a tool such as <a href="http://docs.seleniumhq.org/">Selenium</a>, driving a web browser to navigate . In this regard though, Apache Isis has a significant trick up its sleeve. Because Apache Isis implements the naked objects pattern, it means that the UI is generated automatically from declared domain-objects, -views and -services. This therefore allows for other implementations of the UI.</p>
+ </div>
+ <div class="paragraph">
+ <p>The <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_WrapperFactory"><code>WrapperFactory</code></a> domain service allows a test to wrap domain objects and thus to interact with said objects "as if" through the UI:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <a class="image" href="images/testing/integ-tests.png"><img src="images/testing/integ-tests.png" alt="integ tests" width="700px"></a>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>If the test invokes an action that is disabled, then the wrapper will throw an appropriate exception. If the action is ok to invoke, it delegates through.</p>
+ </div>
+ <div class="paragraph">
+ <p>What this means is that an Isis application can be tested end-to-end without having to deploy it onto a webserver; the whole app can be tested while running in-memory. Although integration tests re (necessarily) slower than unit tests, they are not any harder to write (in fact, in some respects they are easier).</p>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_dependency_injection">2.4. Dependency Injection</h3>
+ <div class="paragraph">
+ <p>Isis provides autowiring dependency injection into every domain object. This is most useful when writing unit tests; simply mock out the service and inject into the domain object.</p>
+ </div>
+ <div class="paragraph">
+ <p>There are a number of syntaxes supported, but the simplest is to use <code>@javax.inject.Inject</code> annotation; for example:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.inject.Inject
+CustomerRepository customers;</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Isis can inject into this even if the field has package-level (or even <code>private</code>) visibility. We recommend that you use package-level visibility, though, so that your unit tests (in the same package as the class under test) are able to inject mocks.</p>
+ </div>
+ <div class="paragraph">
+ <p>Isis does also support a couple of other syntaxes:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">void</span> setCustomerRepository(CustomerRepository customers) { ... }</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>or</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">void</span> injectCustomerRepository(CustomerRepository customers) { ... }</code></pre>
+ </div>
+ </div>
+ <div class="admonitionblock tip">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>Apache Isis also supports automatic dependency injection into integration tests; just declare the service dependency in the usual fashion and it will be automatically injected.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_given_when_then">2.5. Given/When/Then</h3>
+ <div class="paragraph">
+ <p>Whatever type of test/spec you are writing, we recommend you follow the given/when/then idiom:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><strong>given</strong> the system is in this state (preconditions)</p> </li>
+ <li> <p><strong>when</strong> I poke it with a stick</p> </li>
+ <li> <p><strong>then</strong> it looks like this (postconditions)</p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>A good test should be 5 to 10 lines long; the test should be there to help you reason about the behaviour of the system. Certainly if the test becomes more than 20 lines it’ll be too difficult to understand.</p>
+ </div>
+ <div class="paragraph">
+ <p>The "when" part is usually a one-liner, and in the "then" part there will often be only two or three assertions that you want to make that the system has changed as it should.</p>
+ </div>
+ <div class="paragraph">
+ <p>For unit test the "given" part shouldn’t be too difficult either: just instantiate the class under test, wire in the appropriate mocks and set up the expectations. And if there are too many mock expectations to set up, then "listen to the tests" … they are telling you your design needs some work.</p>
+ </div>
+ <div class="paragraph">
+ <p>Where things get difficult though is the "given" for integration tests; which is the topic of the next section…</p>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_fixture_management">2.6. Fixture Management</h3>
+ <div class="paragraph">
+ <p>In the previous section we discussed using given/when/then as a form of organizing tests, and why you should keep your tests small.</p>
+ </div>
+ <div class="paragraph">
+ <p>For integration tests though it can be difficult to keep the "given" short; there could be a lot of prerequisite data that needs to exist before you can actually exercise your system. Moreover, however we do set up that data, but we also want to do so in a way that is resilient to the system changing over time.</p>
+ </div>
+ <div class="paragraph">
+ <p>The solution that Apache Isis provides is a domain service called <a href="../rgcms/rgcms.html#_rgcms_classes_super_FixtureScripts">Fixture Scripts</a>, that defines a pattern and supporting classes to help ensure that the "data setup" for your tests are reusable and maintainable over time.</p>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_fake_data">2.7. Fake data</h3>
+ <div class="paragraph">
+ <p>In any given test there are often quite a few variables involved, to initialize the state of the objects, or to act as arguments for invoking a method, or when asserting on post-conditions. Sometimes those values are important (eg verifying that an `Order’s state went from PENDING to SHIPPED, say), but often they aren’t (a customer’s name, for example) but nevertheless need to be set up (especially in integration tests).</p>
+ </div>
+ <div class="paragraph">
+ <p>We want our tests to be easily understood, and we want the reader’s eye to be drawn to the values that are significant and ignore those that are not.</p>
+ </div>
+ <div class="paragraph">
+ <p>One way to do this is to use random (or fake) values for any insignificant data. This in effect tells the reader that "any value will do". Moreover, if it turns out that any data won’t do, and that there’s some behaviour that is sensitive to the value, then the test will start to flicker, passing and then failing depending on inputs. This is A Good Thing™.</p>
+ </div>
+ <div class="paragraph">
+ <p>Apache Isis does not, itself, ship with a fake data library. However, the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s fakedata module (non-ASF) does provide exactly this capability.</p>
+ </div>
+ <div class="admonitionblock tip">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>Using fake data works very well with fixture scripts; the fixture script can invoke the business action with sensible (fake/random) defaults, and only require that the essential information is passed into it by the test.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_feature_toggles">2.8. Feature Toggles</h3>
+ <div class="paragraph">
+ <p>Writing automated tests is just good development practice. Also good practice is developing on the mainline (master, trunk); so that your continuous integration system really is integrating all code. Said another way: <a href="http://martinfowler.com/bliki/FeatureBranch.html">don’t use branches</a>!</p>
+ </div>
+ <div class="paragraph">
+ <p>Sometimes, though, a feature will take longer to implement than your iteration cycle. In such a case, how do you use continuous integration to keep everyone working on the mainline without revealing a half-implemented feature on your releases? One option is to use <a href="http://martinfowler.com/bliki/FeatureToggle.html">feature toggle</a>s.</p>
+ </div>
+ <div class="paragraph">
+ <p>Apache Isis does not, itself, ship with a feature toggle library. However, the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s togglz module does provide exactly this capability.</p>
+ </div>
+ <div class="paragraph">
+ <p>With all that said, let’s look in detail at the testing features provided by Apache Isis.</p>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="sect1">
+ <h2 id="_ugtst_unit-test-support">3. Unit Test Support</h2>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="sectionbody">
+ <div class="paragraph">
+ <p>Isis Core provides a number of unit test helpers for you to use (if you wish) to unit test your domain objects.</p>
+ </div>
+ <div class="sect2">
+ <h3 id="_ugtst_unit-test-support_contract-tests">3.1. Contract Tests</h3>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_contract-tests.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_contract-tests.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_contract-tests.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_contract-tests.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_contract-tests.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>Contract tests ensure that all instances of a particular idiom/pattern that occur within your codebase are implemented correctly. You could think of them as being a way to enforce a certain type of coding standard. Implementation-wise they use <a href="https://code.google.com/p/reflections/">Reflections</a> library to scan for classes.</p>
+ </div>
+ <div class="sect3">
+ <h4 id="__code_sortedset_code_s">3.1.1. <code>SortedSet</code>s</h4>
+ <div class="paragraph">
+ <p>This contract test automatically checks that all fields of type <code>java.util.Collection</code> are declared as <code>java.util.SortedSet</code>. In other words, it precludes either <code>java.util.List</code> or <code>java.util.Set</code> from being used as a collection.</p>
+ </div>
+ <div class="paragraph">
+ <p>For example, the following passes the contract test:</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">Department</span> {
+ <span class="directive">private</span> <span class="predefined-type">SortedSet</span><Employee> employees = <span class="keyword">new</span> <span class="predefined-type">TreeSet</span><Employee>();
+ ...
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>whereas this would not:</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">SomeDomainObject</span> {
+ <span class="directive">private</span> <span class="predefined-type">List</span><Employee> employees = <span class="keyword">new</span> <span class="predefined-type">ArrayList</span><Employee>();
+ ...
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>If using DataNucleus against an RDBMS (as you probably are) then we strongly recommend that you implement this test, for several reasons:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>first, <code>Set</code>s align more closely to the relational model than do <code>List</code>s. A <code>List</code> must have an additional index to specify order.</p> </li>
+ <li> <p>second, <code>SortedSet</code> is preferable to <code>Set</code> because then the order is well-defined and predictable (to an end user, to the programmer).<br></p>
+ <div class="paragraph">
+ <p>The <a href="../rgcms/rgcms.html#_rgcms_classes_utility_ObjectContracts"><code>ObjectContracts</code></a> utility class substantially simplifies the task of implementing <code>Comparable</code> in your domain classes.</p>
+ </div> </li>
+ <li> <p>third, if the relationship is bidirectional then JDO/Objectstore will automatically maintain the relationship.</p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>To use the contract test, subclass <code>SortedSetsContractTestAbstract</code>, specifying the root package to search for domain classes.</p>
+ </div>
+ <div class="paragraph">
+ <p>For example:</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">SortedSetsContractTestAll</span> <span class="directive">extends</span> SortedSetsContractTestAbstract {
+
+ <span class="directive">public</span> SortedSetsContractTestAll() {
+ <span class="local-variable">super</span>(<span class="string"><span class="delimiter">"</span><span class="content">org.estatio.dom</span><span class="delimiter">"</span></span>);
+ withLoggingTo(<span class="predefined-type">System</span>.out);
+ }
+}</code></pre>
+ </div>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_bidirectional">3.1.2. Bidirectional</h4>
+ <div class="paragraph">
+ <p>This contract test automatically checks that bidirectional 1:m or 1:1 associations are being maintained correctly (assuming that they follow the <a href="../ugfun/ugfun.html#_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships">mutual registration pattern</a></p>
+ </div>
+ <div class="admonitionblock tip">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>(If using the JDO objectstore, then) there is generally no need to programmatically maintain 1:m relationships (indeed it may introduce subtle errors). For more details, see <a href="../ugfun/ugfun.html#_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships">here</a>. Also check out the templates in the developers' guide (<a href="../dg/dg.html#<em>dg_ide_intellij_live-templates">live templates for IntelliJ</a> / <a href="../dg/dg.html#</em>dg_ide_eclipse_editor-templates">editor templates for Eclipse</a>) for further guidance.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>For example, suppose that <code>ParentDomainObject</code> and <code>ChildDomainObject</code> have a 1:m relationship (<code>ParentDomainObject#children</code> / <code>ChildDomainObject#parent</code>), and also <code>PeerDomainObject</code> has a 1:1 relationship with itself (<code>PeerDomainObject#next</code> / <code>PeerDomainObject#previous</code>).</p>
+ </div>
+ <div class="paragraph">
+ <p>The following will exercise these relationships:</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">BidirectionalRelationshipContractTestAll</span>
+ <span class="directive">extends</span> BidirectionalRelationshipContractTestAbstract {
+
+ <span class="directive">public</span> BidirectionalRelationshipContractTestAll() {
+ <span class="local-variable">super</span>(<span class="string"><span class="delimiter">"</span><span class="content">org.apache.isis.core.unittestsupport.bidir</span><span class="delimiter">"</span></span>,
+ ImmutableMap.<<span class="predefined-type">Class</span><?>,Instantiator>of(
+ ChildDomainObject.class, <span class="keyword">new</span> InstantiatorForChildDomainObject(),
+ PeerDomainObject.class, <span class="keyword">new</span> InstantiatorSimple(PeerDomainObjectForTesting.class)
+ ));
+ withLoggingTo(<span class="predefined-type">System</span>.out);
+ }
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>The first argument to the constructor scopes the search for domain objects; usually this would be something like <code>"com.mycompany.dom"</code>.</p>
+ </div>
+ <div class="paragraph">
+ <p>The second argument provides a map of <code>Instantiator</code> for certain of the domain object types. This has two main purposes. First, for abstract classes, it nominates an alternative concrete class to be instantiated. Second, for classes (such as <code>ChildDomainObject</code>) that are <code>Comparable</code> and are held in a <code>SortedSet</code>), it provides the ability to ensure that different instances are unique when compared against each other. If no <code>Instantiator</code> is provided, then the contract test simply attempts to instantiates the class.</p>
+ </div>
+ <div class="paragraph">
+ <p>If any of the supporting methods (<code>addToXxx()</code>, <code>removeFromXxx()</code>, <code>modifyXxx()</code> or <code>clearXxx()</code>) are missing, the relationship is skipped.</p>
+ </div>
+ <div class="paragraph">
+ <p>To see what’s going on (and to identify any skipped relationships), use the <code>withLoggingTo()</code> method call. If any assertion fails then the error should be descriptive enough to figure out the problem (without enabling logging).</p>
+ </div>
+ <div class="paragraph">
+ <p>The example tests can be found <a href="https://github.com/apache/isis/tree/master/core/unittestsupport/src/test/java/org/apache/isis/core/unittestsupport/bidir">here</a>.</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_injected_services_method">3.1.3. Injected Services Method</h4>
+ <div class="paragraph">
+ <p>It is quite common for some basic services to be injected in a project-specific domain object superclass; for example a <code>ClockService</code> might generally be injected everywhere:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">abstract</span> <span class="type">class</span> <span class="class">EstatioDomainObject</span> {
+ <span class="annotation">@javax</span>.inject.Inject
+ <span class="directive">protected</span> ClockService clockService;
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>If a subclass inadvertantly overrides this method and provides its own <code>ClockService</code> field, then the field in the superclass will never initialized. As you might imagine, <code>NullPointerException</code>s could then arise.</p>
+ </div>
+ <div class="paragraph">
+ <p>This contract test automatically checks that the <code>injectXxx(…)</code> method, to allow for injected services, is not overridable, ie <code>final</code>.</p>
+ </div>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>This contract test is semi-obsolete; most of the time you will want to use <code>@javax.inject.Inject</code> on fields rather than the <code>injectXxx()</code> method. The feature dates from a time before Apache Isis supported the <code>@Inject</code> annotation.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>To use the contract test, , subclass <code>SortedSetsContractTestAbstract</code>, specifying the root package to search for domain classes.</p>
+ </div>
+ <div class="paragraph">
+ <p>For example:</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">InjectServiceMethodMustBeFinalContractTestAll</span> <span class="directive">extends</span> InjectServiceMethodMustBeFinalContractTestAbstract {
+
+ <span class="directive">public</span> InjectServiceMethodMustBeFinalContractTestAll() {
+ <span class="local-variable">super</span>(<span class="string"><span class="delimiter">"</span><span class="content">org.estatio.dom</span><span class="delimiter">"</span></span>);
+ withLoggingTo(<span class="predefined-type">System</span>.out);
+ }
+}</code></pre>
+ </div>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_value_objects">3.1.4. Value Objects</h4>
+ <div class="paragraph">
+ <p>The <code>ValueTypeContractTestAbstract</code> automatically tests that a custom value type implements <code>equals()</code> and <code>hashCode()</code> correctly.</p>
+ </div>
+ <div class="paragraph">
+ <p>For example, testing JDK’s own <code>java.math.BigInteger</code> can be done as follows:</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">ValueTypeContractTestAbstract_BigIntegerTest</span> <span class="directive">extends</span> ValueTypeContractTestAbstract<<span class="predefined-type">BigInteger</span>> {
+
+ <span class="annotation">@Override</span>
+ <span class="directive">protected</span> <span class="predefined-type">List</span><<span class="predefined-type">BigInteger</span>> getObjectsWithSameValue() {
+ <span class="keyword">return</span> <span class="predefined-type">Arrays</span>.asList(<span class="keyword">new</span> <span class="predefined-type">BigInteger</span>(<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span>), <span class="keyword">new</span> <span class="predefined-type">BigInteger</span>(<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span>));
+ }
+
+ <span class="annotation">@Override</span>
+ <span class="directive">protected</span> <span class="predefined-type">List</span><<span class="predefined-type">BigInteger</span>> getObjectsWithDifferentValue() {
+ <span class="keyword">return</span> <span class="predefined-type">Arrays</span>.asList(<span class="keyword">new</span> <span class="predefined-type">BigInteger</span>(<span class="string"><span class="delimiter">"</span><span class="content">2</span><span class="delimiter">"</span></span>));
+ }
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>The example unit tests can be found <a href="https://github.com/apache/isis/tree/master/core/unittestsupport/src/test/java/org/apache/isis/core/unittestsupport/value">here</a>.</p>
+ </div>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_ugtst_unit-test-support_jmock-extensions">3.2. JMock Extensions</h3>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_jmock-extensions.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_jmock-extensions.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_jmock-extensions.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_jmock-extensions.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_jmock-extensions.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>As noted earlier, for unit tests we tend to use <a href="http://www.jmock.org">JMock</a> as our mocking library. The usual given/when/then format gets an extra step:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><strong>given</strong> the system is in this state</p> </li>
+ <li> <p><strong>expecting</strong> these interactions (set up the mock expectations here)</p> </li>
+ <li> <p><strong>when</strong> I poke it with a stick</p> </li>
+ <li> <p><strong>then</strong> these state changes and interactions with Mocks should have occurred.</p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>If using JMock then the interactions (in the "then") are checked automatically by a JUnit rule. However, you probably will still have some state changes to assert upon.</p>
+ </div>
+ <div class="admonitionblock tip">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td>
+ <td class="content">
+ <div class="title">
+ Distinguish between queries vs mutators
+ </div>
+ <div class="paragraph">
+ <p>For mock interactions that simply retrieve some data, your test should not need to verify that it occurred. If the system were to be refactored and starts caching some data, you don’t really want your tests to start breaking because they are no longer performing a query that once they did. If using JMock API this means using the <code>allowing(..)</code> method to set up the expectation.</p>
+ </div>
+ <div class="paragraph">
+ <p>On the other hand mocks that mutate the state of the system you probably should assert have occurred. If using JMock this typically means using the <code>oneOf(…)</code> method.</p>
+ </div>
+ <div class="paragraph">
+ <p>For more tips on using JMock and mocking in general, check out the <a href="http://www.growing-object-oriented-software.com/">GOOS</a> book, written by JMock’s authors, Steve Freeman and Nat Pryce and also <a href="http://natpryce.com/articles.html">Nat’s blog</a>.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>Apache Isis' unit test support provides <code>JUnitRuleMockery2</code> which is an extension to the <a href="http://www.jmock.org/">JMock</a>'s <code>JunitRuleMockery</code>. It provides a simpler API and also providing support for autowiring.</p>
+ </div>
+ <div class="paragraph">
+ <p>For example, here we see that the class under test, an instance of <code>CollaboratingUsingSetterInjection</code>, is automatically wired up with its <code>Collaborator</code>:</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">JUnitRuleMockery2Test_autoWiring_setterInjection_happyCase</span> {
+
+ <span class="annotation">@Rule</span>
+ <span class="directive">public</span> JUnitRuleMockery2 context = JUnitRuleMockery2.createFor(Mode.INTERFACES_AND_CLASSES);
+
+ <span class="annotation">@Mock</span>
+ <span class="directive">private</span> Collaborator collaborator;
+
+ <span class="annotation">@ClassUnderTest</span>
+ <span class="directive">private</span> CollaboratingUsingSetterInjection collaborating;
+
+ <span class="annotation">@Test</span>
+ <span class="directive">public</span> <span class="type">void</span> wiring() {
+ assertThat(collaborating.collaborator, is(not(nullValue())));
+ }
+}</code></pre>
+ </div>
+ </div>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>Isis also includes (and automatically uses) a <a href="http://www.javassist.org">Javassist</a>-based implementation of JMock’s <a href="http://www.jmock.org/mocking-classes.html"><code>ClassImposteriser</code></a> interface, so that you can mock out concrete classes as well as interfaces. We’ve provided this rather than JMock’s own cglib-based implementation (which is problematic for us given its own dependencies on <a href="http://asm.ow2.org/">asm</a>).</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>The example tests can be found <a href="https://github.com/apache/isis/tree/master/core/unittestsupport/src/test/java/org/apache/isis/core/unittestsupport/jmocking">here</a></p>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_ugtst_unit-test-support_soap-fake-server-junit-rule">3.3. SOAP Fake Endpoints</h3>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_soap-fake-server-junit-rule.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_soap-fake-server-junit-rule.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_soap-fake-server-junit-rule.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_soap-fake-server-junit-rule.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_soap-fake-server-junit-rule.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <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>
+ <tbody>
+ <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://platform.incode.org" target="_blank">Incode Platform</a>'s publishmq 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>
+ </tbody>
+ </table>
+ </div>
+ <div class="sect3">
+ <h4 id="__code_soapendpointpublishingrule_code">3.3.1. <code>SoapEndpointPublishingRule</code></h4>
+ <div class="paragraph">
+ <p>The idea behind this rule is that you write a fake server endpoint 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 and gets the rule to instantiate and publish that fake server endpoint, and then obtains a reference to that server endpoint. It also instantiates the SOAP client, pointing it at the address (that is, a URL) that the fake server endpoint is running on. This way the unit test has control of both the SOAP client and server: the software under test and its collaborator.</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 fake server endpoints onto a thread-local. Therefore the unit tests should clear up any state on the fake server endpoints.</p>
+ </div>
+ <div class="paragraph">
+ <p>Your unit test uses the rule by specifying the endpoint class (must have a no-arg constructor):</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">FakeExternalSystemEndpointRuleTest</span> {
+ <span class="annotation">@Rule</span>
+ <span class="directive">public</span> SoapEndpointPublishingRule serverRule =
+ <span class="keyword">new</span> SoapEndpointPublishingRule(FakeExternalSystemEndpoint.class); <i class="conum" data-value="1"></i><b>(1)</b>
+ <span class="directive">private</span> FakeExternalSystemEndpoint fakeServerEndpoint;
+ <span class="directive">private</span> DemoObject externalSystemContract; <i class="conum" data-value="2"></i><b>(2)</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> {
+ fakeServerEndpoint =
+ serverRule.getEndpointImplementor(FakeExternalSystemEndpoint.class); <i class="conum" data-value="3"></i><b>(3)</b>
+ <span class="directive">final</span> <span class="predefined-type">String</span> endpointAddress =
+ serverRule.getEndpointAddress(FakeExternalSystemEndpoint.class); <i class="conum" data-value="4"></i><b>(4)</b>
+ <span class="directive">final</span> DemoObjectService externalSystemService = <i class="conum" data-value="5"></i><b>(5)</b>
+ <span class="keyword">new</span> DemoObjectService(ExternalSystemWsdl.getWsdl()); <i class="conum" data-value="6"></i><b>(6)</b>
+ externalSystemContract = externalSystemService.getDemoObjectOverSOAP();
+ BindingProvider provider = (BindingProvider) externalSystemContract;
+ provider.getRequestContext().put(
+ BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
+ endpointAddress)
+ );
+ }
+ <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="7"></i><b>(7)</b>
+ ...
+ <span class="comment">// expect</span>
+ final UpdateResponse response = <span class="keyword">new</span> UpdateResponse(); <i class="conum" data-value="8"></i><b>(8)</b>
+ ...
+ fakeServerEndpoint.control().setResponse(updateResponse);
+ <span class="comment">// when</span>
+ PostResponse response = externalSystemContract.post(update); <i class="conum" data-value="9"></i><b>(9)</b>
+ <span class="comment">// then</span>
+ <span class="directive">final</span> <span class="predefined-type">List</span><Update> updates = <i class="conum" data-value="10"></i><b>(10)</b>
+ fakeServerEndpoint.control().getUpdates();
+ ...
+ }
+}</code></pre>
+ </div>
+ </div>
+ <div class="colist arabic">
+ <table>
+ <tbody>
+ <tr>
+ <td><i class="conum" data-value="1"></i><b>1</b></td>
+ <td>specify the class that implements the endpoint (must have a no-arg constructor)</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="2"></i><b>2</b></td>
+ <td>the SOAP contract as defined in WSDL and generated by wsdl2java</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="3"></i><b>3</b></td>
+ <td>get hold of the fake server-side endpoint from the rule…</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="4"></i><b>4</b></td>
+ <td>… and its endpoint address</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="5"></i><b>5</b></td>
+ <td>use factory (also generated by wsdl2java) to create client-side endpoint</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="6"></i><b>6</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="7"></i><b>7</b></td>
+ <td>create a request object in order to invoke the SOAP web service</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="8"></i><b>8</b></td>
+ <td>instruct the fake server endpoint how to respond</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="9"></i><b>9</b></td>
+ <td>invoke the web service</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="10"></i><b>10</b></td>
+ <td>check the fake server endpoint was correctly invoked etc.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>The rule can also host multiple endpoints; just provide multiple classes in the constructor:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Rule</span>
+<span class="directive">public</span> SoapEndpointPublishingRule serverRule =
+ <span class="keyword">new</span> SoapEndpointPublishingRule(
+ FakeCustomersEndpoint.class,
+ FakeOrdersEndpoint.class,
+ FakeProductsEndpoint.class);</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>To lookup a particular endpoint, specify its type:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java">FakeProductsEndpoint fakeProductsServerEndpoint =
+ serverRule.getPublishedEndpoint(FakeProductsEndpoint.class);</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>The endpoint addresses that the server endpoints run on are determined automatically. If you want more control, then you can call one of <code>SoapEndpointPublishingRule</code>'s overloaded constructors, passing in one or more <code>SoapEndpointSpec</code> instances.</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_xml_marshalling_support">3.3.2. XML Marshalling Support</h4>
+ <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="sect2">
+ <h3 id="_ugtst_unit-test-support_maven-configuration">3.4. Maven Configuration</h3>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_maven-configuration.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_maven-configuration.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_maven-configuration.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_maven-configuration.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_maven-configuration.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>Apache Isis' unit test support is automatically configured if you use the <a href="../ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype">HelloWorld</a> or the <a href="../ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp</a> archetypes. To set it up manually, update the <code>pom.xml</code> of your domain object model module:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><dependency></span>
+ <span class="tag"><groupId></span>org.apache.isis.core<span class="tag"></groupId></span>
+ <span class="tag"><artifactId></span>isis-core-unittestsupport<span class="tag"></artifactId></span>
+ <span class="tag"><scope></span>test<span class="tag"></scope></span> <i class="conum" data-value="1"></i><b>(1)</b>
+<span class="tag"></dependency></span></code></pre>
+ </div>
+ </div>
+ <div class="colist arabic">
+ <table>
+ <tbody>
+ <tr>
+ <td><i class="conum" data-value="1"></i><b>1</b></td>
+ <td>Normally <code>test</code>; usual Maven scoping rules apply.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>(As of <code>1.15.0</code>) this can also be done by adding a dependency to <code>org.apache.isis.mavendeps:isis-mavendeps-testing</code> module; see the <a href="../ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp archetype</a>.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>We also recommend that you configure the <code>maven-surefire-plugin</code> to pick up the following class patterns:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><plugin></span>
+ <span class="tag"><groupId></span>org.apache.maven.plugins<span class="tag"></groupId></span>
+ <span class="tag"><artifactId></span>maven-surefire-plugin<span class="tag"></artifactId></span>
+ <span class="tag"><version></span>2.10<span class="tag"></version></span>
+ <span class="tag"><configuration></span>
+ <span class="tag"><includes></span>
+ <span class="tag"><include></span>**/*Test.java<span class="tag"></include></span>
+ <span class="tag"><include></span>**/*Test_*.java<span class="tag"></include></span>
+ <span class="tag"><include></span>**/*Spec*.java<span class="tag"></include></span>
+ <span class="tag"></includes></span>
+ <span class="tag"><excludes></span>
+ <span class="tag"><exclude></span>**/Test*.java<span class="tag"></exclude></span>
+ <span class="tag"><exclude></span>**/*ForTesting.java<span class="tag"></exclude></span>
+ <span class="tag"><exclude></span>**/*Abstract*.java<span class="tag"></exclude></span>
+ <span class="tag"></excludes></span>
+ <span class="tag"><useFile></span>true<span class="tag"></useFile></span>
+ <span class="tag"><printSummary></span>true<span class="tag"></printSummary></span>
+ <span class="tag"><outputDirectory></span>${project.build.directory}/surefire-reports<span class="tag"></outputDirectory></span>
+ <span class="tag"></configuration></span>
+<span class="tag"></plugin></span></code></pre>
+ </div>
+ </div>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>As of <code>1.14.0</code> this can also be done using mavenmixins; see the <a href="../ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp archetype</a>.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="sect1">
+ <h2 id="_ugtst_integ-test-support">4. Integration Test Support</h2>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="sectionbody">
+ <div class="paragraph">
+ <p>As discussed in the introductory overview of this chapter, Apache Isis allows you to integration test your domain objects from within JUnit. There are several parts to this:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>configuring the Apache Isis runtime so it can be bootstrapped (mostly boilerplate)</p> </li>
+ <li> <p>defining a base class to perform said bootstrapping</p> </li>
+ <li> <p>using fixture scripts to set up the app</p> </li>
+ <li> <p>using <code>WrapperFactory</code> so that the UI can be simulated.</p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>We’ll get to all that shortly, but let’s start by taking a look at what a typical integration test looks like.</p>
+ </div>
+ <div class="sect2">
+ <h3 id="_ugtst_integ-test-support_typical-usage">4.1. Typical Usage</h3>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_typical-usage.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_typical-usage.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_typical-usage.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_typical-usage.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_typical-usage.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>This example adapted from the <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a> (non-ASF). The code we want to test (simplified) is:</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">ToDoItem</span> ... {
+
+ <span class="directive">private</span> <span class="type">boolean</span> complete;
+ <span class="annotation">@Property</span>( editing = Editing.DISABLED )
+ <span class="directive">public</span> <span class="type">boolean</span> isComplete() {
+ <span class="keyword">return</span> complete;
+ }
+ <span class="directive">public</span> <span class="type">void</span> setComplete(<span class="directive">final</span> <span class="type">boolean</span> complete) {
+ <span class="local-variable">this</span>.complete = complete;
+ }
+
+ <span class="annotation">@Action</span>()
+ <span class="directive">public</span> ToDoItem completed() {
+ setComplete(<span class="predefined-constant">true</span>);
+ ...
+ return <span class="local-variable">this</span>;
+ }
+ <span class="directive">public</span> <span class="predefined-type">String</span> disableCompleted() {
+ <span class="keyword">return</span> isComplete() ? <span class="string"><span class="delimiter">"</span><span class="content">Already completed</span><span class="delimiter">"</span></span> : <span class="predefined-constant">null</span>;
+ }
+ ...
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>We typically put the bootstrapping of Apache Isis into a superclass (<code>AbstractToDoIntegTest</code> below), then subclass as required.</p>
+ </div>
+ <div class="paragraph">
+ <p>For this test (of the "completed()" action) we need an instance of a <code>ToDoItem</code> that is not yet complete. Here’s the setup:</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">ToDoItemIntegTest</span> <span class="directive">extends</span> AbstractToDoIntegTest {
+
+ <span class="annotation">@Inject</span>
+ FixtureScripts fixtureScripts; <i class="conum" data-value="1"></i><b>(1)</b>
+ <span class="annotation">@Inject</span>
+ ToDoItems toDoItems; <i class="conum" data-value="2"></i><b>(2)</b>
+ ToDoItem toDoItem; <i class="conum" data-value="3"></i><b>(3)</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> {
+ RecreateToDoItemsForCurrentUser fixtureScript = <i class="conum" data-value="4"></i><b>(4)</b>
+ <span class="keyword">new</span> RecreateToDoItemsForCurrentUser();
+ fixtureScripts.runFixtureScript(fixtureScript, <span class="predefined-constant">null</span>);
+ <span class="directive">final</span> <span class="predefined-type">List</span><ToDoItem> all = toDoItems.notYetComplete(); <i class="conum" data-value="5"></i><b>(5)</b>
+ toDoItem = wrap(all.get(<span class="integer">0</span>)); <i class="conum" data-value="6"></i><b>(6)</b>
+ }
+ ...
+}</code></pre>
+ </div>
+ </div>
+ <div class="colist arabic">
+ <table>
+ <tbody>
+ <tr>
+ <td><i class="conum" data-value="1"></i><b>1</b></td>
+ <td>the <a href="../rgcms/rgcms.html#_rgcms_classes_super_FixtureScripts"><code>FixtureScripts</code></a> domain service is injected, providing us with the ability to run fixture scripts</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="2"></i><b>2</b></td>
+ <td>likewise, an instance of the <code>ToDoItems</code> domain service is injected. We’ll use this to lookup…</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="3"></i><b>3</b></td>
+ <td>the object under test, hel
<TRUNCATED>