It must be easier to write tests
Unit tests are a vital development tool. It should be as easy as possible to write tests and to execute them.
Currently we have to do several steps to write a test.
- Create a new directory for the test.
- Create a new Makefile.am. This normally involves a lot of copy and paste from an existing test.
- Add a new init.c file. Which may be enough for simple tests.
- Add a test.doc file for the documentation.
- Add a test.scn file with the output of the test.
- Modify the top level Makefile.am.
- Modify the top level configure.ac.
- Run bootstrap.
- Add a copy and paste .cvsignore.
- Write a ChangeLog? with several entries.
This is way to much work. A lot of copy and paste is involved. What do we really need?
- An extra directory for each test case is not needed. We can use different file prefixes for each test case.
- Not necessary if we don't have an extra directory.
- This is the core.
- The *.doc files are pretty useless in the current format. We should define guidelines how do to document tests. We should write them in a machine and human readable form. I propose Doxygen. If someone does not like Doxygen it is trivial to write a parser that transforms the Doxygen comments into something else.
- These files are useless and hard to maintain. The test output should clearly state if a test failed or passed or whatever. The test output should be in a standard format to allow programs to determine the test outcome easily.
- We need this.
- We likely don't have to modify the configure.ac.
- We need this.
- We likely don't have to modify the .cvsignore.
- The ChangeLog? entry is now much easier.
Replying to comment:10:
I copied the description into http://www.rtems.org/wiki/index.php/RTEMS_Test_Template and noted what was completed and what was left to do...
There were several comments that went into different directions, but I didn't completely capture all of those, as they were not in the description, but below is my understanding of them, and where they could be addressed...
Comment 1: looks like Sebastian Huber solved part of the problem.
Comment 2: new stuff was added, looks like requirements traceability and simulator verification of screen-shots. I should explicitly state requirements traceability in http://www.rtems.org/wiki/index.php/RTEMS_Test_Specification , and simulator verification in http://www.rtems.org/wiki/index.php/RTEMS_Test_Screen_Validation
Comment 3: a new thread related to some sort of coverage testing hook, which I thought was probably address in http://www.rtems.org/wiki/index.php/RTEMS_Test_Coverage
Comment 4: back to requirements traceability, but this time, embedded into the code. I could explicitly state requirements traceability in http://www.rtems.org/wiki/index.php/RTEMS_Test_Specification is to be embedded in the init.c
Comment 5: some vague argument related to what format the output text should be in... I'll probably write up the tests should be commented in RTEMS doxygen format and gloss over with a statement that there must exist a technology to convert doxygen comments into .texi (possibly even doxygen does this, but I'm not sure)
Comment 6: some question as to where to place comments, and the format of them, probably could be in http://www.rtems.org/wiki/index.php/RTEMS_Test_Specification
Comment 7: Is there a specific direction you wanted to go with this? There are some really good ideas for how to write up the additional issues brought up in the previous comments.
My personal take on this is the write-ups will need to be easy to understand and the results easy to maintain. Although doxygen may not be the "be all" and "end all" of documentation, it would meet Sebastian's desire to have the comments in the same file as the code. The way to do requirements traceability using doxygen would be:
Grouping by class using something akin to.
http://www.longacre-scm.com/blog/index.php/2010/08/using-doxygens-test-command-with-c
For traceability, add custom doxygen tags, such as:
@requirement (in the the source file)
and
@see (in the test file pointing to the functions being tested)
Again, if doxygen is not the format of choice, the tags should help with requirements traceability using another static analysis tool, it's just that we use doxygen in other parts of the code.
IMO the doxygen commenting (in a way towards getting tests standards compliant) of the existing tests should be a GCI task, which I will work on writing up, if that would meet the need.