Getting started with Node.js and Bamboo

Node.js is described as:

"a platform built on Chrome's JavaScript engine for easily building fast, scalable network applications. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient, perfect for data-intensive real-time applications that run across distributed devices." Node.js

We agree, and bundle a number of tasks with Bamboo to make it easy for you to get continuous integration and deployment for your Node.js projects. You can find the official Node.js documentation here.

Distributions

Node.js distributions usually come bundled with npm, a package manager for the platform, which runs from the command line and manages dependencies for your applications.

All npm packages contain a file, usually in the project root, called package.json - this file holds metadata relevant to the project. You can find out more about the package.json file here.

Configure your Node.js project

Add the following dependencies (or devDependencies) to the package.json file in your Node.js project. These are required if you want to use the Grunt 0.4.x, Gulp, Bower, Nodeunit or Mocha Test Runner tasks:

Your package.json file should look something like this:

...
"devDependencies": {
    ...
    "mocha": "~1.18",
    "mocha-bamboo-reporter": "*",
    ...
    "nodeunit" : "~0.8"
}
"dependencies": {
    ...
    "grunt": "~0.4",
    "grunt-cli": "~0.1",
    ...
    "gulp": "~3.3.2",
    ...
    "bower": "~1.3.12"
}

Install the necessary node_modules before executing any of the Node.js tasks, by adding an npm task and using the install command.

Node.js tasks

Bamboo ships with specific tasks for Node.js that make it easy to integrate the Node.js platform with Bamboo. You can use these tasks to set up builds for your Node.js project.

npm task

The npm task allows you to execute Node Package Manager commands in build plans and deployment projects. To run npm commands, simply enter the command to execute during task configuration:

In order to execute npm commands, the Node.js capability must be present on your build agent (see below).

Note: since Node.js and npm are distributed together, Bamboo will use the Node.js capability for npm tasks as well. The path will be modified at run time to point to the npm executable.

Node.js task

The Node.js task is a general purpose task that can be used to execute Node scripts within Bamboo.

To run the Node.js task, the Node.js capability must be present on your local or remote agents (see below).

Node.js can be used to execute any custom Node.js scripts or applications. To do so, enter the path of the script to execute in the task configuration, and optionally define additional arguments to pass.

Note that it is possible to execute scripts installed by the npm task from the node_modules, however we recommend that you use the dedicated tasks for executing such scripts, such as Grunt, Mocha or Nodeunit.

Mocha

Mocha is a test framework that runs on the Node.js platform.

You can use the Mocha Test Runner task to run your Mocha tests – it will create an output file named mocha.json.

You can configure the task to parse test results after a successful execution. Alternatively, you can add a Mocha Test Parser task to run afterwards to parse the test results.

If you don't do a full checkout on each build, make sure you add a task to delete mocha.json before the Mocha Test Runner task. A simple script task that runs rm -f mocha.json should do the trick.

Grunt

Use the Grunt task to take advantage of the Grunt task runner.

Nodeunit

Nodeunit is a tool for defining and running unit tests for Node.js projects.

Running the Nodeunit task will create test results in JUnit XML format.

You can configure the task to parse test results after a successful execution. Alternatively, you can add a following JUnit Parser task to parse the test results.

Node.js capability

Bamboo comes with a definition for a new executable capability called Node.js. In order to use the Node.js task (as well as most of the other Node.js tasks in Bamboo), you need this capability to be present on your local or remote agents.

The capability can be auto detected on the server side.

The  NODE_HOME  environment variable will instruct Bamboo where to look for Node.js if it is not installed in a typical directory - it should point to the location of the Node.js installation. Bamboo will search the agent's default directories to find the Node.js installation; it will also search in location specified by NODE_HOME.