ObMimic 1.0 Released

22 08 2014

Release 1.0 of ObMimic is now available from OpenBrace Limited.

ObMimic is a library of ready-made test-doubles for the Servlet API. It provides fully-configurable plain-Java implementations of Servlet API objects for use in out-of-container testing of any code that depends on the Servlet API (including, for example, JSF pages).

You can use ObMimic to write comprehensive, detailed tests for such code, using the same tools and techniques as for normal plain-Java code – without having to deploy and run your code inside a servlet container, and without having to write your own stubs or use general-purpose mocks that rely on your own assumptions about the Servlet API’s behaviour.

At its simplest, your tests can obtain fully-functional instances of Servlet API objects using plain no-argument constructors (e.g. “new HttpServletRequestMimic()” to create an HttpServletRequest).

The main changes in this release are:

  • First full release: ObMimic is no longer in “beta”.
  • Fix to session handling: A bug in session-handling during RequestDispatcher “forwards” and “includes” has been fixed (see 16Bugs Bug #5 for details).
  • HttpServletResponseMimic.setStatus(int): By default this no longer clears the response buffer as was specified incorrectly by the Javadoc of Servlet API versions prior to 3.0 (but a new ServletContainerBehaviour option has also been added to allow explicit control over this).

For a more complete list of changes, refer to the Changes in ObMimic 1.0.000 page.

As before, the free “Community Edition” and a free (but time-limited) licence-key file for evaluation of the “Professional Edition” facilities are available for download from the ObMimic website’s Downloads / Current Release page.

In addition, “Professional Edition” licence-key files and the “Enterprise Edition” can now be purchased via the website’s Buy ObMimic Licences page.

For full details and documentation please see the ObMimic website at www.openbrace.com.

For previous posts that describe ObMimic (including some example code), see:

ObMimic 1.0 Beta 10 Released

7 11 2013

Updated August 2014: ObMimic is now out of beta, with latest version available from www.openbrace.com

Release 1.0-beta-10 of ObMimic is now available from OpenBrace Limited.

The main changes in this release are:

  • Testing of JSF pages: A “how to” guide has been added to cover testing of JSF pages, based on experiments that have demonstrated that ObMimic can be used for out-of-container testing of complete JSF pages (including full control over the ServletContext and ability to access the JSF FacesContext and API within tests).
  • Maven: A “how to” guide and “pom.xml” file have been added to aid in the use of ObMimic within Maven-based projects.
  • Listeners for Servlet API calls: Listeners can now be installed into Mimics to intercept, examine and optionally modify Servlet API calls and their results at the point where they occur, as described in an accompanying “how to” guide. In particular, this can be used as a last resort to work around any questionable Servlet API calls made by third-party code, or to overrule ObMimic’s built-in behaviour for a particular Servlet API call.

Additional changes include:

  • Any attempt to use a Java EE jar that is deliberately limited to “compile-time only” is now explicitly checked for and reported, and documentation has been updated accordingly.
  • Options have been added for configuring how the ServletContext “getResource” and “getResourceAsStream” methods behave when given “directory” paths.
  • Various minor fixes and documentation improvements.
  • ObMimic has been tested against some additional JDKs, including a JDK 8 early-access release.

For more complete details, refer to the Changes in ObMimic 1.0 Beta 10 page.

As before, the OpenBrace website provides a free download of ObMimic (including a free licence-key to unlock the “Professional Edition” features during the beta).

Note that our current intention is that this will be the last “beta” release, with the full 1.0 release to follow next.

Some more testing against different JDKs…

2 08 2013

I’ve recently added a few more JDKs into the compatibility tests of my ObMimic library, and have found a few issues that seem worth noting here.

1  JDKs Added

The specific JDKs added into the testing were:

2  Background

This isn’t a comprehensive examination of the JDKs themselves, but just tests that:

  • The ObMimic code all works correctly on all of the JDKs.
  • The Ant build script delivered as part of ObMimic’s “Enterprise Edition” can successfully build ObMimic from its source code on the Java SE 7 and higher JDKs (including running its tests and generating its Javadoc).
  • The deliverables produced by the “Enterprise Edition” build script do themselves work correctly on all of the JDKs.

For details of the other JDKs that were already included in the testing, further background information and previous findings, refer to the earlier post Some specific issues from ObMimic portability testing.

The only significant changes since that earlier post are that the tests are now run on 64-bit systems (with the Linux system now being Ubuntu 12.10); and the ObMimic “Enterprise Edition” build script is limited to Java SE 7 or higher (as it now needs Servlet 3.1, which in turn requires Java SE 7 or higher).

3  Issues Encountered

The issues encountered on the newly-added JDKs were as follows:

3.1  IBM Java SE 6 Logger doesn’t successfully look-up message keys

The java.util.logging.Logger methods that take a “msg” argument are supposed to accept a message key and look it up in a ResourceBundle to translate it into the actual message to be used (substituting given parameters into the message where applicable). This is supposed to follow the usual rules for finding the most relevant localization of the resource bundle.

There’s one ObMimic test case that relies on this, as it’s testing that a custom Handler correctly processes calls that use a message key. This test case works on all other JDKs, including IBM Java SE 5 and 7, but on IBM Java SE 6 it fails – the message key is written to the log “as is” rather than being converted into the full message from the resource bundle.

I’ve not found any definitive explanation or bug report for this, but there is a comment from “tripl3des” within a Can’t find bundle… post in an IBM discussion forum that says

“ResourceBundle implementation for IBM JDK does not respect the contract described in the API. At least not for 1.6 version…. IBM JDK only works when there is a file for the exact locale requested.”

If true, that sounds similar to what I’m encountering here (though there are other types of message look-ups throughout ObMimic that are working correctly).

The test case that fails isn’t critical to ObMimic (it’s just part of the full testing of an optional feature in some “common” code that’s bundled with ObMimic); there doesn’t appear to be anything wrong with the source code; and it all works OK on all the other JDKs.

At any rate, unless and until I learn any different I’m assuming this is just a bug in this particular JDK – and that anybody using this JDK’s java.util.logging facilities will encounter this in any logging with message keys, not just if they happen to do such logging whilst using the custom “handler” that I’m testing.

So whilst I don’t like having JDK-specific tests, in this particular case I’ve decided the most appropriate solution is to just skip this one specific test when running on IBM Java SE 6.

3.2  IBM Java SE 6 and 7 bootclasspath is more complex than just “rt.jar”

Until now, ObMimic’s “Enterprise Edition” build script has been explicitly specifying a “bootclasspath” that points to the /jre/lib/rt.jar of the JDK it’s using..

This has been done because the build’s default settings specify Java 5 as the “source” and “target” level, and javac issues a warning if these aren’t accompanied by an explicit “bootclasspath”. Explicitly supplying the “bootclasspath” doesn’t really achieve anything other than cutting out the warning message, as the build with default settings doesn’t know of any JDK other than the one it’s running on and can only specify that JDK’s own boot classes. But under the circumstances the warning is superfluous and distracting, and seemed worth cutting out.

Unfortunately, the IBM JDKs for Java 6 and 7 need more than just “rt.jar”. Some of the core Java classes (including, for example, java.lang.String) are in a separate “vm.jar”. To make matters worse, this is in different locations in IBM JDK 6 and IBM JDK 7. Then there are other necessary classes in other jars within the /jre/lib directory structure.

As a result, javac and javadoc on the IBM JDKs seem to work OK when it’s left to its own devices, but once an explicit bootclasspath is given they seem to need lots of jars from various locations within /jre/lib.

There are VM options for adding specific jars into the default bootclasspath instead of completely replacing it, and one could always configure the bootclasspath to include any and all jars within the entire /jre/lib directory structure. However, I’m not sure enough of an appropriate way to set the bootclasspath that will work for the IBM JDKs whilst also being entirely safe and appropriate for all other JDKs.

In the end I’ve modified the build script to not specify the bootclasspath at all. This re-introduces the warning message about it not being specified, but it works on all of the JDKs and is perhaps safer and more “truthful” than artificially suppressing the message.

In any case, the warning can always be avoided by changing the build properties that set the “source” and “target” levels if you don’t actually need compatibility with JDKs earlier than the one you’re building on.

3.3 Stricter Javadoc checking in JDK 8

Building the code on JDK 8 resulted in lots of Javadoc errors!

It turns out that by default Javadoc on JDK 8 carries out much stricter checking of the Javadoc content. This includes checking for incorrect HTML tags, characters that ought to be escaped/encoded, HTML attributes that are necessary for accessibility etc.

This appears to be a result of the “JDK Enhancement Proposal” JEP 172 DocLint.

In my case it found:

  • Quite a few “&” characters and a few “<” and “>” characters that needed escaping;
  • Numerous silly little mistakes in HTML tags (e.g. “<ul>” that should have been “</ul>”);
  • Some tables that were missing “summary” or “caption” attributes.

I can see this coming as a bit of a shock to many people when they switch to JDK 8 and suddenly discover that their builds fail with lots of Javadoc errors!

There’s apparently an “-Xdoclint” option that can be used to turn off some or all of the checks, but of course it makes more sense to actually fix the errors. If your Javadoc is otherwise reasonable there might be a large number of these errors, but each should be pretty trivial to fix.

It took me an hour or two to fix all of these Javadoc errors in the ObMimic code, but as always it feels good to have found and fixed these and to know that this is now checked by each Javadoc run.

3.4  A JDK 8 b99 Javadoc bug?

I also hit an apparent Javadoc bug on JDK 8 build b99 where it gives an error plus a warning for “@throws X” where “X” is a type parameter of the method (it looks like some of the Javadoc processing is taking the “X” as a class name rather than recognising it as the method’s type parameter).

However, there already seem to be JDK changes in progress that might be relevant. So for now I’m assuming this is just an early-access quirk that will get fixed in due course.

I’ve implemented a temporary (rather hacky!) work-around for the single ObMimic method affected by this, but it doesn’t seem worth going into any more detail here on the assumption that this will turn out to be a purely temporary issue.

ObMimic 1.0 Beta 9 Released

24 07 2013

Updated August 2014: ObMimic is now out of beta, with latest version available from www.openbrace.com

Release 1.0-beta-9 of ObMimic is now available from OpenBrace Limited.

The main change from the previous 1.0-beta-8 release is compatibility with Servlet 3.1 and Java EE 7 libraries, so that ObMimic can be used with such libraries.

Whilst full support for Servlet 3.0 and 3.1 features is still pending (and intended for future releases), in the meantime this at least allows ObMimic to be used in the presence of Servlet 3.1 or Java EE 7 libraries (i.e. it can now be used with any Servlet 3.1 library as well as with any Servlet 2.4, 2.5 or 3.0 library as before). This also paves the way for the gradual introduction of Servlet 3.1 support in future releases.

In addition:

  • ObMimic’s Javadoc is now supplied in Java 7 style (but including an adjustment to work-around a problem in some versions of the Eclipse IDE that render Eclipse unable to parse such Javadoc).
  • Various minor fixes, revisions and improvements have been made to ObMimic’s documentation.

As before, the OpenBrace website provides a free download of ObMimic (including a free licence-key to unlock the “Professional Edition” features during the beta).

For previous posts that describe ObMimic and show some example code, see:

ObMimic Public Beta for Out-of-Container Servlet Testing

3 06 2013

Updated August 2014: ObMimic is now out of beta, with latest version available from www.openbrace.com

ObMimic from OpenBrace Limited is a library of complete and fully-configurable plain-Java implementations of Servlet API objects for use as ready-made test-doubles in out-of-container testing of Servlet code. After a long development – and an even longer hiatus – it’s now available as a public beta release at www.openbrace.com.

You can use ObMimic to write comprehensive, detailed tests for your Servlet API code, using the same tools and techniques as for normal plain-Java code – without having to deploy and run your code inside a servlet container, and without having to write your own mocks or stubs and rely on your own assumptions about the Servlet API’s behaviour.

At its simplest, your tests can obtain fully-functional “mimic” instances of Servlet API objects using plain no-argument constructors — for example, you can create an HttpServletRequest with just:

new HttpServletRequestMimic();

Beyond that, you can configure and inspect the logical state of each such object as necessary for your tests. This includes control over details that would normally be “fixed” when running within a Servlet container (e.g. “init” parameters, Servlet API version, behaviours that are allowed to vary between containers, deliberate throwing of exceptions for testing of exception handling etc). There’s a detailed list of features on the website’s Features page.

If you want to test code that uses the Servlet API but find that detailed testing of such code is harder, more restrictive or slower than for normal Java code, ObMimic may be what you’re looking for.

The website provides a free download of ObMimic (including a free licence-key to unlock the “Professional Edition” features during the beta). The website also has a full copy of ObMimic’s documentation (including comprehensive Javadoc and a set of How To guides) and a set of discussion forums.

For some earlier posts that describe ObMimic and show some example code, see Experiments with out-of-container testing of Servlet code using ObMimic (Part 1) and First use of ObMimic for out-of-container testing of Servlets and Struts (Part 2).

ObMimic: Very, very late – but still alive

21 11 2009

Updated May 2013: It’s been a long, long hiatus, but ObMimic is now available from www.openbrace.com

It’s been a long, long time since I last mentioned ObMimic, so an update seems necessary.

At the time I thought it wouldn’t take more than a couple of months or so to get everything ready and put up a public website, discussion forums, bug list, and everything we need internally to release and support ObMimic.

Well, here we are, well over a year later, and there’s still no public website or ObMimic release.

So it seems worth a quick post to explain that ObMimic isn’t dead; it isn’t forgotten; it has just been much delayed and postponed, and is still “on the way”.

Why this long delay?

Well, partly this is the usual story that everything takes much longer than expected, even after you’ve allowed for the fact that everything takes much longer than expected.

Partly it’s from needing longer than expected to handle all the bugs and kludges encountered in the many third-party applications, tools and services involved, and getting everything to work nicely together.

Partly it’s a deliberate decision to wait until everything is reasonably complete and reliable before going public, even if that causes delay, rather than rushing out a quick-and-nasty website with lots of problems (and leaving us with a backlog of work and ongoing firefighting).

But mainly it’s due to having been sucked into other commitments, and spending time on several other things in order to “keep afloat” in the meantime. Such distractions have always seemed like a bad idea, but over the last year or so they’ve been a necessary evil.

It’s not that we’ve not been working on it. It’s just that there are always so many things that need doing, and the months fly by at alarming speed. As Brooks says in The Mythical Man Month: “How does a project get to be a year late? … One day at a time.” (but as also quoted there, “Good cooking takes time. If you are made to wait, it is to serve you better, and to please you”).

Anyway, during all these delays I’ve been deliberately keeping a low profile, and have wanted to steer clear of talking much about ObMimic until I can be sure that it’s genuinely imminent.

Rest assured though, a public beta and full release are still intended as soon as it’s ready (and we are getting there, despite the absence of any outward signs of progress); the product itself is still being maintained and improved in the meantime; and for anyone that wants an early look at it, a “private beta release” is still available if you contact me.

Private beta of ObMimic for out-of-container servlet testing

30 05 2008

Updated May 2013: ObMimic is now available from www.openbrace.com

The ObMimic library for out-of-container servlet testing is now being made available to a small number of users as a private “beta” release, in advance of a more public beta.

We’re ready for a few more people to start trying it out, so if you’re interested just let me know – either via this blog’s “contact me” page or via my company e-mail address of mike-at-openbrace-dot-com.

In outline, ObMimic provides a comprehensive set of fully-configurable test doubles for the Servlet API, so that you can use normal “plain java” tools and techniques to test servlets, filters, listeners and any other code that depends on the Servlet API. We call these test doubles “mimics”, because they “mimic” the behaviour of the real object.

We see this as the ultimate set of “test doubles” for this specific API: a set of plain Java objects that completely and accurately mimic the behaviour of the “real” Servlet API objects, whilst being fully configurable and inspectable and with additional instrumentation to support both “state-based” and “interaction-based” testing.

If you find servlet code harder to test than plain Java, ObMimic might be just what you’re looking for.

With ObMimic, you can create instances of any Servlet API interface or abstract class using plain no-argument constructors; configure and inspect all relevant details of their internal state as necessary; and pass them into your code wherever Servlet API objects are needed. This makes it easy to do detailed testing of servlets, filters, listeners and other code that depends on the Servlet API, without needing a servlet container and without any of the complexities and overheads of packaging, deployment, restarts/reloads, networking etc.

ObMimic includes facilities for:

  • Setting values that are “read-only” in the Servlet API (including full programmatic control over “deployment descriptor” values and other values that are normally fixed during packaging/deployment, or that have fixed values in each servlet container).
  • Examining values that are normally “write-only” in the Servlet API (such as a response’s body content).
  • Optionally recording and retrieving details of the Servlet API calls made to each object (with ability to turn this on and off on individual objects).
  • Controlling which version of the Servlet API is simulated, with versions 2.3, 2.4 and 2.5 currently supported (for example, you can programmatically repeat a test using different Servlet API versions).
  • Detecting and reporting any calls to Servlet API methods whose handling isn’t strictly defined by the API (e.g. passing null arguments to Servlet API methods whose Javadoc doesn’t specify whether nulls are permitted or how they are handled).
  • Controlling the simulation of container-specific behaviour (i.e. where the Servlet API allows variations or leaves this open).
  • Explicitly forcing Servlet API methods to throw a checked exception (e.g. so that you can test any code that handles such exceptions).
  • Handling JNDI look-ups using a built-in, in-memory JNDI simulation.

There are no dependencies on any particular testing framework or third-party libraries (other than Java SE 5 or higher and the Servlet API itself), so you can freely use ObMimic with JUnit, TestNG or any other testing framework or tool.

In contrast to traditional “mock” or “stub” objects, ObMimic provides complete, ready-made implementations of the Servlet API interfaces and abstract classes as defined by their Javadoc. As a result, your tests don’t have to depend on your own assumptions about the Servlet API’s behaviour, and both state-based and interaction-based tests can be supported. ObMimic can even handle complex sequences of Servlet API calls, such as for session-handling, request dispatching, incorporation of “POST” body content into request parameters, notification to listeners, and other such complex interactions between Servlet API objects. It can thus be used not only for testing individual components in isolation, but also for testing more complete paths through your code and third-party libraries.

With the appropriate configuration, it’s even possible to test code that uses other frameworks on top of the Servlet API. For example, we’ve been able to use ObMimic to test “Struts 1” code, and to run ZeroTurnaround’s JspWeaver on top of ObMimic to provide out-of-container testing of JSPs (as documented previously).

As a somewhat arbitrary example, the following code illustrates a very simple use of ObMimic to test a servlet (just to show the basics of how Servlet API objects can be created, configured and used):

import com.openbrace.obmimic.mimic.servlet.http.HttpServletRequestMimic;
import com.openbrace.obmimic.mimic.servlet.http.HttpServletResponseMimic;
import com.openbrace.obmimic.mimic.servlet.ServletConfigMimic;
import javax.servlet.Servlet;
import javax.servlet.ServletException;
import java.io.IOException;


/* Create a request and configure it as needed by the test. */    
HttpServletRequestMimic request = new HttpServletRequestMimic();
request.getMimicState().getRequestParameters().set("name", "foo");
request.getMimicState().getAttributes().set("bar", 123);
... further request set-up as desired ...

/* Create a response. */
HttpServletResponseMimic response = new HttpServletResponseMimic();

 * Create and initialize the servlet to be tested (assumed to be a
 * class called "MyHttpServlet"), using a dummy/minimal 
 * ServletConfig.
Servlet myServlet = new MyHttpServlet();
try {
    myServlet.init(new ServletConfigMimic());
} catch (ServletException e) {
    ... report that test failed with unexpected ServletException ...

/* Invoke the servlet to process the request and response. */
try {
    myServlet.service(request, response);
} catch (ServletException e) {
    ... report that test failed with unexpected ServletException ...
} catch (IOException e) {
    ... report that test failed with unexpected IOException ...

 * Retrieve the response's resulting status code and body content,
 * as examples of how the resulting state of the relevant mimic 
 * instances can be examined.
int statusCode 
    = response.getMimicState().getEffectiveHttpStatusCode();
String bodyContent
    = response.getMimicState().getBodyContentAsString();
... then check them as appropriate for the test ...

For further examples and details, refer to the previous posts “First experiments with out-of-container testing of Servlet code using ObMimic” part 1 and part 2, “Out-of-container JSP testing with ObMimic and JspWeaver”, and the related post “Mocking an API should be somebody else’s problem”.

There are also more extensive examples in ObMimic’s documentation.

ObMimic isn’t open-source, but it will have a zero-cost version (full API coverage but a few overall features disabled, such as the ability to configure the Servlet API version, control over how incorrect/ambiguous API calls are handled, and recording of API calls). There will also be a low-cost per-user “Professional” version with full functionality, and an “Enterprise” version that includes all of ObMimic’s source-code and internal tests (with an Ant build script) as well as a licence for up to 200 users.

At the moment there’s no web-site, discussion forums or bug-reporting mechanisms (all still being prepared), but ObMimic already comes with full documentation including both short and detailed “getting started” guides, “how to”s with example code, and extensive Javadoc – and for this private beta I’m providing direct support by e-mail.

Anyway, if you’d like to try out ObMimic, or have any questions or comments, or would like to be informed when there’s a more public release, just let me know via the “contact me” page or by e-mail.

%d bloggers like this: