Tapestry Training -- From The Source

Let me help you get your team up to speed in Tapestry ... fast. Visit howardlewisship.com for details on training, mentoring and support!

Thursday, December 31, 2009

Clojure 1.1 is out ... plus videos about new features

So, Clojure 1.1 is now available, with lots of cool new features, including transients, pre & post conditions, futures, promises and a boat load of other stuff. Rich Hickey has put together release notes.

Meanwhile, if you are curious about some of these new features, check out this series of videos by Sean Devlin.

CodeMash I'll be speaking about Clojure and Tapestry at CodeMash 2.0.1.0 this year, January 13-15.

Monday, December 28, 2009

Securing Tapestry pages with Annotations, Part 1

Everyone wants all sorts of integrations for Tapestry with other frameworks, but sometimes rolling your own is actually easier. Let's start with securing access to pages, a subject that still keeps coming up on the mailing list. I thought I'd show a little bit about how I tackle this problem generally.

People have been asking for a single definitive solution for handling security ... but I don't see any single solution satisfying even the majority of projects. Why? Because there are simply too many variables. For example, are you using LDAP, OpenAuth or some ad-hoc user registry (in your database)? Are pages accessible by default, or in-accessible by default? Are you using role-based security? How do you represent roles then? Creating a single solution that's pluggable enough for all these possibilities seems like an insurmountable challenge ... but perhaps we can come up with a toolkit so that you can assemble your own custom solution (more on that later).

One approach to security could be to define a base class, ProtectedPage, that enforced the basic rules (you must be logged in to use this page). You can accomplish such a thing using the activate event handler ... but I find such an approach clumsy. Anytime you can avoid inheritance, you'll find your code easier to understand, easier to manage, easier to test and easier to evolve.

Instead, let's pursue a more declarative approach, where we use an annotation to mark pages that require that the user be logged in. We'll start with these ground rules:

  • Pages are freely accessible by anyone, unless they have a @RequiresLogin annotation
  • Any static resource (in the web context directory) is accessible to anybody
  • There's already some kind of UserAuthentication service that knows if the user is currently logged in or not, and (if logged in) who they are, as a User object

So, we need to define a RequiresLogin annotation, and we need to enforce it, by preventing any access to the page unless the user is logged in.

That poses a challenge: how do you get "inside" Tapestry to enforce this annotation? What you really want to do is "slip in" a little bit of your code into existing Tapestry code ... the code that analyzes the incoming request, determines what type of request it is (a page render request vs. a component event request), and ultimately starts calling into the page code to do the work.

This is a great example of the central design of Tapestry and it's IoC container: to natively supporting this kind of extensibility. Through the use of service configurations it's possible to do exactly that: slip a piece of code into the middle of that default Tapestry code. The trick is to identify where. This image gives a rough map to how Tapestry handles incoming requests:

Tapestry Request Processing

In fact, there's a specific place for this kind of extension: the ComponentRequestHandler pipeline service1. As a pipeline service, ComponentRequestHandler has a configuration of filters, and adding a filter to this pipeline is just what we need.

Defining the Annotation

First, lets define our annotation:

@Target( { ElementType.TYPE })
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RequiresLogin {

}

This annotation is designed to be placed on a page class to indicate that the user must be logged in to access the page. The retention policy is important here: it needs to be visible at runtime for our runtime code to see it and act on its presence.

An annotation by itself does nothing ... we need the code that checks for the annotation.

Creating a ComponentRequestFilter

Filters for the ComponentRequestHandler pipeline are instances of the interface ComponentRequestFilter:

/**
 * Filter interface for {@link org.apache.tapestry5.services.ComponentRequestHandler}.
 */
public interface ComponentRequestFilter
{
    /**
     * Handler for a component action request which will trigger an event on a component and use the return value to
     * send a response to the client (typically, a redirect to a page render URL).
     *
     * @param parameters defining the request
     * @param handler    next handler in the pipeline
     */
    void handleComponentEvent(ComponentEventRequestParameters parameters, ComponentRequestHandler handler)
            throws IOException;

    /**
     * Invoked to activate and render a page. In certain cases, based on values returned when activating the page, a
     * {@link org.apache.tapestry5.services.ComponentEventResultProcessor} may be used to send an alternate response
     * (typically, a redirect).
     *
     * @param parameters defines the page name and activation context
     * @param handler    next handler in the pipeline
     */
    void handlePageRender(PageRenderRequestParameters parameters, ComponentRequestHandler handler) throws IOException;
}

Our implementation of this filter will check the page referenced in the request to see if it has the annotation. If the annotation is present and the user has not yet logged in, we'll redirect to the Login page. When a redirect is not necessary, we delegate to the next handler in the pipeline2:

public class RequiresLoginFilter implements ComponentRequestFilter {

  private final PageRenderLinkSource renderLinkSource;

  private final ComponentSource componentSource;

  private final Response response;

  private final AuthenticationService authService;

  public PageAccessFilter(PageRenderLinkSource renderLinkSource,
      ComponentSource componentSource, Response response,
      AuthenticationService authService) {
    this.renderLinkSource = renderLinkSource;
    this.componentSource = componentSource;
    this.response = response;
    this.authService = authService;
  }

  public void handleComponentEvent(
      ComponentEventRequestParameters parameters,
      ComponentRequestHandler handler) throws IOException {

    if (dispatchedToLoginPage(parameters.getActivePageName())) {
      return;
    }

    handler.handleComponentEvent(parameters);

  }

  public void handlePageRender(PageRenderRequestParameters parameters,
      ComponentRequestHandler handler) throws IOException {

    if (dispatchedToLoginPage(parameters.getLogicalPageName())) {
      return;
    }

    handler.handlePageRender(parameters);
  }

  private boolean dispatchedToLoginPage(String pageName) throws IOException {

    if (authService.isLoggedIn()) {
      return false;
    }

    Component page = componentSource.getPage(pageName);

    if (! page.getClass().isAnnotationPresent(RequiresLogin.class)) {
      return false;
    }

    Link link = renderLinkSource.createPageRenderLink("Login");

    response.sendRedirect(link);

    return true;
  }
}

The above code makes a bunch of assumptions and simplifications. First, it assumes the name of the page to redirect to is "Login". It also doesn't try to capture any part of the incoming request to allow the application to continue after the user logs in. Finally, the AuthenticationService is not part of Tapestry ... it is something specific to the application.

You'll notice that the dependencies (PageRenderLinkSource, etc.) are injected through constructor parameters and then stored in final fields. This is the preferred, if more verbose approach. We could also have used no constructor, a non-final fields with an @Inject annotation (it's largely a style choice, though constructor injection with final fields is more guaranteed to be fully thread safe).

The class on its own is not enough, however: we have to get Tapestry to actually use this class.

Contributing the Filter

The last part of this is hooking the above code into the flow. This is done by making a contribution to the ComponentEventHandler service's configuration.

Service contributions are implemented as methods of a Tapestry module class, such as AppModule:

  public static void contributeComponentRequestHandler(
      OrderedConfiguration configuration) {
    configuration.addInstance("RequiresLogin", RequiresLoginFilter.class);
  }

Contributing modules contribute into an OrderedConfiguration: after all modules have had a chance to contribute, the configuration is converted into a List that's passed to the service implementation.

The addInstance() method makes it easy to contribute the filter: Tapestry will look at the class, see the constructor, and inject dependencies into the filter via the constructor parameters. It's all very declarative: the code needs the PageRenderLinkSource, so it simply defines a final field and a constructor parameter ... Tapestry takes care of the rest.

You might wonder why we need to specify a name ("RequiresLogin") for the contribution? The answer addresses a somewhat rare but still important case: multiple contributions to the same configuration that have some form of interaction. By giving each contribution a unique id, it's possible to set up ordering rules (such as "contribution 'Foo' comes after contribution 'Bar'"). Here, there is no need for ordering because there aren't any other filters (Tapestry provides this service and configuration, but doesn't make any contributions of its own into it).

Improvements and Conclusions

This is just a first pass at security. For my clients, I've built more elaborate solutions, that include capturing the page name and activation context to allow the application to "resume" after the login is complete, as well as approaches for automatically logging the user in as needed (via a cookie or other mechanism).

Other improvements would be to restrict access to pages based on some set of user roles; again, how this is represented both in code and annotations, and in the data model is quite up for grabs.

My experience with different clients really underscores what a fuzzy world security can be: there are so many options for how you represent, identify and authenticate the user. Even basic decisions are underpinnings are subject to interpretation; for example, one of my clients wants all pages to require login unless a specific annotation is found. Perhaps over time enough of these use cases can be worked out to build the toolkit I mentioned earlier.

Even so, the amount of code to build a solid, custom security implementation is still quite small ... though the trick, as always, is writing just the write code and hooking it into Tapestry in just the right way.

I expect to follow up this article with part 2, which will expand on the solution a bit more, addressing some more of the real world constraints my customers demand. Stay tuned!


1 In fact, this service and pipeline were created in Tapestry 5.1 specifically to address this use case. In Tapestry 5.0, this approach required two very similar filter contributions to two similar pipelines.

2 If there are multiple filters, you'd think that you'd delegate to the next filter. Actually you do, but Tapestry provides a bridge: a wrapper around the filter that uses the main interface for the service. In this way, each filter delegates to either the next filter, or the terminator (the service implementation after all filters) in a uniform manner. More details about this are in the pipeline documentation.

Monday, December 14, 2009

Upcoming Public Training: London and Paris

SkillsMatter Logo This is a big announcement ... something I've been working on pretty much since I left Formos. I've partnered up with SkillsMatter to provide my three-day, hands-on Tapestry training as a public enrollment course!

This is the exact same course I provide as on-site training, but we'll be doing it at the SkillsMatter offices in London on February 10th, and then in Paris on the 15th.

This is a big experiment for me and for SkillsMatter in terms of growing the size of the Tapestry community. In fact, SkillsMatter has really upped the ante here by offering 2-for-1 on the London training ... that's a great way to kick things off!

I can't emphasize enough what a great opportunity this is for people to get accelerated Tapestry training at a discount (even before factoring in the 2-for-1 offer). I'm really looking forward to bringing many new developers into the fold!

In addition, there will be a special, free evening event at each location. Details on that to follow. I look forward to meeting even more of you there!

Friday, December 04, 2009

Devoxx Videos up at Parleys.com

My sessions for this year's Devoxx are available from Parleys.com: Tapestry and Clojure. You can watch the first two minutes for free (so if you idea of fun is to watch me check with the sound guy and look uncomfortable while waiting for the session to start ... you are in like Flynn); after that it's a subscription service to gain access to all of the Parleys.com content.

Change of pace: Arduino

As a total change of pace, I've been playing around with actual hardware, in the form of an Arduino board. This is a hoot, an actual computer that you can carry around in your hand. They call it physical computing.

I'm just getting started with it, in my tiny shards of free time. Your code is in C (and a smattering of C++). I've hooked up four LEDs and two buttons that allow me to cycle the LEDs forward or backward. Since you're working at such a low level, you have to be aware of tiny factors such as key bounce (closing a switch will, for a short period, yield unstable results due to physical and electrical factors).

There's a tool called Fritzing to help you document your projects. It's very alpha, but the simple results are rather nice:


The code is still evolving:

#define FIRST_LED 12
#define LED_COUNT 4
#define DEBOUNCE_PERIOD 50 // ms

class Debounce
{
public:
  Debounce(int pin);
  boolean read();
private:
  int _pin;
  int _previousValue;
  int _lastButtonDebounce;
  boolean _enabled;
};

Debounce::Debounce(int pin)
{
  _pin = pin;
  _previousValue = LOW;
  _lastButtonDebounce = 0; // never
  _enabled = true;

  pinMode(_pin, INPUT);  
}

boolean Debounce::read()
{
  int currentValue = digitalRead(_pin);

  long now = millis();

  if (currentValue != _previousValue)
  {
    _lastButtonDebounce = now;
    _previousValue = currentValue;
    return false;
  }

  if (now - _lastButtonDebounce < DEBOUNCE_PERIOD) {
    return false;
  }


  // It's gone HIGH to LOW

  if (currentValue == LOW) {
    _enabled = true;
    return false;
  }

  // It's gone LOW to HIGH

  if (_enabled) {
    _enabled = false;
    return true;
  }

  return false;
}

// First press will move to the first LED.
int currentLed = -1;

Debounce advanceButton = Debounce(2);
Debounce retreatButton = Debounce(3);

void setup()
{
  for (int i = 0; i < LED_COUNT; i++) {
    int pin = FIRST_LED - i;
    pinMode(pin, OUTPUT);
    digitalWrite(pin, HIGH);
  }

  delay(250);

  for (int i = 0; i < LED_COUNT; i++)
  {
    digitalWrite(FIRST_LED - i, LOW);
  }
}

void advance()
{
  if (currentLed >= 0)
    digitalWrite(FIRST_LED - currentLed, LOW);

  if (++currentLed == LED_COUNT)
    currentLed = 0;

  digitalWrite(FIRST_LED - currentLed, HIGH);
}

void retreat()
{
  if (currentLed >= 0)
    digitalWrite(FIRST_LED - currentLed, LOW);

  if (--currentLed < 0)
    currentLed = LED_COUNT - 1;

  digitalWrite(FIRST_LED - currentLed, HIGH);
}

void loop()
{
  if (advanceButton.read()) advance();

  if (retreatButton.read()) retreat();
}

Fun stuff ... and I don't see me writing a web framework for it, which is a change of pace.

My ultimate goal is to write Arduino apps in a Clojure DSL, and have Clojure generate the machine code for the AVR processor that runs the Arduino. Of course, that means learning AVR machine code and writing a lot of code to compile and assemble the DSL into something that can execute inside the Arduino.

Plan B: Perhaps its time to learn Forth?

Thursday, December 03, 2009

Tapestry and Kaptcha

Another bit of interesting work I did, for another client, was to implement a CAPTCHA system. I chose the library Kaptcha and built services and components around it.

If you follow the documentation for Katpcha, you'll see that you're supposed to configure it inside web.xml and add a servlet. That's not the Tapestry way, especially for something that will likely be split off into its own library at some point and there's no reason that all the necessary plumbing can't occur within the context of Tapestry's APIs.

The essence of a CAPTCHA is two fold: first, a secret string is generated on the server side. On the client-side, an image and a text field are displayed. The image is a distorted version of the secret text. The user must type the text ... humans being better able to pull meaning out of the distortion than any typical program.

Back on the server side, we compare what the user entered against the secret string.

I broke the implementation up into three pieces:

  • A Tapestry service to handle generating the secret string and the image
  • A Tapestry component to display the image
  • A second component to handle the text field

In practice, all it takes to use this is the following:

  <t:kaptchaimage t:id="kaptcha"/>
  <br/>
  <t:kaptchafield image="kaptcha"/>

The two components work together to select the secret word, display the image, and validate that the user has entered the expected value.

Let's look at how this all comes together.

KaptchaProducer Service

Kaptcha includes an interface, Producer, that has most of what I want:

package com.google.code.kaptcha;

import java.awt.image.BufferedImage;

/**
 * Responsible for creating captcha image with a text drawn on it.
 */
public interface Producer
{
  /**
   * Create an image which will have written a distorted text.
   * 
   * @param text
   *            the distorted characters
   * @return image with the text
   */
  BufferedImage createImage(String text);

  /**
   * @return the text to be drawn
   */
  String createText();
}

I extended this to add methods for determining the width and height of the captcha image:

package com.myclient.services.kaptcha;

import com.google.code.kaptcha.Producer;

/**
 * Extension of KatpchaProducer that exposes the images width and height (in
 * pixels).
 * 
 */
public interface KaptchaProducer extends Producer {

  int getWidth();

  int getHeight();
}

My implementation is largely a wrapper around Kaptcha's default implementation:

package com.myclient.services.kaptcha;

import java.awt.image.BufferedImage;
import java.util.Map;
import java.util.Properties;

import com.google.code.kaptcha.impl.DefaultKaptcha;
import com.google.code.kaptcha.util.Config;

public class KaptchaProducerImpl implements KaptchaProducer {

  private final DefaultKaptcha producer;

  private final int height;

  private final int width;

  public KaptchaProducerImpl(Map<String, String> configuration) {
    producer = new DefaultKaptcha();

    Config config = new Config(toProperties(configuration));

    producer.setConfig(config);

    height = config.getHeight();
    width = config.getWidth();
  }

  public int getHeight() {
    return height;
  }

  public int getWidth() {
    return width;
  }

  public BufferedImage createImage(String text) {
    return producer.createImage(text);
  }

  public String createText() {
    return producer.createText();
  }

  private static Properties toProperties(Map<String, String> map) {

    Properties result = new Properties();

    for (String key : map.keySet()) {
      result.put(key, map.get(key));
    }

    return result;

  }
}

What's all the business with the Map<String, String> configuration? That's a Tapestry IoC mapped configuration, that allows us to extend the configuration of the Kaptcha Producer ... say, to change the width or height or color scheme.

Note that this was my choice, to have a centralized text and image producer, so that all CAPTCHAs in the application would have a uniform look and feel. Another alterntiave would have been to have the KaptchaImage component (described shortly) have its own instance of DefaultKaptcha, with parameters to control its configuration.

KaptchaImage Component

So with this service in place, how do we generate the image? This is done in three steps:

  • Selecting a secret word and storing it persistently in the session
  • Rendering an <img> element, including a src attribute
  • Providing an image byte stream when asked by the browser
package com.myclient.components;

import java.awt.image.BufferedImage;
import java.io.IOException;
import java.io.OutputStream;

import javax.imageio.ImageIO;

import org.apache.tapestry5.ComponentResources;
import org.apache.tapestry5.Link;
import org.apache.tapestry5.MarkupWriter;
import org.apache.tapestry5.annotations.Persist;
import org.apache.tapestry5.annotations.SupportsInformalParameters;
import org.apache.tapestry5.ioc.annotations.Inject;
import org.apache.tapestry5.services.Response;

import com.myclient.services.kaptcha.KaptchaProducer;

/**
 * Part of a Captcha based authentication scheme; a KaptchaImage generates a new
 * text image whenever it renders and can provide the previously
 * rendred text subsequently (it is stored persistently in the session).
 * 
 * The component renders an <img> tag, including width and height
 * attributes. Other attributes come from informal parameters.
 */
@SupportsInformalParameters
public class KaptchaImage {

  @Persist
  private String captchaText;

  @Inject
  private KaptchaProducer producer;

  @Inject
  private ComponentResources resources;

  @Inject
  private Response response;

  public String getCaptchaText() {
    return captchaText;
  }

  void setupRender() {
    captchaText = producer.createText();
  }

  boolean beginRender(MarkupWriter writer) {
    Link link = resources.createEventLink("image");

    writer.element("img",

    "src", link.toAbsoluteURI(),

    "width", producer.getWidth(),

    "height", producer.getHeight());

    resources.renderInformalParameters(writer);

    writer.end();

    return false;
  }

  void onImage() throws IOException {

    BufferedImage image = producer.createImage(captchaText);

    response.setDateHeader("Expires", 0);
    response.setHeader("Cache-Control",
        "no-store, no-cache, must-revalidate");
    response.setHeader("Cache-Control", "post-check=0, pre-check=0");
    response.setHeader("Pragma", "no-cache");

    OutputStream stream = response.getOutputStream("image/jpeg");

    ImageIO.write(image, "jpg", stream);

    stream.flush();

    stream.close();
  }
}

This component (which has no template) has two render phase methods. In setupRender() we choose the secret word; since the captchaText field has the @Persist annotation, it's value will be stored in the session.

Inside beginRender() is where we render the image. We also generate a callback link for an event named "image". The URL Tapestry generates will identify the page and component within the page, as well as this event name.

Notice how we use the getWidth() and getHeight() extensions on the service interface to set these attributes of the <img> tag.

Later, the browser will send a request for the event, and the onImage() event handler method will be invoked. This is where we get the image bytestream from the service and pump it down to the client. As you can see, we set a bunch of header values to ensure that the browser won't cache the image.

KaptchaField Component

The last part of the overall puzzle is the text field. Again, there are two main responsibilities:

  • Rendering out the text field (when rendering)
  • Validating that the user entered the correct secret text (when the form is submitted)
package com.myclient.components;

import org.apache.tapestry5.BindingConstants;
import org.apache.tapestry5.ComponentResources;
import org.apache.tapestry5.FieldValidator;
import org.apache.tapestry5.MarkupWriter;
import org.apache.tapestry5.ValidationTracker;
import org.apache.tapestry5.annotations.BeginRender;
import org.apache.tapestry5.annotations.Environmental;
import org.apache.tapestry5.annotations.Parameter;
import org.apache.tapestry5.annotations.SupportsInformalParameters;
import org.apache.tapestry5.corelib.base.AbstractField;
import org.apache.tapestry5.ioc.Messages;
import org.apache.tapestry5.ioc.annotations.Inject;
import org.apache.tapestry5.services.FieldValidatorSource;
import org.apache.tapestry5.services.Request;

/**
 * Field paired with a {@link KaptchaImage} to ensure that the user has provided
 * the correct value.
 * 
 */
@SupportsInformalParameters
public class KaptchaField extends AbstractField {

  /**
   * The image output for this field. The image will display a distorted text
   * string. The user must decode the distorted text and enter the same value.
   */
  @Parameter(required = true, defaultPrefix = BindingConstants.COMPONENT)
  private KaptchaImage image;

  @Inject
  private Request request;

  @Inject
  private Messages messages;

  @Inject
  private ComponentResources resources;

  @Environmental
  private ValidationTracker validationTracker;

  @Inject
  private FieldValidatorSource fieldValidatorSource;

  @Override
  public boolean isRequired() {
    return true;
  }

  @BeginRender
  boolean renderTextField(MarkupWriter writer) {

    writer.element("input",

    "type", "password",

    "id", getClientId(),

    "name", getControlName(),

    "value", "");

    resources.renderInformalParameters(writer);

    FieldValidator fieldValidator = fieldValidatorSource.createValidator(
        this, "required", null);

    fieldValidator.render(writer);

    writer.end();

    return false;
  }

  @Override
  protected void processSubmission(String elementName) {

    String userValue = request.getParameter(elementName);

    if (image.getCaptchaText().equals(userValue))
      return;

    validationTracker.recordError(this, messages.get("incorrect-captcha"));
  }

}

The renderTextField() method is largely straight forward: by the time this is invoked, the unique clientId and controlName will already have been set for the field. The only trick here is to create some client-side validation to enforce that the field is required.

Later the form will be submitted by the user and the processSubmission() method is invoked. It asks the KaptchaImage for the stored text and compares it to the user's input. If invalid, then an error message is recorded, associated with the field. The actual error text is stored in the component's message catalog.

Conclusion

Tapestry's approach is quite often about integration: integration of component code with other resources (such as templates or message catalogs), integration of components with other components, and integration of components with services. Here we get to see how a singleton service can be used by any number of components, how two components can be connected together, and how easy it is to provide logic both when rendering a page and on later related requests from the client.

Update

If you check the comments below, you'll see that Jon and I have been sparring good-naturedly about what constitutes "simple". Most of the code is related to integration: integrating the Kaptcha code into the Tapestry infrastructure; adding features such as just-in-time initialization to the DefaultProducer code, adding new features (access to the width and height of the image), allowing for configuration of the Kaptcha Producer in the "Tapestry way" (via contribution methods in module classes), and hooking into Tapestry's normal infrastructure for handling form submissions and reporting user input errors ... even client-side logic to enforce that the field is required.

All that integration is what allows the end-developer to get by with just the following in their page template:

  <t:kaptchaimage t:id="kaptcha"/>
  <br/>
  <t:kaptchafield image="kaptcha"/>

... and even that could be compressed down to a single convenience component wrapping the two underlying components:

  <t:kaptcha/>

That is simplicity: no decisions to make, no URLs to map, no other files to edit, no additional code to write.

However, this still follows the Law of Immutable Complexity: making one part of a system simpler will make other parts more complex. In this situation, that extra complexity is the integration code (the two components and the service that Jon objects to). That's a trade-off I'm always willing to make: write some medium complex code once (and test it, once) and then be able to use it wherever I want.

TestNG and Selenium

I love working on client projects, because those help me really understand how Tapestry gets used, and the problems people are running in to. On site training is another good way to see where the theory meets (or misses) the reality.

In any case, I'm working for a couple of clients right now for whom testing is, rightfully, quite important. My normal approach is to write unit tests to test specific error cases (or other unusual cases), and then write integration tests to run through main use cases. I consider this a balanced approach, that recognizes that a lot of what Tapestry does is integration.

One of the reasons I like TestNG is that it seamlessly spans from unit tests to integration tests. All of Tapestry's internal tests (about 1500 individual tests) are written using TestNG, and Tapestry includes a base test case class for working with Selenium: AbstractIntegrationTestSuite. This class does some useful things:

  • Launches your application using Jetty
  • Launches a SeleniumServer (which drives a web browser that can exercise your application)
  • Creates an instance of the Selenium client
  • Implements all the methods of Selenium, redirecting each to the Selenium instance
  • Adds additional error reporting around any Selenium client calls that fail

These are all useful things, but the class has gotten a little long in the tooth ... it has a couple of critical short-comings:

  • It runs your application using Jetty 5 (bundled with SeleniumServer)
  • It starts and stops the stack (Selenium, SeleniumServer, Jetty) around each class

For my current client, a couple of resources require JNDI, and so I'm using Jetty 7 to run the application (at least in development, and possibly in deployment as well). Fortunately, Jetty 5 uses the old org.mortbay.jetty packages, and Jetty 7 uses the new org.eclipse.jetty packages, so both versions of the server can co-exist within the same application.

The larger problem is that I didn't want a single titanic test case for my entire application; I wanted to break it up in other ways, by Tapestry page initially.

I could create additional subclasses of AbstractIntegrationTestSuite, but then the tests will spend a huge amount of time starting and stopping Firefox and friends. I really want that stuff to start just once.

What I've done is a bit of refactoring, by leveraging some features of TestNG that I hadn't previously used.

The part of AbstractIntegrationTestSuite responsible for starting and stopping the stack is broken out into its own class. This new class, SeleniumLauncher, is responsible for starting and stopping the stack around an entire TestNG test. In the TestNG terminology, a suite contains multiple tests, and a test contains test cases (found in individual classes, within scanned packages). The test case contains test and configuration methods.

Here's what I've come up with:

package com.myclient.itest;

import org.apache.tapestry5.test.ErrorReportingCommandProcessor;
import org.eclipse.jetty.server.Server;
import org.openqa.selenium.server.RemoteControlConfiguration;
import org.openqa.selenium.server.SeleniumServer;
import org.testng.ITestContext;
import org.testng.annotations.AfterTest;
import org.testng.annotations.BeforeTest;

import com.myclient.RunJetty;
import com.thoughtworks.selenium.CommandProcessor;
import com.thoughtworks.selenium.DefaultSelenium;
import com.thoughtworks.selenium.HttpCommandProcessor;
import com.thoughtworks.selenium.Selenium;

public class SeleniumLauncher {

  public static final String SELENIUM_KEY = "myclient.selenium";

  public static final String BASE_URL_KEY = "myclient.base-url";

  public static final int JETTY_PORT = 9999;

  public static final String BROWSER_COMMAND = "*firefox";

  private Selenium selenium;

  private Server jettyServer;

  private SeleniumServer seleniumServer;

  /** Starts the SeleniumServer, the application, and the Selenium instance. */
  @BeforeTest(alwaysRun = true)
  public void setup(ITestContext context) throws Exception {

    jettyServer = RunJetty.start(JETTY_PORT);

    seleniumServer = new SeleniumServer();

    seleniumServer.start();

    String baseURL = String.format("http://localhost:%d/", JETTY_PORT);

    CommandProcessor cp = new HttpCommandProcessor("localhost",
        RemoteControlConfiguration.DEFAULT_PORT, BROWSER_COMMAND,
        baseURL);

    selenium = new DefaultSelenium(new ErrorReportingCommandProcessor(cp));

    selenium.start();

    context.setAttribute(SELENIUM_KEY, selenium);
    context.setAttribute(BASE_URL_KEY, baseURL);
  }

  /** Shuts everything down. */
  @AfterTest(alwaysRun = true)
  public void cleanup() throws Exception {
    if (selenium != null) {
      selenium.stop();
      selenium = null;
    }

    if (seleniumServer != null) {
      seleniumServer.stop();
      seleniumServer = null;
    }

    if (jettyServer != null) {
      jettyServer.stop();
      jettyServer = null;
    }
  }
}

Notice that we're using the @BeforeTest and @AfterTest annotations; that means any number of tests cases can execute using the same stack. The stack is only started once.

Also, notice how we're using the ITestContext to communicate information to the tests in the form of attributes. TestNG has a built in form of dependency injection; any method that needs the ITestContext can get it just by declaring a parameter of that type.

AbstractIntegrationTestSuite2 is the new base class for writing integration tests:

package com.myclient.itest;

import java.lang.reflect.Method;

import org.apache.tapestry5.test.AbstractIntegrationTestSuite;
import org.apache.tapestry5.test.RandomDataSource;
import org.testng.Assert;
import org.testng.ITestContext;
import org.testng.annotations.AfterClass;
import org.testng.annotations.BeforeClass;
import org.testng.annotations.BeforeMethod;

import com.mchange.util.AssertException;
import com.thoughtworks.selenium.Selenium;

public abstract class AbstractIntegrationTestSuite2 extends Assert implements
    Selenium {

  public static final String BROWSERBOT = "selenium.browserbot.getCurrentWindow()";

  public static final String SUBMIT = "//input[@type='submit']";

  /**
   * 15 seconds
   */
  public static final String PAGE_LOAD_TIMEOUT = "15000";

  private Selenium selenium;

  private String baseURL;

  protected String getBaseURL() {
    return baseURL;
  }

  @BeforeClass
  public void setup(ITestContext context) {
    selenium = (Selenium) context
        .getAttribute(SeleniumLauncher.SELENIUM_KEY);
    baseURL = (String) context.getAttribute(SeleniumLauncher.BASE_URL_KEY);
  }

  @AfterClass
  public void cleanup() {
    selenium = null;
    baseURL = null;
  }

  @BeforeMethod
  public void indicateTestMethodName(Method testMethod) {
    selenium.setContext(String.format("Running %s: %s", testMethod
        .getDeclaringClass().getSimpleName(), testMethod.getName()
        .replace("_", " ")));
  }

  /* Start of delegate methods */
  public void addCustomRequestHeader(String key, String value) {
    selenium.addCustomRequestHeader(key, value);
  }

  ...
}

Inside the @BeforeClass-annotated method, we receive the test context and extract the selenium instance and base URL put in there by SeleniumLauncher.

The last piece of the puzzle is the code that launches Jetty. Normally, I test my web applications using the Eclipse run-jetty-run plugin, but RJR doesn't support the "Jetty Plus" functionality, including JNDI. Thus I've created an application to run Jetty embedded:

package com.myclient;

import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.webapp.WebAppContext;

public class RunJetty {

  public static void main(String[] args) throws Exception {

    start().join();
  }

  public static Server start() throws Exception {
    return start(8080);
  }

  public static Server start(int port) throws Exception {
    Server server = new Server(port);

    WebAppContext webapp = new WebAppContext();
    webapp.setContextPath("/");
    webapp.setWar("src/main/webapp");

    // Note: Need jetty-plus and jetty-jndi on the classpath; otherwise
    // jetty-web.xml (where datasources are configured) will not be
    // read.

    server.setHandler(webapp);

    server.start();

    return server;
  }
}

This is all looking great. I expect to move this code into Tapestry 5.2 pretty soon. What I'm puzzling on is a couple of extra ideas:

  • Better flexibility on starting up Jetty so that you can hook your own custom Jetty server configuration in.
  • Ability to run multiple browser agents, so that a single test suite can execute against Internet Explorer, Firefox, Safari, etc. In many cases, the same test method might be invoked multiple times, to test against different browsers.

Anyway, this is just one of a number of very cool ideas I expect to roll into Tapestry 5.2 in the near future.