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:
- 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).
- 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
- Download the bootstrap project as described below.
- Configure Eclipse (optional).
- Configure Jenkins CI server (optional).
- 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.
Now you can start hacking away!
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.
Now you can start hacking away!
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:
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,
1 2 3 4 5 6 7 8
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.
Importing the bootstrap project
The following steps will import your local clone of the bootstrap project into Eclipse.
First, you must generate the required project files for Eclipse via gradle:
Then you import the bootstrap project into Eclipse as follows.
File > Import...:
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.
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.
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:
- Cobertura plugin for Jenkins
- Gradle plugin for Jenkins
- TestNG plugin for Jenkins
- Git plugin for Jenkins
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
- In section “Source Code Management” select
Gitand enter your repository URL.
- In section “Build” click on “Add build step” and select “Invoke Gradle script”.
clean build javadocin the “Tasks” field.
- In section “Post-build Actions” click on “Add post-build action” and select “Publish Cobertura Coverage Report”.
**/build/reports/cobertura/main/coverage.xmlin the “Cobertura xml report pattern” field.
- In section “Post-build Actions” click again on “Add post-build action” and select “Publish TestNG Reports”.
./build/reports/tests/testng-results.xmlin the “TestNG XML report pattern” field.
- Make sure you click on the
Savebutton at the very bottom to actually save your new Jenkins build job!
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:
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.
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.