Writing my first Node.js based VSTS Task

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

    image

  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

Field Name

Value

name keyvaulttask (must be all lower case)
version 1.0.0
description Retrieves value from Azure Key Vault
entry point ./src/app.js
test command istanbul cover node_modules\\mocha\\bin\\_mocha -- -R list
git repository  
keywords Azure Key Vault
author  
license MIT

 

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.

Comments (2) -

  • Hi Donovan,

    Nice post - very helpful for newbies with node.js for VSTS tasks.  Couple of clarifications.  My impression on the purpose of the json package is to include parameters that the task.js needs at runtime - do you agree?  I was also looking for an example.  I see that you did not include the code for task.js.

    Thanks,
    Vince

Add comment

Loading