Avignon Developer Cookbook

Setting Up

Required Components

• JUnit -- JUnit is used to run the tests.
• HTTPUnit -- HTTPUnit is used to control web applications. It's not necessary if you're not testing a web application, but you'll need to remove any references from the AvignonTestState if you don't want to put it in your classpath.
• JAXP -- JAXP provides the Java interface for the XML parsing.
• Xalan -- Xalan provides the XML and XSL processing implementation for JAXP.

The avignon.properties File

• ScriptRoot -- This property defines where all of the scripts will be located. Only the files ending in "TestSuite.xml" will be executed automatically.
• HandlerPath -- This property defines the packages that Avignon should search for aditional tag handlers. The search path always starts with com.nolacom.testing.avignon.handlers and then searches the packages specified by this property. Each package should be separated by the vertical bar (|) symbol.
• AppStart -- This property specifies the application to be tested. If the value starts with java: the rest of the value should be the fully qualified name of a Java class that extends the java.awt.Frame class. Any other protocol will cause Avignon to try to get a response from HTTPUnit for the URL.
• HtmlTransform -- If you're testing an HTML application, this property should specify the file name (relative to the PageDescriptionRoot directory) of the default XSL transformation.
• PageDescriptionRoot -- This property defines the root directory from which page descriptions are found.

Unimplemented Features

If your customer wishes to use the database manipulation tags, you'll need to implement three methods in the com.nolacom.testing.avignon.handlers.database.DatabaseConnection class.

• getConnection -- This method should return a java.sql.Connection to your database.
• tableExists -- This method is used to help with perserving the database during a test. It returns true if the given table name exists in the database system.
• copyTable -- This method should create a new table (with the name specified in the destinationName paramaeter with the same structure as the table specified in the originalName parameter and copy all of the existing data from the original to the new table.

Running Tests

The class com.nolacom.testing.avignon.ScriptedTests is a standard JUnit TestCase that can be run on its own or added to a TestSuite.

Writing Tag Handlers

Avignon tag handlers must be named the same as the tag they implement with the word "Handler" suffixed to it. They must implement the AvignonTagHandler interface and have access to the AvignonTestState information. They are essentially event handlers that get a "start" event when the tag is first encountered in the script and an "end" event when the tag is closed in the script. They must be placed in one of the classpathes specified by the HandlerPath property.

The AvignonTagHandler Interface

All Avignon tag handlers must implement this interface. It defines the events that can occur for a tag. The start event gets two parameters, the application state (as an instance of an AvignonTestState) and any attributes that are specified with the tag. The end event gets only the application state.

The AvignonTestState Class

Contains information about the current state of the application being tested, the stack of tags that surround the tag being executed and any error information generated by the tests. The following methods are of interest when writing handlers:

Error Handling

• anyErrors -- Returns a boolean indicating whether or not any errors have been reported in the current TestSuite.
• appendErrorMessage -- Appends a message to the error output. If passed a String, it will append that String prefixed by the name of the current test. If passed a Throwable object, it will append the test name and the stack trace of the Throwable.
• getErrorMessages -- Returns the current error messages.

HTML Application Control

• loadPageFromPageClick -- Clicks a link on the current page and returns the text of the response.
• getCurrentFormRequest -- Returns the first form on the current page.
• submitRequest -- Submits a WebRequest and returns the text of the response.

Java Application Control

• getApplication -- Returns the Frame of the Java application being tested.

Test Tag Browsing

• peek -- Searches the current test state for the first enclosing tag with the given Class.

Helper Classes

There are a couple of classes that help with testing Java applications:

• ComponentFinder -- Searches a java.awt.Container for a component with the given name. This allows you to search the application being tested for a certain component.
• ComponentAsserter -- Allows you to assert the value of a named component within the application being tested.