When starting out with a fresh Java project one of the nuisances you have to deal with is setting up your build and test environment. It’s even more troublesome if you are trying to switch from Maven to Gradle for your builds. In this article I will provide you with a bootstrap Java project that is backed by Gradle, TestNG, Mockito, FEST-Assert 2 and Cobertura. It took me quite a while to wire everything together and fix issues such as hidden dependencies and early-bird Cobertura support, so I hope you find this information useful. The included example code illustrates how each of the previously mentioned packages is used. Lastly I will cover how the bootstrap project integrates with Eclipse and Jenkins.

Software used in the bootstrap project

• Gradle version 1.3 – build tool
• TestNG version 6.8 – unit testing framework
• Mockito version 1.9.0 – mocking framework
• FEST-Assert 2 version 2.0M8 – fluent interface for assertions that allows you to write assertions that read more like natural language (unfortunately Java lacks something like the awesome ScalaTest framework)
• Cobertura plugin for Gradle version 1.0 – allows Gradle to generate Cobertura compatible test reports (mostly used for integrating test results with Jenkins)

Packages only used for showcasing the functionality:

• Google Guava version 13 – solely used to show how compile-time dependencies are configured in Gradle

The latest dependency information is always available in build.gradle on GitHub.

What we want to do

We have two complimentary goals:

1. You should be able to use Eclipse as the IDE of choice to work with the code (e.g. run the build and tests locally on your machine).
2. You should be able to integrate the code with the Jenkins continuous integration server (e.g. to let it run the build and tests for your team and publish the test results).

The first goal covers your personal workflow as a software engineer with the code. The second goal covers integrating the code with the your engineering team as a whole.

How to use the bootstrap project

1. Download the bootstrap project as described below.
2. Configure Eclipse (optional).
3. Configure Jenkins CI server (optional).
4. Hack away!

You have the following two options to start your own project with the bootstrap project.

Option 1: You do not have a GitHub account – clone the bootstrap project

If you don’t have a GitHub account, the simplest way is to just clone (i.e. checkout) the original bootstrap project. The only requirement is a local installation of git on your machine.

$git clone git://github.com/miguno/gradle-testng-mockito-bootstrap.git  Now you can start hacking away! $ cd gradle-testng-mockito-bootstrap
# ...start coding...


Option 2: You do have a GitHub account – fork the bootstrap project

If you do have a GitHub account, I recommend that you fork the bootstrap project. Then start writing your own code against your personal fork.

First, open the bootstrap project on GitHub and fork it.

Then clone (i.e. checkout) your personal fork.

$git clone git@github.com:YOURUSERNAME/gradle-testng-mockito-bootstrap.git  Note: Make sure to replace YOURUSERNAME in the git URL above with the name of your GitHub user account. Now you can start hacking away! $ cd gradle-testng-mockito-bootstrap
# ...start coding...


About the actual Java code in the bootstrap project

The bootstrap project ships with only two classes:

• BobRoss.java – A simple class that implements a few features that we can write unit tests for. We pretend to be the late painting instructor Bob Ross who, well, is painting a picture with us.
• BobRossTest.java – This class tests the former class. It illustrates the use of TestNG, Mockito and FEST-Assert 2 to write these unit tests. Don’t pay too much attention to the semantics of the actual tests, we’re just showcasing here.

Using Gradle on the command line

Before continuing you must download and install Gradle if you haven’t done so already.

If you are on a Mac and have the Homebrew package manager installed, you just need to run:

$brew install gradle  Command Examples The bootstrap project is a normal gradle project. Have a look at the gradle documentation what this allows you to do. I will only list the most important commands here. If you want to see what gradle tasks are available out of the box in the bootstrap project, run gradle tasks. # General commands$ gradle clean          # deletes the build directory
$gradle clean test # runs the unit tests (and compile before if needed)$ gradle clean build    # assembles and tests this project

# Eclipse related
$gradle cleanEclipse # cleans all Eclipse files$ gradle eclipse        # generates all Eclipse files


By default, executing the commands above will create output in the following locations:

• build/ – this sub-directory is used by Gradle
• build/reports/cobertura/main/coverage.xml – Cobertura test coverage report in XML format
• build/reports/tests/testng-results.xml – TestNG Results in XML format
• bin/ – this sub-directory is used by Eclipse

Feel free to browse the directory tree to find additional files that you might need.

Configuring Eclipse

Importing the bootstrap project

The following steps will import your local clone of the bootstrap project into Eclipse.

Note: Yes, there is a Gradle plugin for Eclipse (don't confuse it with the Eclipse plugin for Gradle in build.gradle, imported via apply plugin: 'eclipse'). However in my personal experience it was not working that well, oftentimes reporting build errors when everything was actually fine. I found the approach described below much more stable and reliable. But your mileage may vary.

First, you must generate the required project files for Eclipse via gradle:

\$ gradle cleanEclipse eclipse


Then you import the bootstrap project into Eclipse as follows.

Open File > Import...:

Select General > Existing Projects into Workspace:

Navigate to your local copy of the bootstrap project. In the dialogue window you can leave the other values at their defaults and just click Finish. Of course feel free to modify the default values as you see fit (e.g. to add the project to a working set of your choice).

Now you should see the bootstrap project in the Package Explorer of Eclipse:

Installing the TestNG plugin for Eclipse

You will need the TestNG plugin for Eclipse so that you can conveniently run the included unit tests from within Eclipse.

To install the plugin open Help > Eclipse Marketplace... in Eclipse. Search for “gradle” and then install the “TestNG for Eclipse” plugin by Cédric Beust. Make sure to restart Eclipse after installing the plugin.

Installing the TestNG plugin for Eclipse. Note that the screenshot above actually shows an "Uninstall" button -- this is only because on my machine the plugin is already installed.

Now you can run the TestNG unit tests, for instance, by right-clicking on the BobRossTest class in the Package Explorer and selecting Run as... > TestNG Test.

If you give it a go, you should see the following results in the TestNG view in Eclipse. If you don’t find the TestNG view in your Eclipse, make sure it is enabled via Window > Show View > TestNG.

Results of a TestNG run in Eclipse as shown in the TestNG view

Configuring Jenkins

This section assumes that you are familiar with Jenkins and have a Jenkins instance installed and running.

Installing required Jenkins plugins

Install the following Jenkins plugins via Jenkins > Manage Jenkins > Manage Plugins:

Creating a new Jenkins build job

Now you can add a new Jenkins build job via Jenkins > New Job.

• Select “Build a free-style software project” and give your project a name. Click Ok.
• In section “Source Code Management” select Git and enter your repository URL.
• In section “Build” click on “Add build step” and select “Invoke Gradle script”.
• Enter clean build javadoc in the “Tasks” field.
• In section “Post-build Actions” click on “Add post-build action” and select “Publish Cobertura Coverage Report”.
• Enter **/build/reports/cobertura/main/coverage.xml in the “Cobertura xml report pattern” field.
• In section “Post-build Actions” click again on “Add post-build action” and select “Publish TestNG Reports”.
• Enter ./build/reports/tests/testng-results.xml in the “TestNG XML report pattern” field.
• Make sure you click on the Save button at the very bottom to actually save your new Jenkins build job!
Note: I will not cover how to integrate Jenkins with your git repository in this article. That said it is pretty straight-forward to configure Jenkins to use a self-hosted git repository or your GitHub repository -- such as the fork of the bootstrap project that you might have created above if you picked download option 2 (see the StackOverflow thread Authenticate Jenkins CI for Github private repository, for instance). This might a topic of a future blog post.

Now you can start using Jenkins to execute the build and run the tests of your bootstrap project!

Here are some screenshots how it will look like:

The bootstrap project configured in Jenkins.

The TestNG test report in Jenkins.

What else for Jenkins?

You can also configure Jenkins to fetch the latest contents of your GitHub code repository when you run a new build (or even trigger a build automatically when a new commit is pushed to the repository). I will not cover this setup in this article though.

Summary

This bootstrap project should get you started quickly with your own Java code project backed by Gradle, TestNG & Co. If you come up with any improvements, feel free to write a comment here or to send me a pull request on the bootstrap GitHub repository.

Interested in more? You can subscribe to this blog and follow me on Twitter.