Testing

This contract test automatically checks that all fields of type java.util.Collection are declared as java.util.SortedSet. In other words, it precludes either java.util.List or java.util.Set from being used as a collection.

For example, the following passes the contract test:

whereas this would not:

If using DataNucleus against an RDBMS (as you probably are) then we strongly recommend that you implement this test, for several reasons:

To use the contract test, subclass SortedSetsContractTestAbstract, specifying the root package to search for domain classes.

For example:

This contract test automatically checks that bidirectional 1:m or 1:1 associations are being maintained correctly (assuming that they follow the mutual registration pattern

For example, suppose that ParentDomainObject and ChildDomainObject have a 1:m relationship (ParentDomainObject#children / ChildDomainObject#parent), and also PeerDomainObject has a 1:1 relationship with itself (PeerDomainObject#next / PeerDomainObject#previous).

The following will exercise these relationships:

The first argument to the constructor scopes the search for domain objects; usually this would be something like "com.mycompany.dom".

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.

It is quite common for some basic services to be injected in a project-specific domain object superclass; for example a ClockService might generally be injected everywhere:

If a subclass inadvertantly overrides this method and provides its own ClockService field, then the field in the superclass will never initialized. As you might imagine, NullPointerExceptions could then arise.

This contract test automatically checks that the injectXxx(…​) method, to allow for injected services, is not overridable, ie final.

To use the contract test, , subclass SortedSetsContractTestAbstract, specifying the root package to search for domain classes.

For example:

The ValueTypeContractTestAbstract automatically tests that a custom value type implements equals() and hashCode() correctly.

For example, testing JDK’s own java.math.BigInteger can be done as follows:

The example unit tests can be found here.

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.

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.

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.

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.

Your unit test uses the rule by specifying the endpoint class (must have a no-arg constructor):

The rule can also host multiple endpoints; just provide multiple classes in the constructor:

To lookup a particular endpoint, specify its type:

The endpoint addresses that the server endpoints run on are determined automatically. If you want more control, then you can call one of SoapEndpointPublishingRule's overloaded constructors, passing in one or more SoapEndpointSpec instances.

Apache Isis' unit testing support also provides helper JaxbUtil and JaxbMatchers 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.

In 1.15.0 the bootstrapping is accomplished using a combination of AppManifestAbstract (a framework-provided implementation of AppManifest) and IntegrationTestAbstract2 superclass.

For example, the SimpleApp archetype's integration tests all inherit from this class:

where DomainAppAppManifest in turn is:

The AppManifestAbstract class (which is also used to bootstrap the regular app as well as integration tests) is discussed further here, while the IntegrationTestAbstract2 class is discussed further here.

In 1.13.0 the bootstrapping itself is typically performed by a "system initializer" class. This is responsible for instantiating the Apache Isis runtime (based on a provided AppManifest) and binding it to a thread-local.

The AppManifest.Util class allows configuration properties for integration testing to be defined (replacing the IsisConfigurationForJdoIntegTests of earlier releases).

For example:

The above code uses the AppManifest.Util helper class, which provides a number of static methods that can be used to set up configuration properties appropriate for integration testing (eg run using an in-memory database). This allows the responsibility of returning the configuration properties to belong exclusively to the AppManifest.

There are three such static methods:

In 1.9.0 the AppManifest was introduced as mechanism to specify all parts (domain code, framework components, configuation properties) that make up a running application.

The suggested way to use this concept was using a "system initializer" class. This uses a IsisConfigurationForJdoIntegTests class to bring together the configuration properties (discussed further here) to bootstrap the application.

For example:

where DomainAppAppManifest in turn is defined as:

Further details on bootstrapping with the AppManifest can be found in the reference guide.

Prior to 1.9.0, the services and entities had to be specified in two separate locations. The suggested way to do this was to introduce a subclass of the IsisSystemForTest.Builder class:

This builder could then be used within the system initializer:

(As of 1.15.0) we recommend that your integration tests inherit from Apache Isis' IntegrationTestAbstract2 class:

Although not mandatory, this provides a number of helper/convenience methods and JUnit rules:

All of these rules could be inlined in your own base class; as we say, they are a convenience.

The IntegrationTestAbstract2 also provides a number of helper/convenience methods, though most of these have been deprecated because the functionality they expose is now readily accessible through various domain services; most notably these are:

For earlier releases we recommend that your base class inherit from Apache Isis' IntegrationTestAbstract class:

This provides most of the benefits of IntegrationTestAbstract2 (it is the latter’s superclass, in fact), but the bootstrapping is more verbose.

Wrapping a domain object is very straightforward; simply call WrapperFactory#wrap(…​).

For example:

Going the other way — getting hold of the underlying (wrapped) domain object — is just as easy; just call WrapperFactory#unwrap(…​).

For example:

If you prefer, you also can get the underlying object from the wrapper itself, by downcasting to WrappingObject and calling __isis_wrapped() method:

We’re not sure that’s any easier (in fact we’re certain it looks rather obscure). Stick with calling unwrap(…​)!

As the wrapper is intended to simulate the UI, only those methods that correspond to the "primary" methods of the domain object’s members are allowed to be called. That means:

As a convenience, we also allow the test to call any default…​(),choices…​() or autoComplete…​() method. These are often useful for obtaining a valid value to use.

What the test can’t call is any of the remaining supporting methods, such as hide…​(), disable…​() or validate…​(). That’s because their value is implied by the exception being thrown.

The wrapper does also allow the object’s title() method or its toString() , however this is little use for objects whose title is built up using the @Title annotation. Instead, we recommend that your test verifies an object’s title by calling DomainObjectContainer#titleOf(…​) method.

As well as enforcing business rules, the wrapper has another important feature, namely that it will cause domain events to be fired.

For example, if we have an action annotated with @Action(domainEvent=…​):

then invoking the action through the proxy will cause the event (CompletedEvent above) to be fired to any subscribers. A test might therefore look like:

The wrapper will also fire domain events for properties (if annotated with @Property(domainEvent=…​)) or collections (if annotated with @Collection(domainEvent=…​)).

The IsisSystemForTest class allows a complete running instance of Apache Isis to be bootstrapped (with the JDO objectstore); this is then held on a a ThreadLocal from one test to another.

Typically bootstrapping code is used to lazily instantiate the IsisSystemForTest once and once only. The mechanism for doing this is line-for-line identical in both BDD step defs and integration tests.

The ScenarioExecution provides a context for a scenario that is being executed. It is Cucumber that determines which step definitions are run, and in which order, and so state cannot be passed between step definitions using local variables or instance variables. Instead the ScenarioExecution acts like a hashmap, allowing each step to put data (eg "given an uncompleted todoitem") into the map or get data ("when I complete the todoitem") from the map. This is done using the putVar(…​) and getVar(…​) methods.

The ScenarioExecution also provids access to the configured domain services (using the service(…​) method) and the DomainObjectContainer (through the container() method).

Like the IsisSystemForTest class, the ScenarioExecution class binds an instance of itself onto a ThreadLocal. It can then be accessed in BDD step definitions using ScenarioExecution.current() static method.

As with integration tests, the UI can be simulated by "wrapping" each domain object in a proxy using the WrapperFactory.

The CukeGlueAbstract acts as a convenience superclass for writing BDD step definitions (analogous to the IntegrationTestAbstract for integation tests). Underneath the covers it delegates to an underlying ScenarioExecution.

There are two ways in which you can provide a FixtureScripts service.

The original (pre-1.9.0) approach is to subclass subclass FixtureScripts domain service, with your subclass specifying which package to search for. Various other settings can also be provided, and - being a custom class - you can also add in additional actions. A common example is to provide a "one-shot" action to recreate a standard demo set of objects.

As of 1.9.0 there is an alternative design. Instead of subclassing FixtureScripts you instead implement the FixtureScriptsSpecificationProvider SPI. (As its name suggests), this provides a FixtureScriptsSpecification object that contains the same information as would otherwise have been in the FixtureScripts subclass.

The actual implementation of the FixtureScripts service is then provided by the framework itself, namely the FixtureScriptsDefault domain service, annotated to be rendered on the secondary "Prototyping" menu. This uses the FixtureScriptsSpecificationProvider to adjust itself accordinly.

For example, here’s the FixtureScriptsSpecificationProvider service that’s generated by the SimpleApp archetype:

The benefit of this design - decoupling the responsibilities of the superclass and the subclass - is that it ensures that there is always an instance of FixtureScripts available, even if the application itself doesn’t provide one. .

By way of comparison, if using the older pre-1.9.0 approach then you would create a subclass:

This isn’t quite equivalent; you would need to write additional code to support the "recreate objects and return first" action, for example.

Either way, here’s how the domain service looks like in the UI:

and here’s what the runFixtureScript action prompt looks like:

when this is executed, the resultant objects (actually, instances of FixtureResult`) are shown in the UI:

If you had defined many fixture scripts then a drop-down might become unwieldy, in which case your code would probably override the autoComplete…​()) instead:

You are free, of course, to add additional "convenience" actions into it if you wish for the most commonly used/demo’d setups ; you’ll find that the SimpleApp archetype adds this additional action:

Let’s now look at the FixtureScript class, where there’s a bit more going on.

A fixture script is ultimately just a block of code that can be executed, so it’s up to you how you implement it to set up the system. However, we strongly recommend that you use it to invoke actions on business objects, in essence to replay what a real-life user would have done. That way, the fixture script will remain valid even if the underlying implementation of the system changes in the future.

Here’s the RecreateSimpleObjects fixture script from the SimpleApp archetype:

Because this script has exposed a "number" property, it’s possible to set this from within the UI. For example:

When this is executed, the framework will parse the text and attempt to reflectively set the corresponding properties on the fixture result. So, in this case, when the fixture script is executed we actually get 6 objects created:

It’s commonplace for one fixture script to call another. In the above example this script called SimpleObjectsTearDown and SimpleObjectCreate. Let’s take a quick look at SimpleObjectCreate:

Fixture scripts can be called from integration tests just the same way that fixture scripts can call one another.

For example, here’s an integration test from the SimpleApp archetype:

There are lots of ways to organize fixture scripts, but we’ve used them as either:

These two styles are probably best illustrated with, well, some illustrations. Here’s a fixture script in the "flat" style for setting up a customer with some orders, a number of which has been placed:

Notice how we have a single script that’s in control of the overall process, and takes responsibility for passing data from one fixture script to the next.

Here’s a similar, simpler script, from the same fictional app, to set up two customers:

We can reuse the same fixture "customer" script, either calling it twice or (perhaps better) passing it an array of customer details to set up.

With the composite style, we rely on each fixture script to set up its own prerequisites. Thus:

Back in the earlier section we noted the MultipleExecutionStrategy setting. We can now explain the meaning of this: the enum value of EXECUTE is designed for the flat style (where every fixture script will be called), whereas the enum value of IGNORE is designed for the composite style, and ensures that any fixture scripts visited more than once (eg TearDown) are only every executed the first time.

As already noted , the app generated by the SimpleApp archetype uses the flat structure, and we feel that it’s a better at separating out the "how" (how we set up some graph of domain objects into a known state, eg a customer with shipped placed orders and a newly placed order) from the "what" (what data should we actually use for the customer’s name, say).

The composite style tends to combine these, which one could argue does not separate responsibilities well enough. On the other hand, one could also make an argument that the composite style is a good way to implement precanned personas, eg "Joe", the customer who has a newly placed order, from "Mary" customer who has none.