Learning Cobertura

Learning Something

Learning Something tutorials like this one were initially developed for my own personal use. They are a way for me to capture what I am learning as I learn it. I find that documenting what I am learning helps me to absorb the lessons better. They are also a great way for me to go back to something that I haven’t worked on for a while and quickly refresh my memory.

Because I am a newbie at whatever I am learning, these tutorials tend to be very basic. They are step-by-step instructions prepared by a newbie. Consequently, they may not show the best way to do something. They just show how I understood things at the time. Still, I hope you will benefit from my sharing of these tutorials and I hope you will add comments where you know a better way so we can all learn from each other.

I hope you enjoy and benefit from the Learning Something tutorials. Enjoy!

Learning Cobertura

Cobertura is a freely available Java code coverage tool. In this document I outline how to generate Cobertura code coverage reports for a Maven project developed using NetBeans integrated development environment.

References

The following references were used to compile this document:

http://cobertura.sourceforge.net/mavenCobertura.html (which I translated from Spanish to English using Google translate)
http://javadude.wordpress.com/2009/09/25/tutorial-getting-started-w... (which helped make the application and tests easier to demonstrate).
http://mojo.codehaus.org/cobertura-maven-plugin/usage.html (which provided the instructions for adding the Cobertura plug-in for our project )
http://www.wakaleo.com/blog/292-site-generation-in-maven-3 (which provides the revised instructions for adding reporting plug-ins under Maven 3)
http://wiki.netbeans.org/MavenBestPractices#section-MavenBestPracti... (also helpful for using NetBeans and Maven together)
http://stackoverflow.com/questions/1220525/how-to-generate-a-maven-... (which explained how to run Maven Site command from within NetBeans).

Pre-requisites

You need to download and install NetBeans, Maven and Cobertura in order to follow this lesson. The tutorial was prepared using NetBeans 7.0 Beta, Maven 3 and Cobertura 1.9.4.1.

You do not require any prior knowledge of Cobertura to follow this tutorial. However, familiarity with Java development, NetBeans and Maven would be helpful.

Part 1: Create a Project to Test

Step 1.1: Create Maven Project

In NetBeans, open the File menu and select New Project... to open the New Project dialog box shown below.

In the Categories list, select Maven and in the Projects list select Java Application. Click the Next button to continue.

Set the project name to CoberturaMavenTutorial, choose an appropriate project location and input the Group Id you wish to use as shown in the image above. Click the Finish button to create the project.

NetBeans creates our project, as shown below.

Notice the BUILD SUCCESS message in the Output panel below the start page. That indicates that the project has been successfully created. In addition, notice the project structure and files shown in the Projects panel that appears below the NetBeans menu.

Step 1.2: Get Familiar with our Project Structure and Files

Let’s take a closer look at our project before we make any changes. The structure of the project is defined by the first level folders you can see in the image above (see the Projects panel in the top left corner under the NetBeans IDE menu). These folders are:

Source Packages – contains our source code
Test Packages – contains the tests for our application
Dependencies – contains any libraries or archives that our project is dependent upon
Test Dependencies – contains libraries and archives that our test packages are dependent upon
Project Files – contains our Maven project definition file, pom.xml.

We will refer to these folders and the files they contain as we work through this tutorial.

Step 1.2.1: Source Packages

Let’s open the App.java file to view our project source code. You can open the file by right clicking on the App.java file name in the Projects panel and selecting Open from the pop-up menu or by simply double clicking on the file name.

As we can see this is a Java main class that prints “Hello World!”

Let’s run the project to see if our understanding is correct. Right click on the project name in the Projects panel and select Run from the pop-up menu. You should be prompted to select the main class for execution, with only one file available to select, as shown below.

Select the Remember Permanently option as shown above and click the Select Main Class button to run the project.

You should notice some activity in the Output panel below the App.java class. Maven is building your project, including downloading any project dependencies defined in the pom.xml file (which we will discuss later). Maven also runs the project and, if all works as intended, you should see the “Hello World!” message from our App class displayed in the Output panel.

Notice the “Hello World!” and “BUILD SUCCESS” messages in the Output panel in the lower part of the image above. These indicate that the project we created has run successfully. Make sure you have a similar result before continuing the tutorial.

Step 1.2.2: Test Packages

Similarly, let’s open the AppTest.java file in the Test Packages folder.

As we can see in the image above, this is a JUnit test class. Those of you familiar with JUnit will recognize that this test will always pass because the assertTrue( true ) statement simply asserts that true is true.

Let’s run the test to see if our understanding is correct. Right click on the project name in the Projects panel and this time select Test from the pop-up menu. Once the test completes, you should see the following results in your NetBeans IDE.

Notice the green bar in the Test Results panel indicating that all tests have passed. In addition, the results of the individual tests are listed below the bar (in our case there is only one test, AppTest and it has passed).

Of course, the tests are successful because they are not real tests yet. As we saw earlier, there is only one test method and it is set to always pass by assertTrue(true). We will modify the generated code and test modules later to show a more realistic, though still basic, example.

Step 1.2.3: Project Files

Let’s open the pom.xml file in the Project Files folder.

As we can see, the pom.xml file contains specific details about our project, including its properties and dependencies. The pom.xml file is required by the Maven build tool. For example, Maven will gather the dependencies we declare in the pom.xml file. In our case, the only dependency defined so far is JUnit 3.8.1. In the next part of this tutorial, we will add Cobertura as a dependency for our project, too. For now, however, we just want to make sure we are familiar with the generated pom.xml file that was created for us.

Part 2: Configure and Run Cobertura

Let’s get up and running with Cobertura before we make any changes to the generated application.

Step 2.1: Configure the Project POM File

Add the following lines just before the </project> closing tag in the pom.xml file to tell Maven to generate coverage reports when we run the application.

<build>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-site-plugin</artifactId>

<groupId>org.codehaus.mojo</groupId>

<artifactId>cobertura-maven-plugin</artifactId>

</formats>

</configuration>

</plugin>

</reportPlugins>

</configuration>

</plugin>

</plugins>

</build>

The pom.xml should appear as shown below.

Step 2.2: Generate the Report

Now that we have added the Cobertura plug-in as a reporting item in our pom.xml file, we need to run our tests again and generate the Cobertura reports.

Step 2.2.1 Add Maven’s Site as an Execute Goal in our Project Properties

There is a configuration step before we can generate our report using NetBeans: we must first add Site as an Action in our Project Properties.

Right click on the project name in the Projects panel and select Project Properties from the pop-up menu. In the Project Properties dialog box, click on the Actions category as shown below.

Click the Add Custom... button at the top right of the dialog box. You will be prompted to enter an action name. Enter Site as shown below.

Click OK to create the new Action.

Back in the Project Properties dialog box, make sure the Site action is selected and enter site:site in the Execute Goals list as shown below.

Click OK to save your changes to the Project Properties.

Step 2.2.2 Run the Site Action

Let’s execute our new Action to generate the Cobertura reports. Right click on the project name in the Projects panel again and select Custom from the pop-up menu. A sub-menu is displayed from which you should select Site, the new Action we configured in Step 2.2.1 above.

Maven will download any required plug-ins, build the project and generate the site as requested by our Action. You should see a BUILD SUCCESS message and a statement that the Cobertura report generation was successful as shown below.

Verify that the BUILD SUCCESS message is displayed before proceeding further in this tutorial.

Step 2.2.3 View the Generated Report

Click on the Files tab next to the Projects tab in the NetBeans top left panel to view the project files as shown below.

Expand the target folder and then the site folder within that. You should see a project-reports.html file in the site folder. Right click on the project-reports.html file and select View from the pop-up menu. This will launch the file in your browser. My default browser is Internet Explorer and the file appears as shown below on my computer.

Click on the Cobertura Test Coverage link to launch the test coverage report page as shown below.

As shown in the report, none of our code is being tested. Recall that this is as we expected since we have not modified the generated Java class and corresponding tests yet. While we are here, click on the package link in the Package column to view the test coverage for the classes in the selected package as shown below.

Now let’s click on the link for the only class in our application, the App class to view the test coverage at a line-by-line level as shown below.

As we can see above, our “hello world” application has one method called main and it is not tested by our test classes. The red highlights indicate the lines that are not tested in our application.

So far, we have created an application and generated the Cobertura code coverage reports for the application. In the following sections we will enhance the application and the tests and then run the Cobertura reports again to check our code coverage.

Part 3: Enhance our Application

We will now enhance our application to do more than say “Hello World”. We will enhance the application to return the discount rate for bulk purchases. The input will be the number of units to be sold and the value returned will be the discount rate based on the number of units.

Step 3.1: Enhance our App.java Class

Modify the main method in the App.java class to read as follows:

    public static void main( String[] args )
    {
        Scanner scanner = new Scanner(System.in);
        
        // Let's introduce ourselves to the user:
        System.out.println("Hi, I can calculate the discount "
                + "rate based on proposed units sold.");
        
        // Request user to input number of units to be sold
        System.out.println("Please enter the number of units"
                + " to be sold: ");
        Integer numberOfUnits = scanner.nextInt(); 

               

        /**

         * calculate the discount rate

         */ 

        try {

            Double result = new Discounter().

                    calculateBulkDiscount(numberOfUnits);

            // Display the result to the user

            System.out.println("The discount rate is: " + result);

        } 

        catch (IllegalArgumentException e) {

            System.out.println("Sorry, I don't understand"

                    + " your request.");

        }

    }

Once you have modified the main method in the App.java class, NetBeans will highlight errors as shown below.

Notice the errors at line 11 and 26 in the image above. Both lines have a icon showing a light bulb and a red dot. If you click on the icon, NetBeans will suggest possible fixes.

Click on the icon at line 11 and select Add import for java.util.Scanner from the list of possible fixes.

NetBeans will add an import statement at the top of the App.java file as shown in the image below.

Notice the import java.util.Scanner at line 3 in the image above. This was inserted by NetBeans at your request. In addition, notice that we now have only one error remaining, at line 28.

Step 3.2: Add the Discounter.java Class

Continuing from above, the error at line 28 is due to the fact that we have not yet coded the Discounter class that we are trying to instantiate. To create the class, click on the icon at line 28 and select Create class “Discounter” in package com.hani.coberturamaventutorial from the list of available fixes.

NetBeans will add new empty class as shown below.

Notice that we now have the Discounter class but we do not have the calculateBulkDiscount method that we referenced in the App.java class. Let’s add the calculateBulkDiscount method and modify the Discounter class to read as follows:

    class Discounter {
    
    private int numberOfUnits;
    private double discount;

    public Discounter() {
    }
    
    public double calculateBulkDiscount(Integer numberOfUnits) 
            throws IllegalArgumentException {
        

        this.numberOfUnits = numberOfUnits;

        

        if (this.numberOfUnits < 5) {

            discount = 0.00;

        } else if (this.numberOfUnits < 10) {

            discount = 0.05;

        } else if (this.numberOfUnits < 100) {

            discount = 0.10;

        } else {

            discount = 0.25;

        }

        

        return this.discount;

    }

}

In NetBeans, the Discounter.java class should be as shown below.

Make sure you save your changes.

Returning to the App.java class, we should see that all errors are now resolved as shown below.

We only have one minor change left. Let’s change the comment at the top of the file from “Hello world!” to “Discount calculator!” Done? Great, let’s continue.

We have now completed the enhancements to our application but our changes are not tested yet.

Part 4: Enhance & Run our Tests

In this part we will enhance the tests for our application to cover the new functionality.

Step 4.1: Add DiscounterTest.java Class

Right click on the Discounter.java file in the Projects panel and select Tools from the pop-up menu. In the Tools sub-menu list select Create JUnit Tests. NetBeans will launch the Create Tests dialog box shown below:

Accept all default values and click OK to create the JUnit tests for the Discounter.java class as shown below.

Step 4.2: Enhance the Tests in DiscounterTest.java

Modify the generated test class to test the various scenarios we want to handle. At a minimum, we should test that the correct discount rate is returned for sales of 0 units, 5 units, 10 units, 100 units.

Let’s start by adding the first test for 0 units sold to our DiscounterTest.java module. The test method is shown below.

   /**
     * Given 0 units to be sold
     * When calculateBulkDiscount
     * Then discount should be 0.0
     */
    public void testCalculateBulkDiscountForZeroUnits() {
        System.out.println("calculateBulkDiscountForZeroUnits");
        Integer numberOfUnits = 0;
        Discounter instance = new Discounter();
        double expResult = 0.0;
        double result = instance.

                calculateBulkDiscount(numberOfUnits);

        assertEquals(expResult, result, 0.0);

    }

We can also delete the generated test method called testCalculateBulkDiscount.

Once we complete the above changes, the DiscounterTest.java file should appear as follows.

Make sure to Save your changes.

Step 4.3: Run the New Test

Let’s run our test to verify our work so far. Right click on the project name in the Projects panel and select Test from the pop-up menu. We should now have two tests that pass as shown below.

Step 4.4: Run Cobertura

Let’s run using Cobertura again to see how our code coverage situation has evolved.

Step 4.4.1 Run Site

Right click on the project name in the Projects panel again and select Custom from the pop-up menu. A sub-menu is displayed from which you should select Site as we did when we ran our report earlier in this tutorial. The results of the Site Action are presented in the Output panel at the lower part of the NetBeans IDE as shown below.

Verify that the BUILD SUCCESS message is displayed before proceeding further.

Step 4.4.2 View the Generated Report

Once again, click on the Files tab next to the Projects tab in the NetBeans top left panel to view the project files as shown below.

Expand the target folder and then the site folder within that. Right click on the project-reports.html file and select View from the pop-up menu. This will launch the file in your browser as shown below.

Click on the Cobertura Test Coverage link to launch the test coverage report page as shown below.

As shown in the report, only some of our code is being tested. Recall that this is as we expected since we have not added all the test cases yet. Let’s click on the package link to view the test coverage for the classes in the package as shown below.

Notice that the App class has 0% line coverage while our new Discounter class has 54% line coverage. We can safely ignore the App class coverage since in reality we would not use a slick Web or Desktop GUI for getting input from the user.

However, our Discounter class clearly needs some attention. Let’s click on the Discounter class to view the test coverage at a line-by-line level as shown below.

Cobertura correctly shows us that we are only covering one of the four possible discount rates in our tests. The lines that are covered in our tests are those marked with a 1 next to the row number. The lines not covered by our tests are those with a 0 next to the line number. Cobertura highlights the untested lines in red for our attention.

Let’s return to our application and add the remaining test cases. We will then run the coverage report again and check that we have adequately tested the application.

Step 4.5: Enhance the Tests in DiscounterTest.java

Let’s add the remaining tests to verify that the correct discount rate is returned for sales of 5 units, 10 units, and 100 units.

    /**
     * Given 5 units to be sold
     * When calculateBulkDiscount
     * Then discount should be 0.05
     */
    public void testCalculateBulkDiscountForFiveUnits() {
        System.out.println("calculateBulkDiscountForFiveUnits");
        Integer numberOfUnits = 5;
        Discounter instance = new Discounter();

        double expResult = 0.05;

        double result = instance.

                calculateBulkDiscount(numberOfUnits);

        assertEquals(expResult, result, 0.0);

    }

    

    /**

     * Given 10 units to be sold

     * When calculateBulkDiscount

     * Then discount should be 0.10

     */

    public void testCalculateBulkDiscountForTenUnits() {

        System.out.println("calculateBulkDiscountForTenUnits");

        Integer numberOfUnits = 10;

        Discounter instance = new Discounter();

        double expResult = 0.10;

        double result = instance.

                calculateBulkDiscount(numberOfUnits);

        assertEquals(expResult, result, 0.0);

    }

    

    /**

     * Given 100 units to be sold

     * When calculateBulkDiscount

     * Then discount should be 0.25

     */

    public void testCalculateBulkDiscountFor100Units() {

        System.out.println("calculateBulkDiscountFor100Units");

        Integer numberOfUnits = 100;

        Discounter instance = new Discounter();

        double expResult = 0.25;

        double result = instance.

                calculateBulkDiscount(numberOfUnits);

        assertEquals(expResult, result, 0.0);

    }

In NetBeans, our DiscounterTest class should be as shown in the following images.

Scroll down.

Scroll down again.

Make sure you Save your changes.

Step 4.6: Run the Tests

Let’s run our tests to check our progress. Right click on the project name in the Projects panel and select Test from the pop-up menu.

Once the tests have run, you should see the following results.

Notice that our test results shown All 5 tests passed. The five tests of course are the four tests we added to the DiscounterTest class plus the generated test in the AppTest class.

Step 4.7: Run Cobertura

Let’s run using Cobertura again to see how our code coverage situation has evolved.

Step 4.7.1 Run Site

Once again, right click on the project name in the Projects panel and select Custom from the pop-up menu and Site from the sub-menu. The results of the Site Action are presented in the Output panel at the lower part of the NetBeans IDE as shown below.

Verify that the BUILD SUCCESS message is displayed before proceeding further.

Step 4.7.2 View the Generated Report

Click on the Files tab next to the Projects tab in the NetBeans top left panel to view the project files as shown below.

Click on the Cobertura Test Coverage link to launch the test coverage report page as shown below.

As shown in the report, only some of our code is being tested. The report is showing 100% branch coverage but only 44% line coverage. Let’s drill down to see what code is not being tested. Click on the package link to view the test coverage for the classes in the package as shown below.

Notice that the App class has 0% line coverage and as we discussed before, we ignore the results for this class since it will be replaced by a Web application or Desktop GUI in the final application. Notice, too, that our Discounter class now has 100% line coverage. Excellent!

Click on the Discounter class in the Classes in this package column to view the test coverage at a line-by-line level as shown below.

Cobertura shows us that our tests are exercising all lines of code in the Discounter class.

Congratulations! You have completed the tutorial and can now generate code coverage reports for Java applications using NetBeans, Maven and Cobertura.