Best practices of writing tests

1)  TESTS:
    Tests are written under version they apply to. For e.g. all tests related to
    v2 should be written under v2/test

    The test folder is broken down into
    a) src
    b) cases
    c) tools

    Below are the uses for each of the folders.
    a) Src:

    This is where the actual test cases (in this case junit driver) live. The src
    folder is divided by functional areas at the highest level.

    Each functional area is further sub divided by smaller functional areas (if
    required). If the division is not required then functional area is divided
    by importance of the tests. Importance are of 2 types

    a) Checkin
    b) Detailed.

    As the names suggest checkin tests are really important tests for a particular
    area while Detailed tests aim is to test more of edge cases/error condition/
    various kinds of input etc.

    Not each top-level functional area needs to have checkin folder. If that area
    is not that widely used in the product there might just be detailed folder.

    Since checkin tests have to be run by all developer every time they checkin
    the goal is to include the most crucial tests for each functional area of
    the product.

    Also each top level/sub functional area can have a Common folder. The main
    goal here is group smaller utilities used to test functional area in one
    place so that both the Checkin/Detailed tests can use. If you feel the tools
    you are writing can be share across Cross-functional areas then use the Tools
    folder (more to come later in the doc). Any class which is not itself a Junit
    test should go into that folder, even if it is a superclass for a Junit test
    in the checkin/detailed folder. Same goes for all interfaces.


    Below is an e.g. of how one of the top-level functional area's directory
    structure may look like.

    xmlcursor/
            |-checkin/
            |-detailed/
            |-common/
            |-saver/
            |     |-detailed/
            |     |-common/
            |-xpath/
            |     |-checkin/
            |     |-detailed/
            |     |-common/


    In this e.g. the xmlcursor area is broken down by checkin/detailed tests for
    smaller functionality that is cursor specific. For functionality in the
    cursor that is bigger sub folders are created with its own checkin/detailed/
    common areas. Again saver does not have a checkin folder since the tests in
    this area are not too important.

    Overall when writing a test please consider which areas they fit and only
    create sub folder/top level folders only if necessary.

2) CASES:
   This contains schema files/xml instances belonging to those schemas and schema
   independent xml instances which can be shared within the functional areas.

   Cases is further divided into top level areas matching src folder and all
   schemas/xml instances used by functional areas are placed within this.

   All schemas are compiled with scomp during the build process before compiling
   the tests. If you have added a top level folder to src then the schemas & xml
   instances for those tests should have their top-level folder within cases/xbean.
   If these schemas need to be compiled by scomp you will need to edit the
   testbuild.xml file to include the new folder in the build. Add this folder
   to the variable "schema.dirs". (More details below)


   If you are just adding schemas to existing folders within xbean/cases then
   these will be automatically picked up in the build process.

   If you have schemas that you don't want to pre compile in the build process
   please rename the extension from .xsd to .xsddonotcompile. In this way scomp
   will not pick up pre compile the schema.

   The best practice for the cases folder is to try to reuse schemas within the
   functional areas. So please check the schemas we have before adding more schemas.

   Since currently the directory structure is such that process sharing of
   schemas exists within top level functional areas (e.g. all tests with
   xmlcursor can reuse the schemas) there is some amount of duplication since
   schemas are not shared among top level functional areas. (for e.g. xmlcursor
   & xmlobject will not have schemas shared among them). Though we recognize this
   and are making attempts to revise the directory structure this has
   implications on how the tests run so for the immediate future this might stay
   as it is.


3) TOOLS:
    The tools area is meant for storing tools/utilities which help running the
    tests and reporting results. If you feel you have written a tool which could
    be used across all functional areas please put the source within tools/src.
    However before adding a tool please check the existing tools which we already
    have.

4) BUILD FILE CHANGES:
    Depending on how tests and cases are added, the build file (testbuild.xml)
    will need to be updated.

    a) New folder containing schemas added to cases:
       Append this folder to the property schema.dirs
        e.g:
        Old value:
        <property name="schema.dirs"
                value="${build.dir.test.schemas}/xbean/xmlcursor"/>

        New value:
        <property name="schema.dirs"
                value="${build.dir.test.schemas}/xbean/xmlcursor,
                       ${build.dir.test.schemas}/xbean/NEWAREA"/>
        If your schemas are needed in order to run checkintests please update the 
        "checkin.schema.dirs" property as well.


    b) New top-level area added to test (src/NEWAREA)
       Add this folder to the list of areas for incremental compile
       * Append the area name to the property area.names
       * Add a new target with the name "build.area.NEWAREA"

         Properties that need to be set for this target to work
             * includes.for.compile - includes spec for javac

         Optionally set the following properties
             * this.schema.dirs - list of folders for scomp
             * this.schema.standalone.dirs - list of individual schemas for scomp
             * testcasesjar.update - set to true if testcases.jar should be
                                     updated instead of overwriting

         Add a call to target "unit.build" at the end of the target.

         e.g:
         <target name="build.area.xmlcursor">
            <property name="this.schema.dirs"
                value="${build.dir.test.schemas}/xbean/xmlcursor"/>
            <property name="includes.for.compile"
                value="**/xmlcursor/**/*.java"/>
            <property name="testcasejar.update" value="true"/>
            <antcall target="unit.build"/>
        </target>