Adding AMX Unit Tests

contact: lloyd.chambers@sun.com
Last updated: 23 June 2005

NOTE: the hyperlinks in this document assume you are reading it from its location in the source tree eg glassfish/admin/mbeanapi-impl/tests/org.glassfish.admin.amxtest.

1. Introduction

The Appserver Management Extensions (AMX) rely heavily on detailed JUnit unit tests to prove that they work correctly. No modification, addition or removal of code from AMX or underlying support code should be checked in without also running the unit tests.

Any code change which involves a new AMX interface, method or Attribute must not be checked in without either (1) verifying that an existing unit test adequately covers the new addition, or (2) writing a new unit test which thoroughly tests the new addition. The code must also be reviewed by amx-dev@sun.com.

2. Adding Tests

2.1 Adding a new test method to an existing unit test

Adding a new test method is easy. Simple add a method of the appropriate form to an existing unit test:

public void
testFoo()
{
// test code here
}

2.2 Adding a new unit test class

A new unit test should be added whenever you add a new class in com.sun.appserv.management, or any of its subpackages. There are exceptions, but generally speaking a unit test class should test only a single class. Examples of exceptions include AMXTest and GenericTest, which test all of AMX generically, regardless of the specific interface.

You may want to start by duplicating the file TestTemplateTest.java.

Your new unit test should extend one of the classes in the table below:

Parent class	Discussion
junit.framework.TestCase	Extend junit.framework.TestCase if your unit test is a standalone test which doesn't connect to the server and doesn't make use of any JMX MBeanServerConnection.
org.glassfish.admin.amxtest.util.jmx.JMXTestBase	Extend JMXTestBase only if your unit test involves generic JMX, with nothing specific to Appserver. This should be very rare.
org.glassfish.admin.amxtest.AMXTestBase	All unit tests which depend on a live connection to the AppServer should extend AMXTestBase.

Your new class should thus be of the form:

public final class ClassBeingTestedTest extends appropriate-parent-class
{
        public
    ClassBeingTestedTest()
    {
    }

        public void
    testMethodA()
    {
        // test code
    }

        public void
    testMethodB()
    {
        // test code
    }
}

You class should generally reside in a org.glassfish.admin.amxtest subpackage which parellels the package of the class being tested. For example, here are the classe and its unit test for SetUtil:

com.sun.appserv.management.util.misc.SetUtil
org.glassfish.admin.amxtest.util.misc.SetUtilTest

2.3 Adding your new unit test to the official list

2.3.1 First, make sure your test compiles:

G:\glassfish\admin\mbeanapi-impl>ant compile-tests
Buildfile: build.xml
init:
compile:
compile-tests:
   [delete] Deleting directory G:\glassfish\admin\mbeanapi-impl\build\tests
    [mkdir] Created dir: G:\glassfish\admin\mbeanapi-impl\build\tests
    [javac] Compiling 80 source files to G:\glassfish\admin\mbeanapi-impl\build\tests
    [javac] Note: * uses or overrides a deprecated API.
    [javac] Note: Recompile with -Xlint:deprecation for details.
    [javac] Note: Some input files use unchecked or unsafe operations.
    [javac] Note: Recompile with -Xlint:unchecked for details.

BUILD SUCCESSFUL
Total time: 3 seconds

2.3.1 Next add your test to the official list

Add your class to org.glassfish.admin.amxtest.Tests. Choose a position in the list that is appropriate; more basic standalone tests should come first. Facilities your new functionality depends on should be unit-tested before your test, etc. This is the "master list" that is consulted when the unit tests are run to warn if any unit tests are being omitted when the unit tests are run.

Also add your test to amxtest.classes. This file contains the actual unit tests that will be run when "ant run-tests" is invoked. Due to the risk of someone checking in amxtest.classes with a reduced list of tests, org.glassfish.admin.amxtest.Tests is always consulted and warnings issued about the missing tests. When you checkin, make sure there are no such warnings.

The best practise is to never modify amxtest.classes (other than adding items), but instead to have your own "myamxtest.classes" and modify amxtest.properties to reference it instead of amxtest.classes.

2.3.2 Run the tests

Please see RunningUnitTests.html.

If you see any failing unit tests, be sure you haven't created the problem by first mailing amx-dev@sun.com. If you believe the problem is unrelated to your work, add the failure to the Known Issues section of RunningUnitTests.html and check in the revised file.