About GroboUtils

• Welcome
• License
• Project List
• Contacts
• Articles

Sourceforge
Project

• Forums
• Bugs
• Feature Requests

For Developers

• Downloads
• Javadoc
• Dependencies
• Building

GroboTestingJUnit version 1.2.1

Author:Matt Albrecht

This document will build a fairly complex and very contrived example application, along with simple sample tests to show how to use the IFTC in complicated and simple hierarchies.

Our example app will attempt to find all CVS registered files in a path. CVS is a common Source Control Repository used in this project and many other open source projects, but the description of its files beyond what this document uses is beyond this document's scope. This app will not recurse directories, but rather scan a depth of directories, as if the user was navigating through them in a shell via the "chdir" command ala UN*X or DOS.

I won't follow the XP methodology in this article. I'll present the project source code, then follow it up with the tests. One could just as easily show the tests first, then the code, but I feel that it makes the tests clearer by showing the code first. This is important to this article because the focus is on tests, not the project source it tests.

The IFileVisitor Interface

We start by creating an interface that does something with each discovered CVS file. We will, however, make it generic enough that the visitor pattern it represents can be used by any project.

   1:public interface IFileVisitor {
   2:    public void visitFile( String fileName );
   3:}

   1:public class IFileVisitorTestI extends InterfaceTestCase {
   2:    private static final Class THIS_CLASS = IFileVisitorTestI.class;
   3:
   4:    public IFileVisitorTestI( String name, ImplFactory f ) {
A  5:        super( name, IFileVisitor.class, f );
   6:    }
   7:
   8:    protected IFileVisitor createIFileVisitor(){
B  9:        return (IFileVisitor)createImplObject();
  10:    }
  11:    
  12:    public void testVisitFile1() {
  13:        IFileVisitor fv = createIFileVisitor();
  14:        try {
  15:            fv.visitFile( "" );
  16:            fail( "Did not throw IllegalArgumentException." );
  17:        } catch (IllegalArgumentException iae) {}
  18:    }
  19:
  20:    public void testVisitFile2() {
  21:        IFileVisitor fv = createIFileVisitor();
  22:        try {
  23:            fv.visitFile( null );
  24:            fail( "Did not throw IllegalArgumentException." );
  25:        } catch (IllegalArgumentException iae) {}
  26:    }
  27:
  28:    public static InterfaceTestSuite suite() {
C 29:        return new InterfaceTestSuite( THIS_CLASS );
  30:    }
  31:}

• A: The constructor must follow this signature. It calls to the super class' constructor with the passed-in information, along with the class of the interface or class that this test will expect from the createImplObject method.
• B: Usage of a helper method to perform casting on the owned factory.
• C: The new format of the suite() method may take any form the test writer likes, since interface tests cannot be directly instantiated and tested by JUnit. In this case, it makes sense to have the suite() method take the standard JUnit form, so that users can more easily use the familiar form. Also, the returned type is a InterfaceTestSuite, so that no unnecessary casting needs to be done.

A Class To Help Debugging

For the sake of example, we'll create a prototype visitor of the above interface to help users test and debug their code.

   1:public class LoggingFileVisitor implements IFileVisitor {
   2:    private PrintStream out;
   3:    public LoggingFileVisitor( PrintStream ps ) {
   4:        if (ps == null) throw new IllegalArgumentException();
   5:        this.out = ps;
   6:    }
   7:    
   8:    public void visitFile( String s ) {
   9:        if (s == null || s.length() <= 0) throw new IllegalArgumentException();
  10:        this.out.println( "Visited "+s );
  11:    }
  12:}

The test for this code can use the interface's tests to aid in ensuring that the new class conforms to the interface's contract.

   1:public class LoggingFileVisitorTest extends TestCase {
   2:    private static final Class THIS_CLASS = LoggingFileVisitorTest.class;
   3:    public LoggingFileVisitorTest( String name ) {
   4:        super( name );
   5:    }
   6:    
   7:    public void testConstructor1() {
   8:        try {
   9:            new LoggingFileVisitor( null );
  10:            fail( "Did not throw IllegalArgumentException." );
  11:        } catch (IllegalArgumentException) {}
  12:    }
  13:    
  14:    public void testVisitFile1() {
  15:        StringWriter sw = new StringWriter();
  16:        LoggingFileVisitor fv = new LoggingFileVisitor( new PrintStream(
  17:            sw, true ) );
  18:        fv.visitFile( "a" );
  19:        assertEquals( sw.toString(), "Visited a" );
  20:    }
  21:    
  22:    public static Test suite() {
A 23:        InterfaceTestSuite suite = IFileVisitorTestI.suite();
  24:        suite.addFactory( new ImplFactory() {
B 25:            public Object createImplObject() {
  26:                return new LoggingFileVisitor( System.out );
  27:            } } );
C 28:        suite.addTestSuite( THIS_CLASS );
  29:        return suite;
  30:    }
  31:}

• A: Since LoggingFileVisitor inherits from ("implements" technically) IFileVisitor, the concrete test "inherits" the tests from IFileVisitorTestI by pulling in its test suite.
• B: These inherited tests are executed in the context of LoggingFileVisitor by
• C: The tests defined in the concrete test class are added to the suite, and interpreted just like the standard JUnit TestSuite does.

The IDirectoryVisitor Interface

Now we'll create an interface to handle the visitor pattern for directories. Since CVS stores the listing of checked-out files locally in a file called "CVS/Entries" under each module directory, the final implementation will use this to check if the entered directory is a valid CVS module dir. Also, to add double-duty and bad design, this interface will handle the state of the current directory the user is in. Any non-null, non-empty directory can be pushed, put only the valid ones will be processed.

   1:public interface IDirectoryVisitor {
   2:    public void pushDir( Stirng name );
   3:    public void popDir();
   4:    public String getCurrentDirectory();
   5:    public void visitCurrentDir();
   6:}

Here's the test:

   1:public class IDirectoryVisitorTestI extends InterfaceTestCase {
   2:    private static final THIS_CLASS = IDirectoryVisitorTestI.class;
   3:    public IDirectoryVisitorTestI( String name, ImplFactory f ) {
   4:        super( name, IDirectoryVisitor.class, f );
   5:    }
   6:    
   7:    protected IDirectoryVisitor createIDirectoryVisitor() {
   8:        return (IDirectoryVisitor)createImplObject();
   9:    }
  10:    
  11:    public void testPushDir1() {
  12:        IDirectoryVisitor dv = createIDirectoryVisitor();
  13:        try {
  14:            dv.pushDir( null );
  15:            fail( "Did not throw IllegalArgumentException." );
  16:        } catch (IllegalArgumentException e) {}
  17:    }
  18:    
  19:    public void testPushDir2() {
  20:        IDirectoryVisitor dv = createIDirectoryVisitor();
  21:        try {
  22:            dv.pushDir( "" );
  23:            fail( "Did not throw IllegalArgumentException." );
  24:        } catch (IllegalArgumentException e) {}
  25:    }
  26:    
  27:    public void testPopDir1() {
  28:        IDirectoryVisitor dv = createIDirectoryVisitor();
  29:        try {
  30:            dv.popDir();
  31:            fail( "Did not throw IllegalArgumentException." );
  32:        } catch (IllegalArgumentException e) {}
  33:    }
  34:    
  35:    public void testPopDir2() {
  36:        IDirectoryVisitor dv = createIDirectoryVisitor();
  37:        String s = dv.getCurrentDir();
  38:        dv.pushDir( "A" );
  39:        dv.popDir();
  40:        assertEquals( s, dv.getCurrentDir() );
  41:    }
  42:    
  43:    public static InterfaceTestSuite suite() {
  44:        return new InterfaceTestSuite( THIS_CLASS );
  45:    }
  46:}

IFileDirectoryVisitor Interface

The next interface has a lot of assumptions about implementations. Since it combines a directory and file visitor together with a bad design, it expects visited directories to visit each file in that directory.

   1:public interface IFileDirectoryVisitor
   2:        extends IFileVisitor, IDirectoryVisitor {
   3:}

Since this does not define any new explicit functionality, the tests are relatively simple. Again, remember that this design is contrived for the sake of example.

   1:public class IFileDirectoryVisitorTestI extends InterfaceTestCase {
   2:    private static final Class THIS_CLASS = IFileDirectoryVisitorTestI.class;
   3:    public IFileDirectoryVisitorTestI( String name, ImplFactory f ) {
   4:        super( name, IFileDirectoryVisitor.class, f );
   5:    }
   6:    
   7:    protected IFileDirectoryVisitor createIFileDirectoryVisitor() {
   8:        return (IFileDirectoryVisitor)createImplObject();
   9:    }
  10:    
A 11:    public void testToString1() {
  12:        IFileDirectoryVisitor fdv = createIFileDirectoryVisitor();
  13:        assertNotNull( fdv.toString() );
  14:    }
  15:    
  16:    public static InterfaceTestSuite suite() {
  17:        InterfaceTestSuite suite = IFileVisitorTestI.suite();
B 18:        suite.addTestSuite( IDirectoryVisitorTestI.suite() );
  19:        suite.addTestSuite( THIS_CLASS );
  20:        return suite;
  21:    }
  22:}

• A: If we did not add at least one test, then the IFTC would register this test class without tests as a failure.
• B: Here, since the interface extends two interfaces, we simply register each's test in turn to imitate the test "inheritance" language defined by the framework. The current test is registered, and the completed hierarchy suite is returned. Since both inherited tests define in their constructor that they test classes which complement the IFileDirectoryVisitorTestI's class-under-test, all suites can share the same registered ImplFactory instances.

AbstractDirectoryParser

Now, let's move to an abstract, common implementation of IDirectoryVisitor. This will parse the equivalent of the "chdir" command, translating it into a "push", "pop", or do-nothing. It will call out to an abstract method to see if the entered dir is "special", and will call the visit method if it is.

   1:public abstract class AbstractDirectoryParser implements IDirectoryVisitor {
   2:    private Stack stack = new Stack();
   3:    private String currDir, parentDir, sep;
   4:    
   5:    public AbstractDirectoryParser( String current, String parent,
   6:            String seperator ) {
   7:        if (current == null || parent == null || seperator == null ||
   8:            current.length() <= 0 || parent.length() <= 0 ||
   9:            seperator.length() <= 0 ) throw new IllegalArgumentException();
  10:        this.currDir = current;
  11:        this.parentDir = parent;
  12:        this.sep = seperator;
  13:    }
  14:    
  15:    public String getCurrentDir() {
  16:        StringBuffer sb = new StringBuffer();
  17:        Enumeration enum = this.stack.elements();
  18:        boolean isFirst = true;
  19:        while (enum.hasMoreElements()) {
  20:            if (isFirst) isFirst = false;
  21:            else sb.append( this.sep );
  22:            
  23:            sb.append( enum.nextElement() );
  24:        }
  25:        return sb.toString();
  26:    }
  27:    
  28:    public void enterDir( String s ) {
  29:        if (s == null || s.length() <= 0) throw IllegalArgumentException();
  30:        if (s.equals( this.parentDir )) popDir();
  31:        else if (!s.equals( this.currDir )) pushDir( s );
  32:        if (isSpecial( getCurrentDir() )) visitCurrentDir();
  33:    }
  34:    
  35:    public void pushDir( String s ) {
  36:        if (s == null || s.length() <= 0 || s.equals( this.parentDir ) ||
  37:            s.equals( this.currDir ) || s.equals( this.sep ))
  38:            throw new IllegalArgumentException();
  39:        
  40:        this.stack.push( s );
  41:    }
  42:    
  43:    public void popDir() {
  44:        if (this.stack.size() <= 0) throw new IllegalStateException();
  45:        this.stack.pop();
  46:    }
  47:    
  48:    public abstract boolean isSpecial( String aDir );
  49:}

We can create two test classifications for this: one that performs "mock-object"-like testing, by creating an internal concrete class, and an inheritable test class. Let's start with the inheritable one.

   1:public class AbstractDirectoryParserTestI extends InterfaceTestClass {
   2:    private static final Class THIS_CLASS = AbstractDirectoryParserTestI.class;
   3:    
   4:    public interface AbstractDirectoryParserImplFactory {
   5:        public AbstractDirectoryParser createAbstractDirectoryParser(
   6:            String c, String p, String s );
   7:    }
   8:    
   9:    public AbstractDirectoryParserTestI( String name, ImplFactory f ) {
A 10:        super( name, AbstractDirectoryParserImplFactory.class, f );
  11:    }
  12:    
  13:    protected AbstractDirectoryParser createAbstractDirectoryParser(
  14:            String curr, String parent, String sep ) {
B 15:        return ((AbstractDirectoryParserImplFactory)createImplObject()).
  16:            createAbstractDirectoryParser( curr, parent, sep );
  17:    }
  18:    
  19:    public void testGetCurrentDir1() {
  20:        AbstractDirectoryParser adp = createAbstractDirectoryParser(
  21:            ".", "..", "_" );
  22:        assertEquals(
  23:            "",
  24:            adp.getCurrentDir() );
  25:    }
  26:    
  27:    public void testGetCurrentDir2() {
  28:        AbstractDirectoryParser adp = createAbstractDirectoryParser(
  29:            "1", "12", "123" );
  30:        adp.enterDir( "A" );
  31:        adp.enterDir( "B" );
  32:        adp.enterDir( "2" );
  33:        adp.enterDir( "12" );
  34:        adp.enterDir( "C" );
  35:        adp.enterDir( "1" );
  36:        adp.enterDir( "D" );
  37:        assertEquals( "A123B123C123D", adp.getCurrentDir() );
  38:    }
  39:    
  40:    public static void suite( InterfaceTestSuite stdFactorySuite,
  41:            InterfaceTestSuite adpFactorySuite ) {
C 42:        stdFactorySuite.addTestSuite( IDirectoryVisitorTestI.suite() );
  43:        adpFactorySuite.addTestSuite( THIS_CLASS );
  44:    }
  45:}

• A: Since the tests, to be "interesting", require additional knowledge of the starting state for the AbstractDirectoryParser under test, it requires subclass tests to construct an AbstractDirectoryParserImplFactory rather than an AbstractDirectoryParser directly. The method testGetCurrentDir2() shows why this can be powerful. Note that these factories may have multiple construction methods for different kinds of setup.
• B: Since the test uses a factory to create AbstractDirectoryParser instances, the helper builder method changes accordingly.
• C: Since AbstractDirectoryParser implements IDirectoryVisitor, AbstractDirectoryParserTestI should "inherit" the tests from IDirectoryVisitorTestI. And, AbstractDirectoryParserTestI is an interface test, so it merely constructs the suite to test, but does not add factories itself. However, IDirectoryVisitorTestI and AbstractDirectoryParserTestI use different implementation classes which are not directly related to each other, and as such they cannot share ImplFactory instances. So, AbstractDirectoryParserTestI resolves this by requiring the two different suites to be passed in, allowing the user of the suites to make the differentiation when adding the specialized factory implementations. Remember, since the Interface test classes are not directly run by the JUnit framework, we can form the suite method however we want.

The mock-object version of the test follows. Note that both the above inheritable test and the below concrete test can co-exist in the same test class path due to the naming convention used in this document.

   1:public class AbstractDirectoryParserTest extends TestCase {
   2:    private static final Class THIS_CLASS = AbstractDirectoryParserTest.class;
   3:    public AbstractDirectoryParserTest( String name ) {
   4:        super( name );
   5:    }
   6:    
   7:    private class MyADP extends AbstractDirectoryParser {
   8:        String specialDirName = " ";
   9:        public boolean isSpecial( String name ) {
  10:            return name.endsWith( specialDirName );
  11:        }
  12:        
  13:        int visitCount = 0;
  14:        public void visitCurrentDir() {
  15:            ++visitCount;
  16:        }
  17:    }
  18:    
  19:    public void testVisit1() {
  20:        MyADP adp = new MyADP( ".", "..", "/" );
  21:        adp.enterDir( " " );
  22:        adp.enterDir( "." );
  23:        adp.enterDir( "A" );
  24:        adp.enterDir( ".." );
  25:        adp.enterDir( " " );
  26:        assertEquals( 4, adp.visitCount );
  27:    }
  28:    
  29:    private class MyADPImplFactory
  30:            implements AbstractDirectoryParserImplFactory {
  31:        public AbstractDirectoryParser createAbstractDirectoryParser(
  32:                String c, String p, String s ) {
A 33:            return new MyADP( c, p, s );
  34:        }
  35:    }
  36:    
  37:    public static Test suite() {
B 38:        InterfaceTestSuite std = new InterfaceTestSuite();
  39:        InterfaceTestSuite dif = new InterfaceTestSuite();
  40:        std.addFactory( new ImplFactory() {
  41:            public Object createImplObject() {
  42:                return new MyADP( ".", "..", "/" );
  43:            }
  44:        } } );
  45:        dif.addFactory( new ImplFactory() {
  46:            public Object createImplObject() {
  47:                return new MyADPImplFactory();
  48:        } } );
  49:        AbstractDirectoryParserTestI.suite( std, dif );
C 50:        TestSuite ts = new TestSuite( THIS_CLASS );
  51:        ts.addTestSuite( std );
  52:        ts.addTestSuite( dif );
  53:        return ts;
  54:    }
  55:}

• A: We need to provide an AbstractDirectoryParserImplFactory instance, so this is the test's verson for the mock-object MyADP. We could have just as easily provided an anonymous innner class.
• B: We create two new InterfaceTestSuites, load each with its own factory type, then pass this into the AbstractDirectoryParserTestI suite so it can add its appropriate test suites.
• C: We join these two seperate suites inside a single TestSuite, then add the current test class to the suite, and return it. Since the two seperate InterfaceTestSuites remain seperate inside the TestSuite, they will not share factories, and there will be no test construction problems.