How to automate your Node tests with Jenkins and GitHub

We all hate bugs in our code. Bugs can make you lose users and ultimately decrease your revenue.

That is why you have tests, to keep your Node & Express application bug free.

Initially, you run them only manually, but with time, as your app and team grow you realize that it is not enough.

It is easy to forget to run them, especially when making small quick changes.

Sometimes all your tests pass successfully but once the code is merged in the master branch they pass no more and you only learn about it later, and sometimes not until your code is in production.

The more people you have wokring on the same project the more these problems affect your codebase, your product and your users.

This is all stuff which begs for automation.

Wouldn’t it be nice if

• Each time new commits are pushed in GitHub that all tests run
• Each time a pull request is merged in GitHub that all tests are run
• Your branches are marked when tests pass successfully
• You can see on the Pull Request page when the tests passed successfully
• There are no more unexpected crashes after merging
• There are less bugs and more happy users

Not only that but you will be much more confident in the code that you produce and ship.

How it will work

To make all of this work the central piece of the process will be Jenkins.

It is an open source continious integration server battle tested by companeis of all sizes for all kinds of automations.

We are going to work with a repository in GitHub to which you need to have admin access.

Each time you push something to GitHub or merge a pull request, GitHub will invoke a hook, which will make a request to a url in Jenkins.

Then Jenkins will pull the contents of the repository and run the tests.

Finally, it will use the GitHub API to post back the result as a status on the tested branch.

What you will need

To apply this process you will need a repository in GitHub and a server where you can install Jenkins, and of course some tests.

This same process can work with many other service like Bitbucket for example, or even with a standard Git repository with a combination of commit hooks.

The Project

Let’s have a look at how your project might look like.

app.js
package.json
conrtollers/
  comments.js
models/
  comment.js
  user.js
tests/
  controllers/
    comments.js
  models/
    comment.js
    model.js

This is how your project might look like. The actual contents of the files are not interesting, except that we would use mocha to write and run all tests.

To run the tests from your terminal, you would have to do the following

$ ./node_modules/.bin/mocha tests/**

The standard way for automation systems like Jenkins is receive your test results in the junit XML format. Fortunately, it is easy to have that. You need just one additional module.

$ npm install mocha-junit-reporter --save-dev

When using this module mocha can produce an XML file which can then be handed to Jenkins.

Installing Jenkins

Log on over SSH to the server where you are going to install Jenkis.

First, you will have to install the latest version of OpenJDK. You can find the instructions for your server here http://openjdk.java.net/install/.

Once installed, all you have to do is download and run the Jenkins jar file.

$ wget http://mirrors.jenkins-ci.org/war/latest/jenkins.war

Then to run Jenkins do all you have to do is

$ java -Djava.awt.headless=true -jar /usr/local/jenkins/jenkins.war --httpListenAddress=127.0.0.1 --httpPort=8080

This will make Jenkins available at 127.0.0.1:8080.

Configuring Jenkins

You can have nice urls by either replacing 127.0.0.1 above with something better or by using a reverse proxy like nginx or varnish.

In either way once your Jenkins server is up and running, load the Jenkins url in your browser and then go to

Jenkins | Manage Jenkins | Configure System

and look for the Jenkins Location field. Be sure that it contains the right url. This is critical or you might have problems with the hooks from GitHub later.

It is also advisable that you configure user access and security by going to

Jenkins | Manage Jenkins | Configure Global Security

Installing Plugins

The real power of Jenkins comes with its plugins. It comes pre installed with some of them. What’s more, installing plugins is really easy. Go to

Jenkins | Manage Jenkins | Manage Plugins

Then install any missing plugins from the following list

• Credentials Plugin
• Git Plugin
• GitHub Plugin
• JUnit Plugin
• Mailer Plugin
• Matrix Authorization Strategy Plugin
• Plain Credentials Plugin
• SSH Credentials Plugin
• SSH Slaves plugin
• Windows Slaves Plugin

You might not need all of them immediately but they are all very useful.

Prepare GitHub

Now that Jenkins is up and running, it is time to prepare GitHub for testing your repository.

Essentially there are two things. First, you need an application token from GitHub which will be used by Jenkins to post back the results.

You aslo need to setup the hook in the repository which will be called by GitHub to notify Jenkins for any changes like a new commit or a merged pull request.

Application Token

Click on your user icon and then choose settings to go to your personal GitHub settings.

There select the section Personal access tokens. Once inside select Generate new token.

Choose admin:repo_hook, repo and repo:status. These are the rights available to Jenkins when it uses the access token.

Then create and copy the token. It will be never again shown to you.

For this token to work, you must have admin rights to the repository.

Setup a hook to Jenkins

Go the repository, then go to its settings and select Webhooks & services.

In the Services section click Add service and look for Jenkins GitHub plugin. This service works with the plugin that you installed earlier.

Then in the field Jenkins hook url put https://url/to/your/jenkins/server/github-webhook/ The part github-webhook at the end is mantadory.

If your Jenkins server is behind basic authentication you can prepend username:password@ to the url before https and it will work.

GitHub is ready.

Configuring Jenkins for working with GitHub

We have configured GitHub to communicate with Jenkins and now let’s to the same the other way around.

Storing the application token

Go to

Jenkins | Manage Jenkins | Manage Credentials 

Choose at the bottom Add Credentials | Secret text and put the token that you obtained from GitHub in the Secret field.

Storing your credentials to GitHub

Choose again Add Credendials | Username & Password and put your GitHub username and password. For increased security you can create a dummy GitHub account.

You need this account to be able to pull your code from GitHub, if you are using a private repository.

Configure communiction with GitHub

Go to

Jenkins | Manage Jenkins | Configure System

Look for the section GitHub Plugin Configuration and add a GitHub Server Config.

Then uncheck Manage hooks, because you already added a better hook, and as credentials choose the token that you just added.

Setup a Job in Jenkins

You are almost ready. This is the last part before you can run the tests automatically.

Create a new job

Jenkins | New Item | Freestyle project

Then put https://github.com/path/to/repository/ in the GitHub project field.

Next, in the Source Code Management section select Git and then put in the Repository URL the path to your repository again, the same as above.

Then select from Credentials the GitHub account credentials.

Afterwards, from Build Triggers select Build when a change is pushed to GitHub.

In the Build section add Execute shell and in the new text area paste the following

npm install
MOCHA_FILE=./jenkins-test-results.xml ./node_modules/.bin/mocha tests/** --reporter mocha-junit-reporter

Then in the Post-build actions below add Publish JUnit test result report and select Set build status on GitHub commit.

Lastly, put in the Test report XMLs field jenkins-test-results.xml.

You are ready. All it is left is to push a commit to an existing branch in your GitHub repository, and all your test will run automatically for this branch.

Actually the first time you push something it will trigger testing for all branches. Afterwards, only the branch you pushed to will trigger the automatic tests.

On the branches page all your branches will be marked with either a green or a red mark showing whether the tests passed successfully. In addition, on the page of each Pull Request you will be able to see what was the result of the tests.

What’s more, on each of this pages, when you click on the mark you will be redirected to Jenkins to see more details.

Next

You can apply what you have just learned immediately. The bigger your team is the more you will gain. You will have more confidence in your code the next time you put it in production.