Introduction to the Node.js reference architecture: Testing

Welcome back to the Node.js reference architecture series. In this article, we’ll take a look at testing in the Node.js landscape and discuss the guidelines recommended by the Node.js reference architecture team.

Follow the series:

• Part 1: Overview of the Node.js reference architecture
• Part 2: Logging in Node.js
• Part 3: Code consistency in Node.js
• Part 4: GraphQL in Node.js
• Part 5: Building good containers
• Part 6: Choosing web frameworks
• Part 7: Code coverage
• Part 8: Typescript
• Part 9: Securing Node.js applications
• Part 10: Accessibility
• Part 11: Typical development workflows
• Part 12: npm development
• Part 13: Problem determination
• Part 14: Testing
• Part 15: Transaction handling
• Part 16: Load balancing, threading, and scaling
• Part 17: CI/CD best practices in Node.js
• Part 18: Wrapping up

2 testing tools

Testing is probably one of the most important parts of any software development practice. It is also one of the most “I’ll get to that later” parts. And let’s be honest, we never get to it later. One of the reasons that developers have an aversion to testing is trying to figure out what tools to use.

Like most tasks in software development, the answer to which is the best package to use for testing is, it depends. It depends on the type and scope of the project. Does a one-size-fits-all solution work or should you go with a solution that is a bit more granular? These are the types of questions that the team asked itself when coming up with recommendations. There are two test frameworks that the team has had success with.

• Jest is a popular testing framework from Meta. It excels at testing React and other component-based web applications, and can be used in other contexts. It is considered an opinionated framework because it provides its own set of assertions, spies/stubs/mocks, and other features (e.g., snapshot testing and code coverage) out of the box.
• Mocha is a widely used, mature (created in 2011), and stable project. While Node.js is the main area of focus and support, Mocha can also be used in a browser context. Mocha is an un-opinionated framework with a large ecosystem of plugins and extensions.

Note: The test framework recommendations are part of the OpenJS Foundation.

These frameworks have advantages, and in the next sections, we will take a look at why you might choose one over the other.

When Jest is the better tool

• When testing React or component-based applications.
• When using a compile-to-JavaScript language (like TypeScript).
• When snapshots are useful.

Snapshots provide an easy to use way of testing output of a function and saving the result as a snapshot artifact, which can then be used to compare against as a test. As an example:

test('unknown service', () => {

    expect(() => {

      bindings.getBinding('DOEST_NOT_EXIST');

    }).toThrowErrorMatchingSnapshot('unknown service');

  });

The first time the test runs, it will create and store a snapshot of the expected exception. On subsequent runs, if the exception does not match the snapshot, it will report a test failure. This makes generating and capturing the result from an operation testing fast and easy.

When Mocha is the better tool

• When you want a smaller dependency tree (91 packages versus 522).
• When Jest's opinions, environment proxies, and dependency upon babel are unfavorable for your use case.

As an example of potential problems with Jest's environment proxies, Jest replaces globals in the environment in a way that can cause failures with native add-ons. For example, this simple test fails:

const addon = require('bindings')('hello');



describe('test suite 1', () => {

  test('exception', () => {

    expect(addon.exception()).toThrow(TypeError);

  });

});

Even though the add-on is throwing the expected exception, as follows:

static napi_value ExceptionMethod(napi_env env, napi_callback_info info) {

   napi_throw_type_error(env, "code1", "type exception");

   return NULL;

}

The failure reports the exception as TypeError: type exception.

FAIL  __tests__/test.js

  ● test suite 1 › exception

    TypeError: type exception

      3 | describe('test suite 1', () => {

      4 |   test('exception', () => {

    > 5 |     expect(addon.exception()).toThrow(TypeError);

        |                  ^

      6 |   });

      7 | });

      8 |

      at Object.<anonymous> (__tests__/test.js:5:18)

An equivalent test runs successfully with Mocha. You can review the full source for the test on GitHub.

Recommended packages to use with Mocha

Because Mocha is un-opinionated, it does not ship with batteries included. While Mocha is usable without any other third-party library, many users find the following libraries and tools helpful.

Refer to the mocha documentation and examples repository for more information on integrating with other tools.

Assertion library

Most Mocha users will want to consume a third-party assertion library. Besides the Node.js built-in assert module, Mocha recommends choosing one of the following. Both have their own plugin ecosystems.

• chai: The most popular general-purpose assertion library, with traditional and natural language APIs available.
• unexpected: A string-based natural language API, Mocha uses Unexpected in its own tests.

Stubs, spies, and mocks

Many users will want a library providing stubs, spies, and mocks to aid isolation when writing unit tests. Both have their own plugin ecosystems.

• sinon: The most popular stub, spy and mock library, and it is mature.
• testdouble: This is a full-featured library with the ability to mock at the module level.

Code coverage

Mocha does not automatically compute code coverage. If you need it, use the following:

• nyc: The most popular code-coverage tool, and the successor CLI for Istanbul.

For more on code coverage, review the code coverage section of the Node.js reference architecture. Also, take a look at Part 7 of this article series on code coverage.

A new feature in Node core

A recent addition to Node core could also help in determining a developers testing strategy. A test runner is now available in Node core (v18 and v16). With the release of Node 20, it is now considered stable.

The following is a basic example of how this new test runner can be used:

const test = require('node:test');

test('asynchronous passing test', async (t) => {
  // This test passes because the Promise returned by the async
  // function is not rejected.
  assert.strictEqual(1, 1);
});

Since this is a new addition, the team doesn’t have guidance on this yet, but it is on our radar to reevaluate our current guidance.

A simpler method

Before wrapping up, there is one fun and helpful thing that I would like to offer. When running your tests in a CI environment, it is somewhat trivial to specify all the different node versions you would like to test against. This isn’t as easy during development time. Many developers use a Node Version Manager like nvm to switch between different versions of node rather than just their tests.

There is a slightly simpler way using the npx command (with the -p flag) and the node npm module which will allow you to run a npm script (or any node application) using a different version of node than what is installed locally. For example, to run your applications test suite with Node 18.12.1, the command might look like this:

npx -p node@18.12.1 -- npm run test

What’s next?

We cover new topics regularly as part of the Node.js reference architecture series. Next, read about transaction handling in Node.js.

We invite you to visit the Node.js reference architecture repository on GitHub, where you can view our work. To learn more about what Red Hat is up to on the Node.js front, check out our Node.js page.