svn commit: r1490229 - /isis/site/trunk/content/core/unittestsupport.md

[da...@apache.org]

Author: danhaywood
Date: Thu Jun  6 10:24:30 2013
New Revision: 1490229

URL: http://svn.apache.org/r1490229
Log:
page on unit test support

Modified:
    isis/site/trunk/content/core/unittestsupport.md

Modified: isis/site/trunk/content/core/unittestsupport.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/core/unittestsupport.md?rev=1490229&r1=1490228&r2=1490229&view=diff
==============================================================================
--- isis/site/trunk/content/core/unittestsupport.md (original)
+++ isis/site/trunk/content/core/unittestsupport.md Thu Jun  6 10:24:30 2013
@@ -4,12 +4,10 @@ This module provides unit test helpers f
 
 To use, update the `pom.xml`:
 
-<pre>
     &lt;dependency&gt;
         &lt;groupId&gt;org.apache.isis.core&lt;/groupId&gt;
         &lt;artifactId&gt;isis-core-unittestsupport&lt;/artifactId&gt;
     &lt;/dependency&gt;
-</pre>
 
 
 ##Bidirectional Contract Tests [1.3.0-SNAPSHOT]
@@ -24,25 +22,26 @@ For example, suppose that `ParentDomainO
 
 The following will exercise these relationships:
 
-<pre>
-public class BidirectionalRelationshipContractTestAll extends BidirectionalRelationshipContractTestAbstract {
-
-    public BidirectionalRelationshipContractTestAll() {
-        super("org.apache.isis.core.unittestsupport.bidir", 
-                ImmutableMap.<Class<?>,Instantiator>of(
-                    // no instantiator need be registered for ParentDomainObject.class; 
-                    // will default to using new InstantiatorSimple(AgreementForTesting.class),
-                    ChildDomainObject.class, new InstantiatorForChildDomainObject(),
-                    PeerDomainObject.class, new InstantiatorSimple(PeerDomainObjectForTesting.class)
-                ));
-        withLoggingTo(System.out);
+    public class BidirectionalRelationshipContractTestAll
+            extends BidirectionalRelationshipContractTestAbstract {
+    
+        public BidirectionalRelationshipContractTestAll() {
+            super("org.apache.isis.core.unittestsupport.bidir", 
+                    ImmutableMap.<Class<?>,Instantiator>of(
+                        ChildDomainObject.class, new InstantiatorForChildDomainObject(),
+                        PeerDomainObject.class, new InstantiatorSimple(PeerDomainObjectForTesting.class)
+                    ));
+            withLoggingTo(System.out);
+        }
     }
-}
-</pre>
 
-As you can see, for some of the types an `Instantiator` must be provided.  This has two main purposes.  First, for abstract classes, it nominates an alternative concrete class to be instantiated.  Second, for classes (such as `ChildDomainObject`) that are `Comparable` and are held in a `SortedSet`), it provides the ability to ensure that different instances are unique when compared against each other.
+The first argument to the constructor scopes the search for domain objects; usually this would be something like `"com.mycompany.dom"`.
 
-So you can see what's going on, this will log all tests to `System.out`.  This can be disabled by removing the call to `withLoggingTo()`.
+The second argument provides a map of `Instantiator` 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 `ChildDomainObject`) that are `Comparable` and are held in a `SortedSet`), it provides the ability to ensure that different instances are unique when compared against each other.  If no `Instantiator` is provided, then the contract test simply attempts to instantiates the class.
+
+If any of the supporting methods (`addToXxx()`, `removeFromXxx()`, `modifyXxx()` or `clearXxx()`) are missing, the relationship is skipped.
+
+To see what's going on (and to identify any skipped relationships), use the `withLoggingTo()` method call.  If any assertion fails then the error should be descriptive enough to figure out the problem (without enabling logging).
 
 The example tests can be found [here](https://github.com/apache/isis/tree/master/core/unittestsupport/src/test/java/org/apache/isis/core/unittestsupport/bidir).
 
@@ -52,29 +51,27 @@ An extension to the JMock's `JunitRuleMo
 
 For example, here we see that the class under test, an instance of `CollaboratingUsingSetterInjection`, is automatically wired up with its `Collaborator`:
 
-<pre>
-public class JUnitRuleMockery2Test_autoWiring_setterInjection_happyCase {
-
-    @Rule
-    public JUnitRuleMockery2 context = JUnitRuleMockery2.createFor(Mode.INTERFACES_AND_CLASSES);
-
-    @Mock
-    private Collaborator collaborator;
-
-    @ClassUnderTest
-    private CollaboratingUsingSetterInjection collaborating;
-
-    @Before
-    public void setUp() throws Exception {
-    	collaborating = context.getClassUnderTest();
-    }
+    public class JUnitRuleMockery2Test_autoWiring_setterInjection_happyCase {
+    
+        @Rule
+        public JUnitRuleMockery2 context = JUnitRuleMockery2.createFor(Mode.INTERFACES_AND_CLASSES);
     
-    @Test
-    public void wiring() {
-    	assertThat(collaborating.collaborator, is(not(nullValue())));
+        @Mock
+        private Collaborator collaborator;
+    
+        @ClassUnderTest
+        private CollaboratingUsingSetterInjection collaborating;
+    
+        @Before
+        public void setUp() throws Exception {
+        	collaborating = context.getClassUnderTest();
+        }
+        
+        @Test
+        public void wiring() {
+        	assertThat(collaborating.collaborator, is(not(nullValue())));
+        }
     }
-}
-</pre>
 
 
 The example tests can be found [here](https://github.com/apache/isis/tree/master/core/unittestsupport/src/test/java/org/apache/isis/core/unittestsupport/jmocking)
@@ -85,20 +82,17 @@ Automatically tests that a custom value 
 
 For example, testing JDK's own `java.math.BigInteger` can be done as follows:
 
-<pre>
-public class ValueTypeContractTestAbstract_BigIntegerTest extends ValueTypeContractTestAbstract<BigInteger> {
-
-    @Override
-    protected List<BigInteger> getObjectsWithSameValue() {
-        return Arrays.asList(new BigInteger("1"), new BigInteger("1"));
-    }
-
-    @Override
-    protected List<BigInteger> getObjectsWithDifferentValue() {
-        return Arrays.asList(new BigInteger("2"));
+    public class ValueTypeContractTestAbstract_BigIntegerTest extends ValueTypeContractTestAbstract<BigInteger> {
+    
+        @Override
+        protected List<BigInteger> getObjectsWithSameValue() {
+            return Arrays.asList(new BigInteger("1"), new BigInteger("1"));
+        }
+    
+        @Override
+        protected List<BigInteger> getObjectsWithDifferentValue() {
+            return Arrays.asList(new BigInteger("2"));
+        }
     }
 
-}
-</pre>
-
 The example unit tests can be found [here](https://github.com/apache/isis/tree/master/core/unittestsupport/src/test/java/org/apache/isis/core/unittestsupport/value).