javadoc2xls

Motivation

This tool aims to generate test case documents (Excel worksheet) from javadoc on JUnit classes. In general, test case documents are required in enterprise software developments. It usually becomes very difficult to keep the consistency between test case documents and JUnit code when there are some modifications. This tool will resolve this problem and keep the consistency with its one-way generation mechanisim.

Image

Write test code with some javadoc including tags. Then generate javadoc with javadoc2xls, get Excel worksheet.

Get Started

1. Download and look at the example
   See the sample project. https://github.com/ikeyat/javadoc2xls/tree/master/sample

   See JUnit code (HogeTest.java, FugaTest.java) in src/java/test. You will find javadoc on these classes.

   Next, see the template Excel worksheet in report/template. You will find worksheet with some annotated cells.

   Next, see pom.xml. There is a definition to switch default javadoc generator to this tool as follows. You can modifiy the configuration if you want to tune. For example, output directory, file name convention, etc...

           <plugin>
               <groupId>org.apache.maven.plugins</groupId>
               <artifactId>maven-javadoc-plugin</artifactId>
               <configuration>
                   <doclet>jp.ikeyat.tools.javadoc2xls.Javadoc2XlsDoclet</doclet>
                   <docletArtifact>
                       <groupId>io.github.ikeyat.tools.javadoc2xls</groupId>
                       <artifactId>javadoc2xls-tool</artifactId>
                       <version>1.0.0.RELEASE</version>
                   </docletArtifact>
                   <encoding>UTF-8</encoding>
                   <useStandardDocletOptions>false</useStandardDocletOptions>
                   <additionalparam>
                       -template ${project.basedir}/report/template/sheet_01.xlsx
                       -reportdir ${project.basedir}/report/testlist
                       -reportfilename {0}_TestCaseaa({1}).xlsx
                       -sorttag @no
                       -sheetindex 0
                   </additionalparam>
               </configuration>
           </plugin>

2. Try the example!
   Go to the console, please execute Maven as follows to generate javadoc of test classes. Don't forget to switch Maven profile (-P).

   $ cd sample
   $ mvn javadoc:test-javadoc -P javadoc2xls

   Afeter execution, go to the report/testlist folder. You can find generated Excel worksheets with javadoc contents if Maven complete successfully.

Spec

Input and Output

• Input
  • Template worksheet with variables (1 file)
    • Legacy Excel workbook format (*.xls)
    • OOXML(Office Open XML) format (*.xlsx)
  • JUnit classes annotated with @Test (N files)
    • There is a fallback option for JUnit3 methods without @Test annotation
• Output
  • Generated test case documents (N workbook files)
    • Format should be same as the template.

Execution parameters

Worksheet variables

Variables are annotation to be replaced with actual values such as javadoc contents, class name, method name, timestamp, static text, etc... To write variables on worksheet template, please follow a simple grammar as follows.

Variable binding mode

This tool supports 2 variable binding modes. You can choose any mode for your purpose.

• Cell binding mode binds value at once. The replacement is never repeated for each test method. Therefore this is used to describe overview of a test class (ex. target class name).
• Row binding mode binds value repeatedly for each row of the worksheet. Number of repeats is the number of test method in a test class. This is used to describe each test method (ex. test method name).

Syntax

#{binding mode}{variable}

For example,

• #cell#className means "binds #className variable with cell binding mode"
• #row#methodName means "binds #methodName variable with row binding mode"

Variables

Hints

If you have the maven-javadoc-plugin config for javadoc2xls, you cannot get standard HTML style javadoc of your test code. Maven profile will help this problem. I recommend that you have the config for javadoc2xls with the minor Maven profile, not the default profile for the people who don't know javadoc2xls.

Other cases, if you would like to get standard javadoc of test code additionally, custom tag option will be helpful. You can find a simple example. For more detail, see https://maven.apache.org/plugins-archives/maven-javadoc-plugin-2.8.1/examples/tag-configuration.html.

Migration from old version

javadoc2xls was published at https://github.com/ikeyat/xls2conf/tree/master/javadoc2xls. If you are an old user, please migrate javadoc2xls as follows.

1. Change a groupId and artifactId of javadoc2xls in a pom.xml of your application.

   • Replace groupId from com.example.tools.xls2conf.javadoc2xls to io.github.ikeyat.tools.javadoc2xls.
   • Replace artifactId from javadoc2xls to javadoc2xls-tool

2. Change a package name of Javadoc2XlsDoclet in a pom.xml of your application.

   • Replace <doclet>com.example.tools.xls2conf.javadoc2xls.Javadoc2XlsDoclet</doclet> to <doclet>jp.ikeyat.tools.javadoc2xls.Javadoc2XlsDoclet</doclet>

3. Don't require to build the tool by yourself. javadoc2xls has been managed at Maven Central. It's available without your buiding as other major OSS libraries are.