Accessibility Test Suite Documentation

This document shows how to use the Accessibility test suite, both inside the NetBeans IDE and as a standalone test tool.

Files

/docs - the JavaDoc for the API
/src - the source code
/tests - a sample test and an ANT script to run the test in NetBeans
/tests/results - the DTD, XSL and CSS to display the XML results of the test

Extension of Form Editor in NetBeans

AccessibilityTester can also be used to test forms in the Form Editor at design-time. This is done by installing the a11y.jar as a module in NetBeans. It will add an action to the Form toolbar.

The action is responsive to RADComponentCookies so it wil be enabled when a component is selected in the Component Inspector.

An Options dialog allows the test to be configured. The user is given a choice of perform Accessiblity property tests and a keyboard traversal test, to ensure all components are reachable with only the keyboard. There is also a list of classes that the test will ignore. This is because classes such as panels will rarely need to be Accessible but can be numerous and will complicate the results.

The report that is generated when the test is run inside NetBeans shows the variable name of the component with the Accessibility problem. If this report is sent to Standard Output (i.e. the Output Window), selecting a component name in the Output Window will select the component in Component Inspector and the properties for it are displayed, allowing the problem to be fixed.

Future development ideas
Allow sub-containers of a form to be tested individually.
More options over the type of report generated and the destination of the report.

Using the API

The Accessibility Tester can also be used directly in your own programs, through its API.

To run a test on a component, we get a reference to the component comp and then:

AccessibilityTester tester = new AccessibilityTester(comp);
            
tester.testProperties();
tester.testTraversal(comp);

XMLReport report = new XMLReport(tester);
report.getReport(new java.io.PrintWriter(System.out));
tester.testProperties() will test the actual properties of a component. These properties are whether the component implements the Accessible interface, has an Accessible name and description, if LABEL_FOR values are correctly used and if buttons have mnemonics. These test can be configured as explained below.

tester.testTraversal(comp) will test the traversal of components by simulating TAB keypresses. The argument passed to the method is the component to start from. Usually, it is sufficient to simply pass the top level container and this will focus the first component by default. However, if some other behaviour is required, a specific component can be used.

XMLReport report = new XMLReport(tester) creates an XML report generator for the tester.

report.getReport(Writer) writes the report to the Writer. In the example above, it is written to the std out.

Example

This example will show the steps necessary to create a test case to invoke the Object Browser in NetBeans and assess its accessibility. This test uses two libraries, Jemmy and Jelly. These libraries are currently closed source so cannot be distributed but this may change. A simpler example, used to test the Accessibility Tester options dialog, is included in the /tests directory.

A test case must implement the abstract methods defined in AccessibilityTestCase.

public abstract class AccessibilityTestCase{
  public void execute(){}
  public abstract Component setUp();
  public abstract void tearDown();
  public String getDescription(){}
}
The setUp method should display the component to be tested on the screen and return a reference to it. The tearDown method should clear up after the test, normally this is closing the dialog or window that was tested. This method should execute even if setUp failed. getDescription is just a vanity method to describe the test.

The execute method will display a dialog to customize the test, then call setup, perform the specified tests and then call teardown. If a different behaviour is required, it can be overridden.

To invoke the Object Browser in NetBeans, we use a combination of Jemmy, to display the Object Browser, and Jelly, to obtain a reference to it.

public Component setUp(){

  JellyProperties.setDefaults();
  JellyProperties.setJemmyDebugTimeouts();
These lines are required to initialize Jemmy.
  MainFrame mf = MainFrame.getMainFrame();
  mf.pushViewMenuNoBlock("Object Browser");
This will simulate pressing the Object Browser menu item in the View menu. It will ensure a non-modal dialog, since the call is non-blocking.
  try{

    JFrame frame = JFrameOperator.waitJFrame("NetBeans", false, false);
This uses the JFrameOperator class from Jelly to wait for the main NetBeans window to be displayed.
    internalFrame = JInternalFrameOperator.waitJInternalFrame(frame, "Object Browser", false, false);
This waits for a JInternalFrame in the main NetBeans window to be displayed that has the title "Object Browser".
  }
  catch (TimeoutExpiredException e){

    return null;
  }
  return internalFrame;
}
If both of these references are obtained before the Jelly timeout, the Object Browser reference is returned. The tearDown method should close the internal frame after the test has completed.
public void tearDown(){

  if (internalFrame != null){

    internalFrame.doDefaultCloseAction();
  }
}

Running the test

The test can be run directly from inside NetBeans. To do this, implement a main method that creates an instance of the test and calls execute on it. If the test is dependent on NetBeans, set execution to Internal Execution and run the test.

The test can also be run from an ANT script. A build.xml script to run the sample test is found in the /tests directory. This script will cause an instance of NetBeans to be run and will execute AccessibilityTestRunner in it. The test runner will attempt to instantiate the class found in system property a11ytest.test_case. This is really a very verbose way of doing what the execute method above does. The reason for doing it is because if a test has no main method, it can still be run. Since this method of execution is supposed to allow automated testing, it is better to ensure that all of the tests will be run. Also, it will not display the options dialog, which would block the automated test.

Please note: the module must be uninstalled from NetBeans for the automated test to run. This is due to a problem with classloaders.

Explanation of options and parameters in AccessibilityTester

When creating an AccessibilityTester, you can specify which tests to perform with the following parameters:

To specify with tests to perform, simply get the logical OR of the desired values and pass it to the constructor or the setTests method.

The following system properties are used by AccessibilityTester:

There is one final parameter, a11ytest.log_file, which is used globally to record the success/failure of tests.