For a more detailed version of the Castor Testing Framework documentation, please download the Castor Testing Framework User Document(PDF). Introduction Test Descriptor Header MarshallingTest SourceGeneratorTest UnitTestCase Listener Implementing CastorTestable dumpFields randomizeFields Running the tests Command Line options Building the CTF
Introduction One of the main processes in the life cycle of software is the 'validation and verification' process. It is a control process which checks that the requisites functions are finally obtained and eliminates faults. It is also known as the non-popular 'testing' process. The reliability and the integrity of a software project are based on tests. Being 'open-source' does not mean avoiding writing tests thus we have chosen to give to Castor an Automation Testing Framework called the Castor Testing Framework (referenced as CTF). This framework is built with JUnit and will help Castor developers but also users in several ways: | - | Improve Castor reliability. | - | Monitoring bugs will be easy since writing bug reports will be easy | - | Building an archive of fixed bugs | - | Test writing is easier. | Test Descriptor CTF test case can be stored in a directory or in a jar. Test case must contain the TestDescriptor.xml file. This file is located under the META-INF directory when using a jar file or directly under the directory that contains the test case files. This is a summary of the test cases contained in the directory or in the jar file. The TestDescriptor can be divided as follows: Header Tag | Description | Optional? | Name | The name of the test | Required | Comment | Some comment on the test | Required | Category | The category in which this test falls: | - | basic capability | - | special case | | Required | BugFix | Used to report a bug and keep track of it It is defined as follows: | - | Name of the reporter | - | Date of the report | - | Name of the 'fixer' | - | Date of the fix | | Optional | MarshallingTest Tag | Attribute | Description | Optional? | Root_Object | | - | dump: a boolean indicating that dumpFields() method has been implemented in Root_Object. | - | random: a boolean indicating that randomizeFields() method has been implemented in Root_Object. | | The qualified name of the Root object in the generated object model | Required | Mapping_File | N/A | The name of the mapping file to (if any) | Optional | SourceGeneratorTest Tag | Attribute | Description | Optional? | Schema | N/A | The name of the schema form which we generate sources | Required | Property_File | N/A | The name of the Source Generator property file to use | Optional | FieldInfoFactory | N/A | The collection type to use (Vector or ArrayList) | Required | Root_Object | | - | dump: a boolean indicating that dumpFields() method has been implemented in Root_Object. | - | random: a boolean indicating that randomizeFields() method has been implemented in Root_Object. | | The qualified name of the Root object in the generated object model | Required | UnitTestCase Tag | Description | Optional? | Name | The name of the specific test | Required | Input | The name of the input file used to create a specific Object Model while unmarshalling this file | Optional | Output | The name of the output file which can be seen as a 'gold file' | Optional | ObjectBuilder | The name of the class used to instantiate the Object Model used | Optional | Failure | A boolean that indicates if set to true that the test case intents to fail (Exception thrown) | Optional | Listener Tag | Description | Optional? | ClassName | The name of the class to use for MarshalListener and/or UnmarshalListener | Required | Type | Marshal, Unmarshal or Both. Indicate how to use the provided ClassName. | Optional, defaults to "Both". | GoldFile | The name of the output file which can be seen as a 'gold file' | Optional | Implementing CastorTestable As you may have noticed, while testing the SourceGenerator or the Marshalling Framework you have to provide the name of the 'Root Object' of your Object Model. The Root Object simply represents the mapping of the root element of the XML document. In order to be correctly used in CTF, the provided Root Object must implement the interface org.exolab.castor.tests.framework.CastorTestable . Implementing this interface is simply implementing two methods: dumpFields() and randomizeFields(). dumpFields Here is the JavaDoc of the method:
/**
* Return a recursive dump of the content of the
* object fields in a user readable format.
* This is used to retrieve the state of the object if
* castor fail to marshal the object for any reason.
*
* We don't rely on the toString() function as it could have
* been already implemented with another semantic.
*/
randomizeFields Here is the JavaDoc of the method:
/**
* The instance of the object will randomize the content
* of its field. This is used to create an instance
* of the object model without having to
* unmarshal anything.
*/
In order to tell the CTF that one (or both) of these methods is implemented you have to set the attributes 'dump' and 'random' to true in the Root_Object element: <Root_Object dump='true' random='true'>Root.java</Root_Object> Running the tests You can run the tests by using the script CTFRun.bat under Windows platform or CTFRun.sh under Linux/UNIX platform. CTFRun path of a Castor Testing Framework test (JAR or Directory). Command Line options Option | Args | Description | Optional? | -verbose | N/A | Give detailed information on the execution of each test. | Optional | -text | N/A | Run the tests without using the JUnit GUI. | Optional | -printStack | N/A | Run the tests by dumping the stack trace when an exception occurs. | Optional | -seed | int value | Specifies the use of a specific seed for the pseudo-random generator. | Optional | For instance to run all the tests from the MasterTestSuite: CTFRun -verbose .src/tests/MasterTestSuite/xml/SourceGenerator This command will execute in GUI mode (default mode) all the test cases written and will print detailed messages about the execution of the tests. Building the CTF Before trying to launch the test cases, please make sure that the CTF is compiled. To do so simply build the Castor test cases by launching: build tests You can also build the CTF jar: build CTFjar |