Framework for Testing Serialization

The framework for testing serialization is currently PROPOSED and being discussed on the development mailing list dev@harmony.apache.org. Please direct comments and questions there.

The framework for testing serialization is intended to simplify and formalize development of serialization tests. This document contains guidelines for creating tests and conventions for resource files.

Guidelines for Developing Serialization Tests

The testing framework provides the support class org.apache.harmony.testframework.serialization.SerializationTest for serialization testing.

Compatibility Testing

Verifies that an object serialized on certified implementation is correctly deserialized on Harmony implementation.
The support class provides four methods for compatibility testing:


                            verifyGolden(TestCase, Object)
                            
                                verifyGolden(TestCase, Object, SerializableAssert)
                            
                            verifyGolden(TestCase, Object[])
                            
                                verifyGolden(TestCase, Object[], SerializableAssert)

The first parameter TestCase is used to locate resource file(s) that contains serialized object(s).
The second parameter is an object or an array of objects to be compared with object(s) deserialized from resource file(s).
The third parameter is optional.

To create a compatibility test for selected class, a developer should:

Serialize object(s) on certified implementation, store serialized form(s) in resource file(s) and place it(them) according to the conventions
Add the testSerializationCompatibility method to a unit test
Invoke one of the methods, mentioned above, with corresponding arguments

Example

public void testSerializationCompatibility()
throws Exception {
SerializationTest.verifyGolden(this, new SomeSerializableClass());
}

Self-Testing

Verifies that an object can be smoothly serialized and deserialized on Harmony implementation.
The support class provides four methods for self-testing:


                        verifySelf(Object)
                        
                            verifySelf(Object, SerializableAssert)
                        
                        verifySelf(Object[])
                        
                            verifySelf(Object[], SerializableAssert)

The provided object(s) is(are) serialized/deserialized and compared with initial object(s).

To create a self test for a selected class, a developer should:

Add the testSerializationSelf method to a unit test
Invoke one of the methods with corresponding arguments

Example

public void testSerializationSelf() throws Exception {
SerializationTest.verifySelf(new SomeSerializableClass(),
new MyComparator());
}

Negative Testing

TBD

Interface SerializableAssert

If a class of object(s) to be compared does not have equals(Object) method or the testing framework can not find appropriate comparator, a test has to implement the interface. The interface has only one method to be implemented:

void assertDeserialized(Serializable reference, Serializable test);

Placement and Naming Conventions for Resource Files

The resource files should follow the next conventions:

Root folder for resource files is <module root>/src/test/resources/serialization
Relative path to a resource file MUST match a test's package name
A resource file MUST start with a test's name
A resource file MUST contain keywords pointing out to testing scenario
1. <golden> keyword is used for files generated on RI
2. <harmony> keyword is used for files generated on Harmony implementation
3. <negative> keyword is used for files that contain broken serial form
A resource file name MUST contain some index
Note

If only one file exists, the index is not required.

Extension for resource files is ser

Example

For the test org.apache.harmony.tests.java.lang.SomeClassTest, we have the following resource files:

modules/luni/src/test/resources/serialization
|
\---org/apache/harmony/tests/java/lang
|
\---SomeClassTest.golden.0.ser
    SomeClassTest.golden.1.ser
    SomeClassTest.golden.2.ser
    SomeClassTest.harmony.0.ser
    SomeClassTest.harmony.1.ser
    SomeClassTest.negative.ser