In this article by Alexandru Vlăduţu, author of Mastering Web Application Development with Express, we are going to see how to test Express applications and how to improve the code quality of our code by leveraging existing NPM modules.

(For more resources related to this topic, see here.)

Creating and testing an Express file-sharing application

Now, it's time to see how to develop and test an Express application with what we have learned previously.

We will create a file-sharing application that allows users to upload files and password-protect them if they choose to. After uploading the files to the server, we will create a unique ID for that file, store the metadata along with the content (as a separate JSON file), and redirect the user to the file's information page. When trying to access a password-protected file, an HTTP basic authentication pop up will appear, and the user will have to only enter the password (no username in this case).

The package.json file, so far, will contain the following code:

{
  "name": "file-uploading-service",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "start": "node ./bin/www"
  },
  "dependencies": {
    "express": "~4.2.0",
    "static-favicon": "~1.0.0",
    "morgan": "~1.0.0",
    "cookie-parser": "~1.0.1",
    "body-parser": "~1.0.0",
    "debug": "~0.7.4",
    "ejs": "~0.8.5",
    "connect-multiparty": "~1.0.5",
    "cuid": "~1.2.4",
    "bcrypt": "~0.7.8",
    "basic-auth-connect": "~1.0.0",
    "errto": "~0.2.1",
    "custom-err": "0.0.2",
    "lodash": "~2.4.1",
    "csurf": "~1.2.2",
    "cookie-session": "~1.0.2",
    "secure-filters": "~1.0.5",
    "supertest": "~0.13.0",
    "async": "~0.9.0"
  },
  "devDependencies": {
  }
}

When bootstrapping an Express application using the CLI, a /bin/www file will be automatically created for you. The following is the version we have adopted to extract the name of the application from the package.json file. This way, in case we decide to change it we won't have to alter our debugging code because it will automatically adapt to the new name, as shown in the following code:

#!/usr/bin/env node
var pkg = require('../package.json');
var debug = require('debug')(pkg.name + ':main');
var app = require('../app');

app.set('port', process.env.PORT || 3000);

var server = app.listen(app.get('port'), function() {
  debug('Express server listening on port ' + server.address().port);
});

The application configurations will be stored inside config.json:

{
  "filesDir": "files",
  "maxSize": 5
}

The properties listed in the preceding code refer to the files folder (where the files will be updated), which is relative to the root and the maximum allowed file size.

The main file of the application is named app.js and lives in the root. We need the connect-multiparty module to support file uploads, and the csurf and cookie-session modules for CSRF protection. The rest of the dependencies are standard and we have used them before. The full code for the app.js file is as follows:

var express = require('express');
var path = require('path');
var favicon = require('static-favicon');
var logger = require('morgan');
var cookieParser = require('cookie-parser');
var session = require('cookie-session');
var bodyParser = require('body-parser');
var multiparty = require('connect-multiparty');
var Err = require('custom-err');
var csrf = require('csurf');
var ejs = require('secure-filters').configure(require('ejs'));
var csrfHelper = require('./lib/middleware/csrf-helper');

var homeRouter = require('./routes/index');
var filesRouter = require('./routes/files');

var config = require('./config.json');
var app = express();
var ENV = app.get('env');

// view engine setup
app.engine('html', ejs.renderFile);
app.set('views', path.join(__dirname, 'views'));
app.set('view engine', 'html');

app.use(favicon());
app.use(bodyParser.json());
app.use(bodyParser.urlencoded());
// Limit uploads to X Mb
app.use(multiparty({
  maxFilesSize: 1024 * 1024 * config.maxSize
}));
app.use(cookieParser());
app.use(session({
  keys: ['rQo2#0s!qkE', 'Q.ZpeR49@9!szAe']
}));
app.use(csrf());
// add CSRF helper
app.use(csrfHelper);

app.use('/', homeRouter);
app.use('/files', filesRouter);

app.use(express.static(path.join(__dirname, 'public')));

/// catch 404 and forward to error handler
app.use(function(req, res, next) {
  next(Err('Not Found', { status: 404 }));
});

/// error handlers

// development error handler
// will print stacktrace
if (ENV === 'development') {
  app.use(function(err, req, res, next) {
    res.status(err.status || 500);
    res.render('error', {
      message: err.message,
      error: err
    });
  });
}

// production error handler
// no stacktraces leaked to user
app.use(function(err, req, res, next) {
  res.status(err.status || 500);
  res.render('error', {
    message: err.message,
    error: {}
  });
});

module.exports = app;

Instead of directly binding the application to a port, we are exporting it, which makes our lives easier when testing with supertest. We won't need to care about things such as the default port availability or specifying a different port environment variable when testing.

To avoid having to create the whole input when including the CSRF token, we have created a helper for that inside lib/middleware/csrf-helper.js:

module.exports = function(req, res, next) {
  res.locals.csrf = function() {
    return "<input type='hidden' name='_csrf' value='" + req.csrfToken() + "' />";
  }

  next();
};

For the password–protection functionality, we will use the bcrypt module and create a separate file inside lib/hash.js for the hash generation and password–compare functionality:

var bcrypt = require('bcrypt');
var errTo = require('errto');

var Hash = {};

Hash.generate = function(password, cb) {
  bcrypt.genSalt(10, errTo(cb, function(salt) {
    bcrypt.hash(password, salt, errTo(cb, function(hash) {
      cb(null, hash);
    }));
  }));
};

Hash.compare = function(password, hash, cb) {
  bcrypt.compare(password, hash, cb);
};

module.exports = Hash;

The biggest file of our application will be the file model, because that's where most of the functionality will reside. We will use the cuid() module to create unique IDs for files, and the native fs module to interact with the filesystem.

The following code snippet contains the most important methods for models/file.js:

function File(options, id) {
  this.id = id || cuid();
  this.meta = _.pick(options, ['name', 'type', 'size', 'hash', 'uploadedAt']);
  this.meta.uploadedAt = this.meta.uploadedAt || new Date();
};

File.prototype.save = function(path, password, cb) {
  var _this = this;

  this.move(path, errTo(cb, function() {
    if (!password) { return _this.saveMeta(cb); }

    hash.generate(password, errTo(cb, function(hashedPassword) {
      _this.meta.hash = hashedPassword;

      _this.saveMeta(cb);
    }));
  }));
};

File.prototype.move = function(path, cb) {
  fs.rename(path, this.path, cb);
};

For the full source code of the file, browse the code bundle. Next, we will create the routes for the file (routes/files.js), which will export an Express router. As mentioned before, the authentication mechanism for password-protected files will be the basic HTTP one, so we will need the basic-auth-connect module. At the beginning of the file, we will include the dependencies and create the router:

var express = require('express');
var basicAuth = require('basic-auth-connect');
var errTo = require('errto');
var pkg = require('../package.json');
var File = require('../models/file');
var debug = require('debug')(pkg.name + ':filesRoute');

var router = express.Router();

We will have to create two routes that will include the id parameter in the URL, one for displaying the file information and another one for downloading the file. In both of these cases, we will need to check if the file exists and require user authentication in case it's password-protected. This is an ideal use case for the router.param() function because these actions will be performed each time there is an id parameter in the URL. The code is as follows:

router.param('id', function(req, res, next, id) {
  File.find(id, errTo(next, function(file) {
    debug('file', file);

    // populate req.file, will need it later
    req.file = file;

    if (file.isPasswordProtected()) {
      // Password
–
protected file, check for password using HTTP basic auth
      basicAuth(function(user, pwd, fn) {
        if (!pwd) { return fn(); }

        // ignore user
        file.authenticate(pwd, errTo(next, function(match) {
          if (match) {
            return fn(null, file.id);
          }

          fn();
        }));
      })(req, res, next);
    } else {
      // Not password
–
protected, proceed normally
      next();
    }
  }));
});

The rest of the routes are fairly straightforward, using response.download() to send the file to the client, or using response.redirect() after uploading the file:

router.get('/', function(req, res, next) {
  res.render('files/new', { title: 'Upload file' });
});

router.get('/:id.html', function(req, res, next) {
  res.render('files/show', {
    id: req.params.id,
    meta: req.file.meta,
    isPasswordProtected: req.file.isPasswordProtected(),
    hash: hash,
    title: 'Download file ' + req.file.meta.name
  });
});

router.get('/download/:id', function(req, res, next) {
  res.download(req.file.path, req.file.meta.name);
});

router.post('/', function(req, res, next) {
  var tempFile = req.files.file;
  if (!tempFile.size) { return res.redirect('/files'); }

  var file = new File(tempFile);

  file.save(tempFile.path, req.body.password, errTo(next, function() {
    res.redirect('/files/' + file.id + '.html');
  }));
});

module.exports = router;

The view for uploading a file contains a multipart form with a CSRF token inside (views/files/new.html):

<%- include ../layout/header.html %>

<form action="/files" method="POST" enctype="multipart/form-data">
  <div class="form-group">
    <label>Choose file:</label>
    <input type="file" name="file" />
  </div>

  <div class="form-group">
    <label>Password protect (leave blank otherwise):</label>
    <input type="password" name="password" />
  </div>

  <div class="form-group">
    <%- csrf() %>
    <input type="submit" />
  </div>
</form>

<%- include ../layout/footer.html %>

To display the file's details, we will create another view (views/files/show.html). Besides showing the basic file information, we will display a special message in case the file is password-protected, so that the client is notified that a password should also be shared along with the link:

<%- include ../layout/header.html %>

<p>
  <table>
    <tr>
      <th>Name</th>
      <td><%= meta.name %></td>
    </tr>
      <th>Type</th>
      <td><%= meta.type %></td>
    </tr>
      <th>Size</th>
      <td><%= meta.size %> bytes</td>
    </tr>
      <th>Uploaded at</th>
      <td><%= meta.uploadedAt %></td>
    </tr>
  </table>
</p>

<p>
  <a href="/files/download/<%- id %>">Download file</a> | 
  <a href="/files">Upload new file</a>
</p>

<p>
  To share this file with your friends use the <a href="/files/<%- id %>">current link</a>.
  <% if (isPasswordProtected) { %>
  <br />
  Don't forget to tell them the file password as well!
  <% } %>
</p>

<%- include ../layout/footer.html %>

Running the application

To run the application, we need to install the dependencies and run the start script:

$ npm i


$ npm start

The default port for the application is 3000, so if we visit http://localhost:3000/files, we should see the following page:

After uploading the file, we should be redirected to the file's page, where its details will be displayed:

Unit tests

Unit testing allows us to test individual parts of our code in isolation and verify their correctness. By making our tests focused on these small components, we decrease the complexity of the setup, and most likely, our tests should execute faster.

Using the following command, we'll install a few modules to help us in our quest:

$ npm i mocha should sinon––save-dev

We are going to write unit tests for our file model, but there's nothing stopping us from doing the same thing for our routes or other files from /lib.

The dependencies will be listed at the top of the file (test/unit/file-model.js):

var should = require('should');
var path = require('path');
var config = require('../../config.json');
var sinon = require('sinon');

We will also need to require the native fs module and the hash module, because these modules will be stubbed later on. Apart from these, we will create an empty callback function and reuse it, as shown in the following code:

// will be stubbing methods on these modules later on
var fs = require('fs');
var hash = require('../../lib/hash');

var noop = function() {};

The tests for the instance methods will be created first:

describe('models', function() {
  describe('File', function() {
    var File = require('../../models/file');

    it('should have default properties', function() {
      var file = new File();

      file.id.should.be.a.String;
      file.meta.uploadedAt.should.be.a.Date;
    });

    it('should return the path based on the root and the file id', function() {
      var file = new File({}, '1');
      file.path.should.eql(File.dir + '/1');
    });

    it('should move a file', function() {
      var stub = sinon.stub(fs, 'rename');

      var file = new File({}, '1');
      file.move('/from/path', noop);

      stub.calledOnce.should.be.true;
      stub.calledWith('/from/path', File.dir + '/1', noop).should.be.true;

      stub.restore();
    });

    it('should save the metadata', function() {
      var stub = sinon.stub(fs, 'writeFile');
      var file = new File({}, '1');
      file.meta = { a: 1, b: 2 };

      file.saveMeta(noop);

      stub.calledOnce.should.be.true;
      stub.calledWith(File.dir + '/1.json', JSON.stringify(file.meta), noop).should.be.true;

      stub.restore();
    });

    it('should check if file is password protected', function() {
      var file = new File({}, '1');

      file.meta.hash = 'y';
      file.isPasswordProtected().should.be.true;

      file.meta.hash = null;
      file.isPasswordProtected().should.be.false;
    });

    it('should allow access if matched file password', function() {
      var stub = sinon.stub(hash, 'compare');

      var file = new File({}, '1');
      file.meta.hash = 'hashedPwd';
      file.authenticate('password', noop);

      stub.calledOnce.should.be.true;
      stub.calledWith('password', 'hashedPwd', noop).should.be.true;

      stub.restore();
    });

We are stubbing the functionalities of the fs and hash modules because we want to test our code in isolation. Once we are done with the tests, we restore the original functionality of the methods.

Now that we're done testing the instance methods, we will go on to test the static ones (assigned directly onto the File object):

    describe('.dir', function() {
      it('should return the root of the files folder', function() {
        path.resolve(__dirname + '/../../' + config.filesDir).should.eql(File.dir);
      });
    });

    describe('.exists', function() {
      var stub;

      beforeEach(function() {
        stub = sinon.stub(fs, 'exists');
      });

      afterEach(function() {
        stub.restore();
      });

      it('should callback with an error when the file does not exist', function(done) {
        File.exists('unknown', function(err) {
          err.should.be.an.instanceOf(Error).and.have.property('status', 404);
          done();
        });

        // call the function passed as argument[1] with the parameter `false`
        stub.callArgWith(1, false);
      });

      it('should callback with no arguments when the file exists', function(done) {
        File.exists('existing-file', function(err) {
          (typeof err === 'undefined').should.be.true;
          done();
        });

        // call the function passed as argument[1] with the parameter `true`
        stub.callArgWith(1, true);
      });
    });

  });
});

To stub asynchronous functions and execute their callback, we use the stub.callArgWith() function provided by sinon, which executes the callback provided by the argument with the index <<number>> of the stub with the subsequent arguments. For more information, check out the official documentation at http://sinonjs.org/docs/#stubs.

When running tests, Node developers expect the npm test command to be the command that triggers the test suite, so we need to add that script to our package.json file. However, since we are going to have different tests to be run, it would be even better to add a unit-tests script and make npm test run that for now. The scripts property should look like the following code:

  "scripts": {
    "start": "node ./bin/www",
    "unit-tests": "mocha --reporter=spec test/unit",
    "test": "npm run unit-tests"
  },

Now, if we run the tests, we should see the following output in the terminal:

Functional tests

So far, we have tested each method to check whether it works fine on its own, but now, it's time to check whether our application works according to the specifications when wiring all the things together.

Besides the existing modules, we will need to install and use the following ones:

• supertest: This is used to test the routes in an expressive manner
• cheerio: This is used to extract the CSRF token out of the form and pass it along when uploading the file
• rimraf: This is used to clean up our files folder once we're done with the testing

We will create a new file called test/functional/files-routes.js for the functional tests. As usual, we will list our dependencies first:

var fs = require('fs');
var request = require('supertest');
var should = require('should');
var async = require('async');
var cheerio = require('cheerio');
var rimraf = require('rimraf');
var app = require('../../app');

There will be a couple of scenarios to test when uploading a file, such as:

function uploadFile(agent, password, done) {
  agent
    .get('/files')
    .expect(200)
    .end(function(err, res) {
      (err == null).should.be.true;

      var $ = cheerio.load(res.text);
      var csrfToken = $('form input[name=_csrf]').val();

      csrfToken.should.not.be.empty;

      var req = agent
        .post('/files')
        .field('_csrf', csrfToken)
        .attach('file', __filename);

      if (password) {
        req = req.field('password', password);
      }

      req
        .expect(302)
        .expect('Location', /files/(.*).html/)
        .end(function(err, res) {
          (err == null).should.be.true;

          var fileUid = res.headers['location'].match(/files/(.*).html/)[1];

          done(null, fileUid);
        });
    });
}

describe('Files-Routes', function(done) {
  after(function() {
    var filesDir = __dirname + '/../../files';
    rimraf.sync(filesDir);
    fs.mkdirSync(filesDir);

  describe("Uploading a file", function() {
    it("should upload a file without password protecting it", function(done) {
      var agent = request.agent(app);

      uploadFile(agent, null, done);
    });

    it("should upload a file and password protect it", function(done) {
      var agent = request.agent(app);
      var pwd = 'sample-password';

      uploadFile(agent, pwd, function(err, filename) {
        async.parallel([
          function getWithoutPwd(next) {
            agent
              .get('/files/' + filename + '.html')
              .expect(401)
              .end(function(err, res) {
                (err == null).should.be.true;
                next();
              });
          },
          function getWithPwd(next) {
            agent
              .get('/files/' + filename + '.html')
              .set('Authorization', 'Basic ' + new Buffer(':' + pwd).toString('base64'))
              .expect(200)
              .end(function(err, res) {
                (err == null).should.be.true;
                next();
              });
          }
        ], function(err) {
          (err == null).should.be.true;
          done();
        });
      });
    });
  });
});

  "scripts": {
    "start": "node ./bin/www",
    "unit-tests": "mocha --reporter=spec test/unit",
    "functional-tests": "mocha --reporter=spec --timeout=10000 --slow=2000 test/functional",
    "test": "npm run unit-tests && npm run functional-tests"
  }

$ npm i pre-commit ––save-dev