[jdom-interest] jdom-test issues

[GB/DEV - Philip Nelson]

Well it's been quite awhile since we've discussed the status of jdom-test.
Since beta six is out and the jdom jsr is launched, I think it's probably
time to reconvene this effort.  A few things have changed since we started
it and I would like to have those of us involved agreee to a course of
action to make this part of the project useful and to complete considerably
before the launch.  

First of all, use cases.  Jools and I were initially thinking of the test
suite being used in an XP sort of way by other developers.  Well, it's long
past that point now and after having used the part of the suite I wrote
myself, I think our idea to separate methods into test classes was an
inconvienient way to structure the tests.  Here is what I think we are
trying to accomplish.

JDOM developer use cases
1 - Run an AllTests unit test suite to verify correct behaviour of all JDOM
classes
2 - Run a test suite for the a single class while making changes to that
class
3 - Run compliance tests to test the "system" against known xml documents

JDOM - Test developer use cases
1 - generate test stubs for all unimplemented methods into existing test
case source files
2 - generate AllTests suite from tests in the org.jdom.test.cases package
3 - add test cases to the suite that do not fit a single jdom class test
4 - all use cases for JDOM developers

JDOM user use cases
jdom-test will not be part of the standard distribution so a JDOM user is
not expected to run the test suite

Additional requirements
- All jdom-test tests can be run from an Ant build script
- all tests are created for the JUnit framework
- unit tests will not be subject to external data requirements (no xml files
to maintain)
- compliance tests will require external data files and will be part of the
jdom-test distribution. This test data directory path will be accessed via a
resource bundle called org.jdom.test.JdomTests.properties and set initally
to "."
- if possible, compliance tests will be against industry standard tests as
they become available.  (I understand Oasis had some effort in this
direction)  
- tests will clean up any files they produce  
- Failure messages will provide enough detail to track the problem to the
correct method and step
- test cases not tied to a single jdom class will have a name beginning with
Test<meaningful verbage>.java
- the suite method of any test case will default to running all tests in the
case
- a main method will be provided with each test case to make it easier to
run individual tests without Ant
- test cases will be organized so that the test is easy to find knowing the
jdom class you want to test. 
 
  org.jdom.Attribute.java ---> org.jdom.test.cases.TestAttribute.java 
  where TestAttribute.java contains tests for all constructors and methods
of Attribute.java
- test methods will follow this naming convention

  test_XXX__<return type>_<method to test>(<parameter type> | ...)

example in Comment.java, public String getText() becomes...

    public void test_TCM__String_getText() {
        fail("implement me !");
    }

in a file called TestComment.java.  XXX is replaced by TCM for methods and
TCC for constructors.


That's fairly simple I think and covers what I currently imagine to be the
main needs of this test suite.   I think much else would be overkill and
that the real purpose of the test suite is regression testing and additional
assurance (beyond the open source process) that the code works as expected.
How to test the inputters and outputters is a little unclear though.
Compliance testing could turn it into a much bigger project.  The naming
convention is driven by Jools' initial naming convention and by the newer
retrospection features of JUnit which may be all we need to accomplish jdom
developer use case #1.  

Opinions?

Jools, I have the modified generator to accomplish much of this, including
appending to an existing test case file if it already exists.  It will
search the class path to find the corresponding test case and if it finds
it, will retrospect the methods to figure out which new tests to append to
the source file.  It does NOT parse the source file to find implemented
methods.  Let me know and I'll upload this to CVS.  Have you completed
anymore test cases to load?

Any problem with updating to JUnit 3.5?