CommonJS

CommonJS is the style favored by Node.js. It’s also the style used in the JavaScript code shown in this chapter.

CommonJS uses a module.exports statement in each source file (i.e. module) containing an object — which could be a class, a function, a constant — that other modules need. Those other modules then have an require statement before they can use that dependent object. Although the require statement can be put anywhere before the first use of the dependency, it’s customary to put all require statements in a group at the top of the file.

Asynchronous Module Definition (AMD)

The AMD specification, as its name implies, facilitates the asynchronous loading of multiple modules. This means modules can be loaded separately (and many at a time, if possible) instead of sequentially (one after the other). This asynchronous loading is highly desireable when JavaScript code runs in a web browser, as it can noticeably improve the responsiveness of web pages and web sites. This is shown in Figure 6-2.

Figure 6-2. Asynchronous Module Definition allows modules to be loaded separately and concurrently (image from Wikipedia.org, courtesy Ле Лой)

AMD is not supported out-of-the-box by Node.js. A couple of popular implementations of AMD are RequireJS and Dojo Toolkit. RequireJS is available as a Node.js package, whereas Dojo Toolkit can be installed via Bower, which is yet another package management system (similar to Node.js).

From the previous paragraph, it may appear that grafting AMD on top of a Node.js app is a bit of work. That is because of a couple of fundamental decisions that the designers of Node.js and AMD have taken about the respective styles:

1. Server-side module management: optimized for correctness. Node.js, whose runtime is designed for building server-side apps outside the confines of a web browser ¹, strongly favors CommonJS style of defining module dependencies. CommonJS ensures deterministic loading of modules, which means that modules may wait on other modules to load. This is best illustrated by the way Node.js’s CommonJS implementation ensures that even cyclical dependencies — which are, in general, a bad choice — are resolved predictably. This waiting is less of a concern on the server, because there are other mechanisms to improve application performance (e.g statelessness and horizontal scaling).

2. Client-side module management: optimized for speed. The AMD style, which is optimized for use in browsers, is built around the idea of asynchronous loading — it’s right there in the name! Loading modules as fast as possible is vital in JavaScript code that runs in a web browser, because any latency due to slow loading is painfully obvious to the human user.

Because of the contrasting needs of running JavaScript on a server vs. running it inside a web browser, the two module definition styles — CommonJS and AMD — are optimized in different ways.

This book does not show the AMD style of module management because its JavaScript code is of a server-side flavor — it’s not intended to be run inside a web browser.

Universal Module Definition (UMD)

UMD is a design pattern and not an official specification. Think of a it as a societal convention (like shaking hands with the right hand) and not a law (like driving on the left side of the road in Ireland). The pattern consists of two parts: an immediately-invoked function expression (IIFE) and an anonymous function that creates a module. A robust implementation of this design pattern accounts for different libraries (such as AMD or CommonJS) and exports the function accordingly. Implementing AMD with such fallback features usually results in more lines of code. The code snippet below shows how to use UMD to export and import the Money class: ²

// ------------------------------------
// money.js (entire file)
// ------------------------------------
(function (root, factory) {
    if (typeof define === "function" && define.amd) {
        define("Money", [], factory);
    } else {
        root.Money = factory();
    }
}(this, function () {
    class Money {
        constructor(amount, currency) {
            this.amount = amount
            this.currency = currency
        }
        times(multiplier) {
            return new Money(this.amount * multiplier, this.currency)
        }
        divide(divisor) {
            return new Money(this.amount / divisor, this.currency)
        }
    };

    return Money;
}));

// ------------------------------------
// test_money.js (one example usage)
// ------------------------------------
const m = require('./money');
fiveDollars = new m.Money(5, "USD");

Because of the relative verbosity of the UMD pattern, this book eschews its use.

ESModules

As the name implies, ESModules is the standard promoted by ECMAScript. It is syntactically similar to CommonJS with a few differences. There is an export keyword, which can be used to export anything — e.g. a class, var, or function — from a module. Instead of require, an import statement allows a dependent module to import and use another module which it needs.

Node.js has supported ESModules for a few versions. Versions v14 and v16, referenced in this book, support it fully. To use ESModules instead of the default CommonJS, we need to do the following steps.

1. Either rename our source files to end in .mjs instead of .js or add a package.json file with { "type": "module" } in our source folder.

2. Declare and export modules using directives like export class Money.

3. Import modules using directives like import {Money} from './money.mjs';.

The code snippet below shows how to use ESModules in our code. This snippet shows the files as renamed to end with .mjs (which is simpler inasmuch as it does not require the creation of a package.json file).

// ------------------------------------
// portfolio.mjs (entire file)
// ------------------------------------
import {Money} from './money.mjs';

export class Portfolio {
    constructor() {
        this.moneys = [];
    }
    add() {
        this.moneys = this.moneys.concat(Array.prototype.slice.call(arguments));
    }

    evaluate(currency) {
        var total = this.moneys.reduce( (sum, money) => {
            return sum + money.amount;
          }, 0);
        return new Money(total, currency);
    }
}

// ------------------------------------
// test_money.mjs (example usage only)
// ------------------------------------
import * as assert from 'assert';
import {Money} from './money.mjs';
import {Portfolio} from './portfolio.mjs';

let fifteenDollars = new Money(15, "USD");
let portfolio = new Portfolio();
portfolio.add(fiveDollars, tenDollars);
assert.deepStrictEqual(portfolio.evaluate("USD"), fifteenDollars);

Notice that we have to declare variables with the let keyword in test_money.mjs, in strict compliance with ES6 rules, since the file is now an ES6 file (ending in .mjs).

Removing redundancy in tests

Let’s first delete the line of code that asserts multiplication in dollars, taking care to not delete the variables named fiveDollars and tenDollars which we need for our Portfolio test. Let’s move these variables closer to that Portfolio test. We now have three tests, segmented out by empty lines:

const assert = require('assert');
const Money = require('./money');
const Portfolio = require('./portfolio');

tenEuros = new Money(10, "EUR");
twentyEuros = new Money(20, "EUR");
assert.deepStrictEqual(tenEuros.times(2), twentyEuros);

originalMoney = new Money(4002, "KRW")
expectedMoneyAfterDivision = new Money(1000.5, "KRW")
assert.deepStrictEqual(originalMoney.divide(4), expectedMoneyAfterDivision)

fiveDollars = new Money(5, "USD");
tenDollars = new Money(10, "USD");
fifteenDollars = new Money(15, "USD");
portfolio = new Portfolio();
portfolio.add(fiveDollars, tenDollars);
assert.deepStrictEqual(portfolio.evaluate("USD"), fifteenDollars);

This is a good starting point for adding some structure.

Adding a test class and test methods

How should we make changes to our test code, using the principles of test-driven development?

We have one thing going for us: we have green tests right now. We can do refactoring and add new behavior using TDD as long as we run our tests frequently.

The current behavior of tests is that if we don’t get any output, it could indicate one of these scenarios:

• All tests ran successfully

OR

• One or more broken tests didn’t run.

That’s why item 3 in Table 6-1 is important.

Since silence ≠ success, we’ll adopt a TDD strategy tailored to our situation as shown in Table 6-2:

Notice that the three phases of RGR still occur and in the same order. The only difference is that, because our tests are currently silent when they pass, we will deliberately break them in the RED phase to ensure that we’re making progress.

We’ll repeat the steps listed in Table 6-2 until we accomplish all remaining items in Table 6-1.

Let’s add a class named MoneyTest in test_money.js. Let’s also move the three code blocks into three methods named testMultiplication, testDivision and testAddition respectively. Since we’re now using full ECMAScript semantics, we’ll need to declare all variables with the let keyword. Here’s how our newly minted class looks:

const assert = require('assert');
const Money = require('./money');
const Portfolio = require('./portfolio');

class MoneyTest {
  testMultiplication() {
    let tenEuros = new Money(10, "EUR");
    let twentyEuros = new Money(20, "EUR");
    assert.deepStrictEqual(tenEuros.times(2), twentyEuros);
  }
  testDivision() {
    let originalMoney = new Money(4002, "KRW")
    let expectedMoneyAfterDivision = new Money(1000.5, "KRW")
    assert.deepStrictEqual(originalMoney.divide(4), expectedMoneyAfterDivision)
  }

  testAddition() {
    let fiveDollars = new Money(5, "USD");
    let tenDollars = new Money(10, "USD");
    let fifteenDollars = new Money(15, "USD");
    let portfolio = new Portfolio();
    portfolio.add(fiveDollars, tenDollars);
    assert.deepStrictEqual(portfolio.evaluate("USD"), fifteenDollars);
  }
}

This runs so silently that we wonder if it’s running at all! Let’s follow the modified RGR cycle described in Table 6-2 and break one of the assertions deliberately. In testMultiplication, we change the 2 to 2000:

    assert.deepStrictEqual(tenEuros.times(2000), twentyEuros);

There is still no output. This proves that we’re not running any of the tests. Let’s add a runAllTests() methods to the class and call it outside the class:

class MoneyTest {
  testMultiplication() {
...
  }
  testDivision() {
...
  }

  testAddition() {
...
  }

  runAllTests() {
    this.testMultiplication();
    this.testDivision();
    this.testAddition();
  }
}

new MoneyTest().runAllTests();

Now we get the expected error from our deliberately broken test:

  code: 'ERR_ASSERTION',
  actual: Money { amount: 20000, currency: 'EUR' },
  expected: Money { amount: 20, currency: 'EUR' },

When we run our class now, the tests run. We’ve accomplished item 2 in Table 6-1.

Discovering and running tests automatically

We’d like to create a mechanism whereby we can automatically discover all the tests and then run them. This can be broken down into two parts:

1. Discover the names of all the test methods in our class (i.e. methods that start with test because that’s our naming convention);

2. Execute these methods one by one.

Let’s tackle the second part first. If we had the names of all our test methods in an array, we could use the Reflect object in standard library to execute them.

Let’s add a new method to MoneyTest that simply returns an array of strings, where each string is the name of one of our test methods.

  getAllTestMethods() {
    let testMethods = ['testMultiplication', 'testDivision', 'testAddition'];
    return testMethods;
  }

Yes, this is not “discovering the names of all the test methods” that we said in Part I! We’ll get to this shortly.

We can now call Reflect.get and Reflect.apply in runAllTests to call our test methods in succession:

  runAllTests() {
    let testMethods = this.getAllTestMethods(); 
    testMethods.forEach(m => {
      let method = Reflect.get(this, m); 
      Reflect.apply(method, this, []); 
    });
  }

Get names of all test methods

Get the method object for each test method name via reflection

Invoke the test method with no arguments on this object

We first call the getAllTestsMethods to get the test method names. For each name, we get the method object by calling Reflect.get. We invoke this method by calling Reflect.apply. The second parameter to Reflect.apply is the object on which the method is invoked, which is this instance of TestMoney. The last parameter to Reflect.apply is an array of any parameters required to invoke method — which, in our case, is always an empty array because none of our tests methods require any parameters.

When we run our tests now, they still run. Deliberately breaking the tests one by one — pursuant to the strategy described in Table 6-2 — yields the expected error messages.

Turning our attention to Part I: we’re executing our tests methods using reflection, but we’re not finding their names automatically. Let’s improve our getAllTestMethods method to discover all methods whose names start with test.

  getAllTestMethods() {
    let moneyPrototype = MoneyTest.prototype; 
    let allProps = Object.getOwnPropertyNames(moneyPrototype); 
    let testMethods = allProps.filter(p => {
      return typeof moneyPrototype[p] === 'function' && p.startsWith("test"); 
    });
    return testMethods;
  }

Get the prototype for this MoneyTest object

Get all the properties defined on the MoneyTest prototype (but not any inherited ones)

Retain only those functions whose names start with test, filtering out all the rest

We call the Object.getOwnPropertyNames to get all the properties defined for MoneyTest.prototype. Why the prototype and not simply MoneyTest? It is because JavaScript (as well as ES6) has Prototype-based Inheritance, not class-based inheritance as in many other languages. The methods declared within the MoneyTest class are in reality attached to the object reachable via the prototype property of MoneyTest.

Next, we iterate over all the properties of MoneyTest and select all (and only) those that are of type function and start with test. Because of our naming convention, these are our test methods. We return this array.

Running our tests validates that all of the are indeed still being executing. We verify by deliberately breaking each of them and observing the assertion failures show up. That’s the top three items in Table 6-1 accomplished.

Produce output when tests run successfully

Throughout this section, as we worked through the items described in Table 6-1, we had to deliberately break our tests to verify that they were still running as we made changes to test_money.js. This is the modified RGR cycle described in Table 6-2. It would be really nice if we got a brief output upon success, instead of the absolute silence we currently have when the tests are green. (There is a “Soylent Green” joke in there somewhere!)

Let’s add a simple output line to the runAllTests method that prints the name of each test before executing it:

    runAllTests() {
        let testMethods = this.getAllTestMethods();
        testMethods.forEach(m => {
            console.log("Running: %s()", m); 
            let method = Reflect.get(this, m);
            Reflect.apply(method, this, []);
        });
    }

Print the name of the method before invoking it

Now, when we run our tests, we get a short and meaningful message even when tests are green:

Running: testMultiplication()
Running: testDivision()
Running: testAddition()

Run all tests even when an earlier test assertion fails

As we were following the modified RGR cycle described in Table 6-2, we noticed that when we deliberately break a test that ran first (e.g. TestMultiplication), the subsequent tests don’t run at all. This can be misleading because the first failing test may not be the only failing test. When test-driving code, it’s vital to be aware of the broad impact of any change, not a myopic perspective that gets us fixated on the first problem that shows up.

We’d like our test class to run all the tests, even when one or more of them fail.

The reason the first assertion failure stops the test execution is because we’re not handling the AssertionError`s that are thrown. We could catch `AssertionError s and log them to the console. Let’s add a try ... catch block around the Reflect.apply call in our runAllTests method to do just that:

  runAllTests() {
    let testMethods = this.getAllTestMethods();
    testMethods.forEach(m => {
      console.log("Running: %s()", m);
      let method = Reflect.get(this, m);
      try { 
        Reflect.apply(method, this, []);
      } catch (e) {
        if (e instanceof assert.AssertionError) { 
          console.log(e);
        } else {
          throw e; 
        }
      }
    });
  }

Surround the method invocation in a try ... catch block

Log only AssertionError s

Rethrow all other errors

We catch all errors. However, we only output `AssertionError`s to the console; we rethrow the rest. (We do not want to inadvertently interfere with other errors, such as the `TypeError`s and `ReferenceError`s we’ve already seen.)

After this change, all our tests run every time we run MoneyTest. For example, when we deliberately break testMultiplication, the other tests — testDivision and testAddition — run successfully after the assertion error.

Running: testMultiplication()
AssertionError [ERR_ASSERTION]: Expected values to be strictly deep-equal:
+ actual - expected

  Money {
+   amount: 20,
-   amount: 2000,
    currency: 'EUR'
  }
...
Running: testDivision()
Running: testAddition()

Sweet! We’ve accomplished all the items in Table 6-1.