Introduction to Avignon

Avignon is an acceptance test system that allows you to write executable tests in a language that you define.  It uses XML to define the syntax of the language but, if you choose to extend the language, leaves the semantics of the tests up to you.

Features

• Extensible – Allows you to define the language of tests by creating new XML tags and the handlers that implement them.
• Hierarchical – Unlike single-fixture test systems, XML tags can include other tags within them, allowing for you to define the surrounding state of a given test action.
• Unsurpassed Browser Integration – Comes with a set of handlers to interact with an Avignon Browser, which is an interface to a browser.  Currently Avignon comes packaged with a new Internet Explorer bridge as well as a partial implementation of an HttpUnit browser.

Running Tests

Avignon is implemented in Java, and is configurable for many different forms of test execution.

Configuration

Java Version

Avignon has been tested with Java JRE versions 1.3 and 1.4, but additional files are needed if used with JRE 1.3 (as noted below).

Classpath

Avignon needs several things in its classpath before it can run tests.  These are described below.

Jars

Avignon.jar  The core test framework.

JUnit.jar (or some other JUnit test runner such as the Eclipse test runner).

AvignonBrowser.jar  The Java classes that implement the pluggable browser framework.  Required for web testing.

AvignonIE.jar  The Java classes that integrate with Microsoft Internet Explorer.  Required only for IE browser integration.

HTTPUnit.jar  Required both for HttpUnit browser integration as well as the core of Avignon.  (This deprecated dependency will be removed once the pluggable HTTPUnit browser is complete).

Tidy.jar  Used by all pluggable browsers to convert web pages into XML documents as well as the core of Avignon.  (As above, this deprecated dependency will be removed once the pluggable HTTPUnit browser is complete).

JAXP.jar  Used to parse the test scripts.  (JDK 1.3 only)

Xalan.jar  Used to parse the test scripts.  (JDK 1.3 only)

Avignon Properties

The Avignon.properties file contains the information that the test runner needs to load tag handlers, determine which browser to use, locate scripts, etc.  Some of the main properties are described below, but please see the AvignonProperties JavaDoc for full details.

ScriptRoot – Required.  Specifies the location of the *TestSuite.xml files that constitute the tests to be run.

HandlerPath – Optional.  Specifies the packages that tag handlers may reside in.  The code for the tag handlers must still be in the classpath.  If you’re using the integrated IE browser, be sure to include com.nolacom.testing.avignon.handlers.browsers in this property.

TestSetupScript – Optional.  Specifies the name (relative to the folder specified in the ScriptRoot property) of the script. to be run whenever an AcceptanceTest tag opens.

TestTearDownScript – Optional.  Specifies the name (relative to the folder specified in the ScriptRoot property) of the script. to be run whenever an AcceptanceTest tag closes.

BrowserClass – Optional.  Specifies the name of the pluggable browser class that OpenBrowser will use.  At present, this class must be located in a subpackage of the com.nolacom.testing.avignon.handlers.browsers package.  The class must have a no-argument constructor and implement the AvignonBrowser interface.

DatabaseDriver – Optional.  Used by the Database* type handlers to make a connection to the database.

DatabaseURL – Optional.  Used by the Database* type handlers to make a connection to the database.

Java Properties

A couple of Java system properties should be set to run Avignon correctly.  These are specified as “–D” arguments to java, such as:

java ‑DAvignonProperties=c:\mytests\Avignon.properties ‑Djava.library.path=c:\AvignonIE junit.swingui.TestRunner

AvignonProperties  Specifies the location of the properties file to use for the tests.  If not specified, Avignon will look for it using the standard searching algorithm.

java.library.path  Specifies the directory where the IEBridge.dll file, used by the IE Browser, is located.  Don’t include the file name, just the directory.)

JUnit Test Runners

Although Avignon itself should work with any JUnit test runners, the IE browser integration has had trouble in certain circumstances (listed below).  If not using one of the test runners listed below, it might be worth running the com.nolacom.testing.avignon.handlers.browser.ie.IEBrowserTest unit tests to make sure everything is okay.  This test is a general indicator of how well acceptance tests will work, but it is not proof positive (see the Eclipse notes).

junit.swingui.TestRunner – Successfully runs browser based acceptance tests and unit tests on Win2K and WinXP with IE 6 installed.  Note that you must turn off the class reloading for the com.nolacom.testing.avignon.handlers.browser.ie package, because it affects the JNI class.

Eclipse – Fails to run unit tests but can run acceptance tests provided they always do something with the browser they open.  If you open a browser, close it, and open another browser you could cause an exception outside of the JVM.

Ant JUnit task – No issues noted.

Writing Tests

Overview

Avignon tests are written in XML and executed by a JUnit test runner using small pieces of Java code associated to each XML tag.  It comes with a number of tags already coded that allow fairly effective testing of web applications and limited testing of Java Swing and AWT based applications, but you can derive the most benefit from it by using its extensibility to create your own testing language that best expresses your tests.

Delivered Tags

The JavaDoc contains descriptions of all delivered tags, including core tags and database manipulation.  Below is a brief overview of Version 2.0’s most significant additions.

Web Application Testing

Pluggable Browser Tags

Navigation Tags

OpenBrowser

This tag instructs the test system to open an instance of its web browser pointing to the “about:blank” page.  The type of browser it uses is dependent on the setting in the Avignon properties file but right now only Microsoft’s Internet Explorer is supported.

OpenPage

This tag instructs the current browser to open the page at the URL given in the ‘address’ attribute.

ClickBrowser

Clicks an element on the current web page by name, text or value (for input tags) in combination with a tag type and/or tag index.  Please see the JavaDoc for the ClickBrowserHandler for complete details.

Page Selection tags

Most of the tags in this section operate on the “current page.”  The current page is defined by as the selected frame. in the selected window.

SelectFrame

Switch to a frame. with the name given by the ‘name’ attribute.  Note that to switch to a frame. at the same level as the current frame, you must first switch to the common parent frame. and then switch back down into the desired frame.

SelectWindow

Switch to the window with the title given by the ‘title’ attribute.  This works irrespective of the current frame.

Page Manipulation Tags

EnterText

Causes the value of the ‘value’ attribute to be entered into the input or textarea tag with the name given by the ‘name’ attribute.

SelectValue

Causes an option in a select tag to become selected.  The name of the select tag is specified by the ‘name’ attribute.  You can specify which option to select with either the ‘text’ or ‘value’ attribute, ‘text’ being what you see on your HTML page, ‘value’ being what gets submitted to the server.

Assertion Tags

TableAssert

Asserts that the content of a table matches a CSV file.  The ‘selectCore’ attribute is an XPath expression specifying where to find the table tag.  The ‘expectedCsv’ attribute defines what you expect to be in the table.

XPathAssert

Asserts something about the result of evaluating an XPath expression against the current page.  The expression is given in the ‘select’ attribute.  The expected result can either be the concatenation of the matching elements (use the ‘values’ attribute) or the number of elements matching the expression (use the ‘count’ attribute).  You may also use a custom asserter by specifying the ‘asserter’ attribute (see the JavaDoc for the XPathAssertHandler for more information).

Old-Style HTTPUnit Tags

Documentation for these tags can be found in the JavaDoc.  It is recommended that you not use them for new tests since they are being removed in favor of making HTTPUnit a pluggable browser.

Java Application Testing

There are currently no prebuilt tags for testing Java Swing or AWT applications, although developers may find the ComponentAsserter class useful in creating them.

Samples

Web Application Testing

Pluggable Browser Example

The IEBrowserSampleTestSuite.xml file serves as an example of how to use some of the prebuilt tags; it includes detailed descriptions of what each part of the test is doing.  To run the test, you must extract the samplescripts directory from the jar and modify the RunSamples.bat file to have the correct classpath for all the required jars.  Please see also the “Running Tests” section of this documentation.

Extending Avignon

Avignon itself comes with a fairly minimal set of tags; adding your own custom tags gives you more power to express your tests.

Test Writer’s Perspective

From the test writer’s perspective, adding new tags is quite simple.  Just make up a name for it, decide what attribute you’ll need for it, and communicate it to the developers.  If you include a tag that doesn’t have any code written for it in your test, it will just appear as an error in the JUnit output.

Developer’s Perspective

From the developer’s perspective, creating new tag handlers is a little more difficult but not terribly so.  For each new tag, you’ll need to create a class with the same name plus the word Handler.  This class must implement the AvignonTagHandler interface and have a zero argument constructor.  The interface gives you two methods: start and end.  The start method is called each time the tag is opened in a test.  It gets the current AvignonTestState, which allows you to record errors and search for surrounding tags, and any XML attributes that were in the test.  The end method is called each time the tag closes in a test.  It gets the current AvignonTestState as a parameter.  You can make any assertions or do any actions necessary is either the start or end methods.

Revision History

Version 1

An early version of Avignon has been used internally at NOLA Computer Services, Inc since early 2002.  It was first released to coincide with the 2002 XP Universe.

Version 2

The second release of Avignon, in October 2004, introduces the idea of pluggable browser components.  It also cleans up some of the shortcomings of the original release, such as making the location of the properties file user definable and not requiring code writing to implement the database connections.