Update documentation to describe how to use Sonnar Runner with JUnit xml output

[jim.ju...@raytheon.com]

I struggled with a few issues that are not present in the Sonar documentation that would be nice to know for people who want to use Sonar Runner with JUnit output.

They are:

 

     I was using the sonar-project.properties file. The necessary contents for this file are not defined in a place that can be found. It should be documented that it needs to include the following

sonar.tests                                                      # Path to directory containing the tests

sonar.java.binaries                                        # Paths to directories with classes for source code being analyzed

sonar.junit.reportsPath                                  # Path to where the unit tests execution reports are

sonar.jacoco.reportPath                               # Path to where the unit tests code coverage report is

sonar.jacoco.itReportPath                           # Path to where the integration tests code coverage report is

 

     Without the Code Coverage reports being analyzed I noticed one cannot get the Unit Tests Coverage wideget to display on a project dashboard. Without the sonar.tests property being defined one can not get the Unit Test results to display only the Unit Test Coverage information will display. 

 

    I later learned a few more un-documented items about conventions for getting Unit Test results to display. They are:

 

    The file naming convention for the JUnit xml output file is important. If the file name does not start with TEST- it is ignored. This is not obvious. The Sonar Runner console output does not indicate it skips files with other names. It would be good if the console output indicated that no JUnit report file coud be found. The documentation should let people know about the file naming convention.

 

    I used Google's CodePro Eclipse plugin as a Java Unit Test framework. I ran my unit tests in Eclipse and then took the Unit Test results and exported them to a file. In my case In my simple test case I had two different classes which I tested which resulted in two different test suites, one for each class. The JUnit xml output file produced has a nested set of test suite xml tags. The output format is shown below

 

  <testsuite ...>
    <testsuite ....>

      <testcase .../>

      ....

    </testsuite>

  </testsuite>

 

   This apparently is not compatible with how Sonar Runner expects to parse the output file. The result is that it fails to extract any Unit Test information so one gets no information displayed in the Unit Test results for the Unit Test widget on the project dashboard. There should be some documentation as to what the required format should be. I would like to have been able to take the CodePro Unit test output and feed it into both Sonar and Jenkins. If the format is not supported that will not work. When I got rid of the extra testsuite tags in the CodePro JUnit output the Sonar Runner was able to read and report to the Sonar project dashboard the Unit Test results. It would ahve been good if the the Sonar Runner had reported it could nto successfully read the xml output file. Currently it reports nothing other than it is parsing the directory containing the xml output file.