Donovan Brown

In this post I am going to show you how to write your first Node.js based Visual Studio Team Services (VSTS) task.  The goal is the make sure the task is very easy to test. We are going to use Mocha, Istanbul and Sinon for our testing.  The task we are going to write will read a secret from Azure Key Vault so we can use it in our build or release in VSTS.  I will be writing this blog using instructions for a Windows user, however, you can use all the tools in this post on any platform.

There are a lot of tools we are going to have to install before we begin development of our task.  The list of task include:

• Visual Studio Code (optional)
• Node.js
• Node Package Manager (NPM)
• TFS Cross Platform Command Line Interface (tfx-cli)

We will begin by install the requirements. The first being Node.  At the time of this writing version 5.6.0 was the latest stable version.

1. Visit https://nodejs.org/en/
2. Download latest stable version
3. Start the installer
4. Click Next
5. Accept the license and click Next
6. Feel free to change the destination folder
7. Click Next
8. Only optional item is the Online documentation shortcuts
9. Click Next
10. Click Install
11. Click Finish

Now that we have Node.js and NPM installed we can install tfx-cli.

1. Open a command window
2. Install tfx-cli globally

   npm install -g tfx-cli

We are also going to install Mocha and Istanbul globally using the same command window.  Mocha is a JavaScript test framework for node.js. For more information view the documentation. Istanbul is a JavaScript code coverage tool.

1. Install mocha globally

   npm install -g mocha

2. Install istanbul globally

   npm install -g instanbul

3. Close the command prompt

You can use any text editor you like but for this post I will be using Visual Studio Code.

1. Visit VisualStudio.com
2. Download Visual Studio Code
3. Start the installer
4. Click Next
5. Feel free to change the destination folder
6. Click Next
7. Feel free to change the start menu folder
8. Click Next
9. Make sure Add to PATH is checked, all other options are optional
10. Click Next
11. Click Install
12. Click Finish

Now that we have all of our tools in place we can start creating our task.

1. Open a new command window
2. CD to the root folder
3. cd \
4. Create the task

   tfx build tasks create

   Field Name	Value
   Task Name	KeyVaultTask
   Friendly Task Name	Azure Key Vault
   Task Description	Reads a secret from Azure Key Vault and stores in variable
   Task Author	<Your Name> or <Your company Name>

5. CD into the KeyVaultTask folder

   cd KeyVaultTask

A VSTS task is made up of following:

• task definition
• image
• Node.js script
• PowerShell script

We are going to be writing our task entirely with Node.js so you can delete the PowerShell script.

del sample.ps1

I have a very particular structure that I use when creating a task.  I bootstrap the main code with a file called app.js and have the real code in task.js.  This will make testing the code much easier.  To start we are going to create the folder structure.

md src
md test

Now rename the sample.js to task.js and move into the src folder.

ren sample.js task.js
move task.js .\src

Now it is time to start editing our code so start Visual Studio code from the KeyVaultTask folder.

code .

Once Visual Studio Code opens it will show you all the files in the current folder.  We need to add the app.js file.

1. Select the src folder
2. Click the New File button in the folder toolbar

   

3. Type app.js
4. Press the Enter key
5. Copy and paste the following code into the file.

   /*
    * This is written as a self calling function so I don't have to place
    * 'use strict' in global scope.
    * This prevents problems when concatenating scripts that are not strict.
    */
   (function () {
       'use strict';
       
       /*
        * This file bootstraps the code that does the real work.  Using this technique
        * makes testing very easy.
        */
   
       // Contains the code for this task.  It is put in a separate module to make 
       // testing the code easier.
       var task = require('./task.js');
       
       // Call the task
       task.run();
   }());

If you look at the task.js file there is no function defined. This can make testing it a challenge.  We are going to update the file next to export a run function. The app.js just bootstraps the task and calls the run function.  Creating our task this way will allow us to call the task.run() function during our test very easy.

We need a package.json file to store our dependencies.  Using NPM we are going to create our package.json file.

Run the following command at the command prompt

npm init

Now that we have a package.json file we can start to add our project dependencies. The first we have to add is to the Visual Studio Team Services task library.

Install Visual Studio Team Service task library

npm install --save vso-task-lib

Before we will be able to run our test we need to install sinon and mocha as development dependencies to our project.

Install mocha as a development dependency

npm install --save-dev mocha

Install sinon as a development dependency

npm install --save-dev sinon

The task definition is defined in the task.json file.