DEV Community: Domagoj Štrekelj

How to test classes with Jest

Domagoj Štrekelj — Wed, 08 Sep 2021 18:58:18 +0000

📣 Notice
This article is part of a series:

Testing JavaScript with Jest

To get the most out of this article, I recommend reading the previous article in the series:

How to mock imported functions with Jest

Testing functions is usually straightforward - we have our input arguments and our return value and that's it. Sometimes there's a dependency or two we need to mock, but for the most part functions are easy to reason about.

Testing classes, on the other hand, can become complex fairly quickly. Methods calling each other internally, properties being modified, internal state being tracked and changed with every call. It's not enough to check if the tested method is called correctly. We need to ensure any other methods called internally behave correctly as well - as if they were an internal dependency.

Testing modules with dependencies (internal or external) is made easier with mocks or spies. Jest makes it possible to spy on object methods similarly to creating mock functions and we can leverage that to test our classes with ease.

This article will provide an example on how to test classes with Jest. We will learn how to use spies to observe the behaviour of class methods and how to combine spies across different methods to perform more in-depth tests.

We will assume that we're testing a Validator class that validates a value according to provided validation rule IDs:

// Validator.js
module.exports = class Validator {
  ruleMap = new Map();

  setRule(id, handler) {
    this.ruleMap.set(id, handler);
  }

  getRule(id) {
    return this.ruleMap.get(id);
  }

  validate(value, ruleIds) {
    const errors = [];

    for (const ruleId of ruleIds) {
      const ruleHandler = this.getRule(ruleId);

      if (!ruleHandler(value)) {
        errors.push(ruleId);
      }
    }

    return errors;
  }
};

We want to see what our tests will teach us about the flaws in our code by passing and failing test cases. Fixing the implementation is not covered by this article, but feel free to play with it as we move through the article.

Read on to find out more!

How to test classes with Jest?

To test classes with Jest we write assertions for static and instance methods and check if they match expectations.

The same process we use when testing functions applies to classes. The key difference is that classes with constructors need to be instantiated into objects before testing.

💡Note
We can use the before / after family of global Jest functions to instantiate objects before / after all tests run or each test runs. There is no specific rule on how to approach object creation, we choose what's best for the test we're performing.

A good first test for classes is to write assertions about their interface. We expect our Validator class to define a setRule() method. We'll test that expectation by writing an assertion to check if the setRule property of the Validator object is a function:

const Validator = require("./Validator");

describe("Validator", () => {
  const validator = new Validator();

  test("defines setRule()", () => {
    expect(typeof validator.setRule).toBe("function");
  });
});

💡Note
There are a couple of ways to match an expectation to be a function. The typeof way is the most generic, but also the least precise. To match with strict equality against a specific function we can use .toBe(). Another way to loosely match against any function is with .toEqual(expect.any(Function)).

We can also write an assertion about the setRule() return value which we expect to be undefined:

test("setRule() returns undefined when called", () => {
  expect(validator.setRule()).toBeUndefined();
});

We're off to a good start, but so far we've only tested the interface. To test the implementation - or how the class works on the inside - we need to use spies.

How to test method implementation using spies with Jest?

To test method implementation using spies with Jest we use the jest.spyOn() function.

jest.spyOn() is called with two required parameters - the object and the object method identifier we're spying on. The return value is a mock function (spy) with a reference to the specified object method. This allows us to call the object method and track the calls and returns value in the mock just like we would with a regular jest.fn() mock.

💡Note
Since Jest 22.1.0+ jest.spyOn() also accepts an optional third argument - an access type string value of either "get" or "set" - for spying on getters or setters specifically.

It's important to make sure we don't keep spies around longer than we need them. Spies keep track of state (function calls and their results) between tests. This state can affect our assertions and result in false positives or negatives. To clear the state we use the spy's mockClear() method.

💡Note
Keep in mind that depending on the use-case we might need to use the mockReset() method or mockRestore() method instead.

Using spies, we can now assert that the setRule() method is actually called with the arguments we provide:

test("setRule() is called with arguments", () => {
  // Prepare a spy for the validator.setRule() method.
  const setRuleSpy = jest.spyOn(validator, "setRule");

  // Create a mock rule for use as a function argument.
  const trueRule = jest.fn(() => true);

  const result = validator.setRule("true", trueRule);

  expect(result).toBeUndefined();

  // Check the spy if the method was called correctly.
  expect(setRuleSpy).toHaveBeenCalledWith("true", trueRule);

  // Restore the mock and revert original implementation.
  setRuleSpy.mockClear();
});

💡Note
In some cases we can use the before / after family of global Jest functions to clean up our mocks between tests.

How to test class implementation using spies with Jest?

To test class implementation using spies with Jest we use the jest.spyOn() function and spy on all methods in the class that take part in the core implementation.

Consider the validate() method of our Validator object. For validate() to work, the getRule() method must be called in order to get the rule handler function. Following that, the rule handler function must be called to validate the value. The validate() call then ends by returning an array of rule IDs for which the validated value failed validation.

With that in mind, we expect the following:

validate() to be called with a value and array of rule IDs;
getRule() to be called with the rule ID;
getRule() to return the rule handler registered under the rule ID;
the rule handler to be called with the value that is validated;
validate() to return an array of errors (array length depends on rule).

To test this implementation we will need spies for validate(), getRule(), and the rule handler function. We will also need to register a rule with our validator, but we can do that as part of a separate test:

// Declare mock rule outside of test to reuse it
const trueRule = jest.fn(() => true);

// Register the mock rule in the validator with a test
test("sets rule", () => {
  const setRuleSpy = jest.spyOn(validator, "setRule");
  const result = validator.setRule("true", trueRule);

  expect(setRuleSpy).toHaveBeenCalledWith("true", trueRule);
  expect(result).toBeUndefined();

  setRuleSpy.mockClear();
});

test("validates value", () => {
  const validateSpy = jest.spyOn(validator, "validate");
  const getRuleSpy = jest.spyOn(validator, "getRule");
  const result = validator.validate("foo", ["true"]);

  // Expect validate() to be called with arguments above.
  expect(validateSpy).toHaveBeenCalledWith("foo", ["true"]);

  // Expect getRule() to return the rule with ID "true"
  expect(getRuleSpy).toHaveBeenCalledWith("true");
  expect(getRuleSpy).toHaveReturnedWith(trueRule);

  // Expect rule handler to be called with validated value
  expect(trueRule).toHaveBeenCalledWith("value");
  expect(trueRule).toHaveReturnedWith(true);

  // Expect validation result to be empty array
  expect(result).toBeInstanceOf(Array);
  expect(result.length).toBe(0);

  validateSpy.mockClear();
  getRuleSpy.mockClear();
  trueRule.mockClear();
});

That's it! We can now test our classes in-depth by using spies to track method calls and their return values.

Jest test class methods example code

The module to be tested in Validator.js:

// Validator.js
module.exports = class Validator {
  ruleMap = new Map();

  setRule(id, handler) {
    this.ruleMap.set(id, handler);
  }

  getRule(id) {
    return this.ruleMap.get(id);
  }

  validate(value, ruleIds) {
    const errors = [];

    for (const ruleId of ruleIds) {
      const ruleHandler = this.getRule(ruleId);

      if (!ruleHandler(value)) {
        errors.push(ruleId);
      }
    }

    return errors;
  }
};

The unit test in Validator.spec.js:

// Validator.spec.js
const Validator = require("./Validator");

describe("Validator", () => {
  const validator = new Validator();
  const setRuleSpy = jest.spyOn(validator, "setRule");
  const getRuleSpy = jest.spyOn(validator, "getRule");
  const validateSpy = jest.spyOn(validator, "validate");

  const trueRule = jest.fn(() => true);

  describe(".setRule", () => {
    test("defines a function", () => {
      expect(typeof validator.setRule).toBe("function");
    });

    test("registers rule when called", () => {
      expect(validator.setRule("true", trueRule)).toBeUndefined();
      expect(setRuleSpy).toHaveBeenCalledWith("true", trueRule);

      setRuleSpy.mockClear();
    });
  });

  describe(".getRule", () => {
    test("defines a function", () => {
      expect(typeof validator.setRule).toBe("function");
    });

    test("returns registered rule", () => {
      expect(validator.getRule("true")).toBe(trueRule);
      expect(getRuleSpy).toHaveBeenCalledWith("true");

      getRuleSpy.mockClear();
    });
  });

  describe(".validate", () => {
    test("defines a function", () => {
      expect(typeof validator.setRule).toBe("function");
    });

    test("validates value without errors", () => {
      const result = validator.validate("value", ["true"]);

      expect(validateSpy).toHaveBeenCalledWith("value", ["true"]);
      expect(getRuleSpy).toHaveBeenCalledWith("true");
      expect(getRuleSpy).toHaveReturnedWith(trueRule);
      expect(trueRule).toHaveBeenCalledWith("value");
      expect(trueRule).toHaveReturnedWith(true);
      expect(result).toBeInstanceOf(Array);
      expect(result.length).toBe(0);

      validateSpy.mockClear();
      getRuleSpy.mockClear();
      trueRule.mockClear();
    });
  });
});

Homework and next steps

Write more comprehensive tests and use fixtures to cover any additional cases.
Fix the code so any failed tests pass or write a newer, better implementation.
Achieve 100% code coverage in the coverage report.

Thank you for taking the time to read through this article!

Have you tried mocking classes with Jest before? What was your experience like?

Leave a comment and start a discussion!

How to mock imported functions with Jest

Domagoj Štrekelj — Tue, 03 Aug 2021 18:42:41 +0000

📣 Notice
This article is part of a series:

Testing JavaScript with Jest

To get the most out of this article, I recommend reading the previous article in the series:

How to write unit tests in JavaScript with Jest

Writing unit tests for code with dependencies can be difficult. This is especially true for large code bases where it's tricky to come up with fixtures that will cover all the cases we need to test.

But what if we could control the return value of a function dependency, no matter what arguments it is called with?

This is where mock functions come in.

Mock functions are a testing tool that allows us to track how function dependencies are called and control their return values. This makes it possible for us to manipulate the control flow of the tested program and reach even those difficult-to-reproduce edge-cases when writing tests.

This article will provide an introduction into the concepts behind mocking and how it relates to unit testing. We will learn how to mock functions and imported function modules with Jest, and write tests that rely on those mocks to increase the coverage of our test cases.

We will assume that we're testing a couple of validation rules:

// isInteger.js
module.exports = (value) => Number.isSafeInteger(value);

// isAtLeast18.js
const isInteger = require("./isInteger");

module.exports = (value) => isInteger(value) && value >= 18;

Read on to find out more!

How to mock an imported function with Jest?

To mock an imported function with Jest we use the jest.mock() function.

jest.mock() is called with one required argument - the import path of the module we're mocking. It can also be called with an optional second argument - the factory function for the mock. If the factory function is not provided, Jest will automock the imported module.

💡Note
Jest automock is the automatic mocking of imported modules with surface-level replacement implementations. Automocking is disabled by default since Jest 15, but can be enabled by configuring Jest with the automock flag.

When testing isAtLeast18() we have to keep in mind that the isInteger() dependency affects the module's behaviour:

if isInteger() is false , isAtLeast18() is false;
if isInteger() is true , isAtLeast18() depends on the value argument.

We'll start by testing the case of isInteger() returning false.

The isInteger.js module has a single default export - the isInteger() function. We will mock the imported module with a factory function that behaves just like the default export and returns a function. That function, when called, will always return false.

// isAtLeast18.spec.js
const isAtLeast18 = require("./isAtLeast18");

// The mock factory returns the function () => false
jest.mock("./isInteger", () => () => false);

describe("isAtLeast18", () => {
    it("fails if value is not recognised as integer", () => {
        // Should pass, but fails because of the isInteger() mock
        expect(isAtLeast18(123)).toBe(false);
        // Should fail either way
        expect(isAtLeast18("abc")).toBe(false);
    });
});

💡Note
The import path of the mocked module must match the import path that is present in the module we're testing. The isAtLeast18.js module imports the isInteger.js module under the path "./isInteger". This is why our mock import path is also "./isInteger".

isAtLeast18() will now always return false no matter what we call it with, because the isInteger() mock is set to always return false.

But what about the case when isInteger() returns true?

To mock different return values depending on the test we will create a mock function.

💡Note
This unit test is a solitary unit test because the tested unit is isolated from its dependencies. Read more about solitary unit tests in the previous article: How to write unit tests in JavaScript with Jest.

What is a mock function?

A mock function is a function that replaces the actual implementation of a function with a "fake" (mock) implementation.

Mock functions track how they are called by external code. With a mock function we can know the number of times the function was called, the arguments it was called with, the result it returned, and more. This ability to "spy" on function calls is why mock functions are also called spies.

We use mock functions to override original function behaviour with custom mock implementations. Mock implementations help us control the return values of a function. This makes our tests more predictable (deterministic) and easier to write.

How to mock a function with Jest?

To mock a function with Jest we use the jest.fn() function.

jest.fn() can be called with an implementation function as an optional argument. If an implementation is provided, calling the mock function will call the implementation and return it's return value.

If no implementation is provided, calling the mock returns undefined because the return value is not defined.

// Without implementation, this mock returns `undefined`.
const mockUndefined = jest.fn();

// With implementation, this mock returns `true`.
const mockTrue = jest.fn(() => true).

Jest registers mock functions under the "jest.fn()" name by default. We can give the mock function a custom name with the mockName() method. The mock name is used when printing test results.

const mockOne = jest.fn(() => false);
// Example error: expect(jest.fn()).toHaveBeenCalledWith(...expected)

const mockTwo = jest.fn(() => false).mockName('mockTwo');
// Example error: expect(mockTwo).toHaveBeenCalledWith(...expected)

💡Note
It's good practice to name mocked functions in cases where a lot of different mocks are used. This makes it easier to tell mocked functions apart and debug code that isn't matching expectations.

How to change the mock implementation of a function with Jest?

To change the mock implementation of a function with Jest we use the mockImplementation() method of the mocked function.

The mockImplementation() method is called with the new implementation as its argument. The new implementation will then be used in place of the previous one when the mock is called.

// The initial mock is a function that returns `true`.
const myMock = jest.fn(() => true);

// The new mock implementation has the function return `false`.
myMock.mockImplementation(() => false);

We can combine this with jest.mock() factory functions to create mocked modules that contain mocked functions. This way we can control how the implementation of a mock behaves depending on what we're testing.

// isAtLeast18.spec.js
const isAtLeast18 = require("./isAtLeast18");
const isInteger = require("./isInteger");

// The mock factory returns a mocked function
jest.mock("./isInteger", () => jest.fn());

describe("isAtLeast18", () => {
    it("fails if value is not recognised as integer", () => {
        // For this test we'll mock isInteger to return `false`
        isInteger.mockImplementation(() => false);

        expect(isAtLeast18(123)).toBe(false);
        expect(isAtLeast18("abc")).toBe(false);
    });

    it("passes if value is recognised as integer and is at least 18", () => {
        // For this test we'll mock isInteger to return `true`
        isInteger.mockImplementation(() => true);

        expect(isAtLeast18(123)).toBe(true);
        expect(isAtLeast18("abc")).toBe(false);
    });
});

💡Note
jest.mock() works by modifying the Node module cache to give us the mock instead of the original implementation whenever we import a mocked module in a test file. To support ES module imports - where import statements have to come first in a file - Jest automatically hoists jest.mock() calls to the top of the module. Read more about this technique here.

How to check if a function was called correctly with Jest?

To check if a function was called correctly with Jest we use the expect() function with specific matcher methods to create an assertion.

We can use the toHaveBeenCalledWith() matcher method to assert the arguments the mocked function has been called with.

To assert how many times the mocked function has been called so far, we can use the toHaveBeenCalledTimes() matcher method.

// isAtLeast18.spec.js
const isAtLeast18 = require("./isAtLeast18");
const isInteger = require("./isInteger");

jest.mock("./isInteger", () => jest.fn());

describe("isAtLeast18", () => {
  it("fails if value is not recognised as integer", () => {
    isInteger.mockImplementation(() => false);

    expect(isAtLeast18(123)).toBe(false);

        // We expect isInteger to be called with 123
    expect(isInteger).toHaveBeenCalledWith(123);
        // We expect isInteger to be called once
    expect(isInteger).toHaveBeenCalledTimes(1);
  });
});

💡Note
While these are the most common matcher methods for functions, there are more matcher methods available in the Jest API docs.

Jest tracks all calls to mocked functions. A mocked function will remember the arguments and times it has been called, as well as the results of those calls.

When reusing mocked functions between tests it is useful to reset their states before running new tests to get a clear baseline. We can do that by clearing mocked functions between tests.

How to clear mocked functions with Jest?

To clear mocked functions with Jest we use the mockClear() method of a mocked function.

mockClear() resets all information stored in mocked functions which makes it useful for cleaning up a mock's usage data between assertions or tests.

// isAtLeast18.spec.js
const isAtLeast18 = require("./isAtLeast18");
const isInteger = require("./isInteger");

jest.mock("./isInteger", () => jest.fn());

describe("isAtLeast18", () => {
  it("fails if value is not recognised as integer", () => {
    isInteger.mockImplementation(() => false);

    expect(isAtLeast18(123)).toBe(false);
    expect(isInteger).toHaveBeenCalledWith(123);
    expect(isInteger).toHaveBeenCalledTimes(1);

        // Clear the mock so the next test starts with fresh data
    isInteger.mockClear();
  });

  it("passes if value is recognised as integer and is at least 18", () => {
    isInteger.mockImplementation(() => true);

    expect(isAtLeast18(123)).toBe(true);
    expect(isInteger).toHaveBeenCalledWith(123);
        // Without clearing, there would be 2 calls total at this point
    expect(isInteger).toHaveBeenCalledTimes(1);
  });
});

💡Note
Jest also provides mock function methods for resetting and restoring mocked functions, as well as shorthands for creating mocked functions that directly return, resolve, or reject a value.

How to clear mocked functions before each test with Jest?

To clear mocked functions before each test with Jest we use the beforeEach() function.

beforeEach() is called with one required argument - the function to run before each of the tests in the test file. We use it to clear mocks, set up fixtures, or reset some other state used across tests.

// isAtLeast18.spec.js
const isAtLeast18 = require("./isAtLeast18");
const isInteger = require("./isInteger");

jest.mock("./isInteger", () => jest.fn());

// Clear mock data before each test
beforeEach(() => {
  isInteger.mockClear();
});

describe("isAtLeast18", () => {
  it("fails if value is not recognised as integer", () => {
    isInteger.mockImplementation(() => false);

    expect(isAtLeast18(123)).toBe(false);
    expect(isInteger).toHaveBeenCalledWith(123);
    expect(isInteger).toHaveBeenCalledTimes(1);
  });

  it("passes if value is recognised as integer and is at least 18", () => {
    isInteger.mockImplementation(() => true);

    expect(isAtLeast18(123)).toBe(true);
    expect(isInteger).toHaveBeenCalledWith(123);
    expect(isInteger).toHaveBeenCalledTimes(1);
  });
});

💡Note
Jest provides four functions to hook into the set-up and tear-down process, both before and after each or all of the tests in a test file. These functions are: afterAll(), afterEach(), beforeAll(), beforeEach(). The afterAll() and beforeAll() variants are called only once for the entire test file. The afterEach() and beforeEach() variants are called once for every test in the test file.

How to reuse mocks with Jest?

To reuse mocks with Jest we create mocks in a __mocks__/ subdirectory adjacent to the module we want to mock.

Mock files in the __mocks__/ subdirectory are used to automock the modules they are adjacent to when the module is mocked with jest.mock(). This is useful when dealing with a lot of repetition in setting up mocks such as when mocking common dependencies or configuration objects because it makes writing a mock factory function unnecessary.

Assuming a common configuration file that is used by many different modules, mocking it would look like this:

// common/config.js
module.exports = { foo: "bar" };

// common/__mocks__/config.js
module.exports = { foo: "mockBar" };

// example.js
const config = require.("./common/config");

// Logs "bar"
module.exports = () => console.log(config.foo);

// example.spec.js
const example = require("./example");

jest.mock("./common/config");

// Logs "mockBar", no need for a mock factory
example();

💡Note
Remember: mocks and automocking are only in effect when running tests with Jest. They do not have an effect on the code in development or production.

That's it! We're now ready to mock imported functions with Jest.

Jest mock imported functions example code

The dependency in isInteger.js:

// isInteger.js
module.exports = (value) => Number.isSafeInteger(value);

The unit to be tested in isAtLeast18.js:

// isAtLeast18.js
const isInteger = require("./isInteger");

module.exports = (value) => isInteger(value) && value >= 18;

The unit test in isAtLeast18.spec.js:

// isAtLeast18.spec.js
const isAtLeast18 = require("./isAtLeast18");
const isInteger = require("./isInteger");

// The mock factory returns a mocked function
jest.mock("./isInteger", () => jest.fn());

beforeEach(() => {
  isInteger.mockClear();
});

describe("isAtLeast18", () => {
  it("fails if value is not recognised as integer", () => {
    isInteger.mockImplementation(() => false);

    expect(isAtLeast18(123)).toBe(false);
    expect(isInteger).toHaveBeenCalledWith(123);
    expect(isInteger).toHaveBeenCalledTimes(1);
  });

  it("passes if value is recognised as integer and is at least 18", () => {
    isInteger.mockImplementation(() => true);

    expect(isAtLeast18(123)).toBe(true);
    expect(isInteger).toHaveBeenCalledWith(123);
    expect(isInteger).toHaveBeenCalledTimes(1);
  });
});

Homework and next steps

Write more comprehensive tests and use fixtures to cover any additional cases. If you've done your homework from the previous article, try continuing from where you left off.
Fix the code so any failed tests pass or write a newer, better implementation.
Achieve 100% code coverage in the coverage report.

Thank you for taking the time to read through this article!

Have you tried mocking imported functions with Jest before? What was your experience like?

Leave a comment and start a discussion!

How to write unit tests in JavaScript with Jest

Domagoj Štrekelj — Sat, 24 Jul 2021 11:39:48 +0000

Unit testing is an important and often overlooked part of the development process. It is considered boring by many, and being traditionally difficult to properly set up earned it a poor reputation early on. The benefits of shipping quality code certainly outweigh any negatives, but how does one find the time and muster the effort to start writing unit tests?

Lucky for us, writing unit tests in JavaScript has never been faster, easier, and arguably more fun thanks to Jest.

Jest is a feature-rich JavaScript testing framework that aims to bring testing to the masses. It's near-zero configuration approach makes it simple to set up, and a familiar API makes writing tests fairly straightforward.

This article will provide a brief introduction into Jest and the concepts behind unit testing. We will learn how to install Jest, write test suites with test cases and fixtures, and run tests both with and without coverage reports.

We will assume that we're testing a module containing a simple function behaving as a validation rule. The rule checks whether the validated value is an integer number. For example:

// isInteger.js
module.exports = (value) => !isNaN(parseInt(value, 10));

This implementation is naive and faulty on purpose. We want to see what our tests will teach us about the flaws in our code by passing and failing test cases. Fixing the implementation is not covered by this article, but feel free to play with it as we move through it.

Read on to find out more!

What is a unit test?

A unit test is an automated test of a unit of source code. A unit test asserts if the unit's behaviour matches expectations.

A unit is usually a line of code, function, or class. There is no strict definition of what makes up a unit, but it's common to start with whatever seems "smallest".

Units that have no dependencies are called isolated (solitary) units. Units that have dependencies are called sociable units.

Solitary units are easy to test, but sociable units are more difficult. The output of a sociable unit depends on other units of code - if other units fail, the tested unit fails as well. This created two unit test styles: sociable unit tests and solitary unit tests.

Sociable unit tests fail if the dependencies of a sociable unit are also failing. The tested unit is not supposed to work if it's dependencies don't work, so a failing test in this case is a good sign.

Solitary unit tests isolate sociable units by creating mock implementations of their dependencies. Mocks control how dependencies behave during tests, making sociable units predictable to test.

No matter the unit test style, the goal of unit testing remains the same - to ensure that individual parts of the program are working correctly as expected.

What is Jest?

Jest is a JavaScript testing framework designed to make testing as easy as possible. It provides all the essential tools for running tests, making assertions, mocking implementations, and more in a single package.

Before Jest, the JavaScript ecosystem relied on several different tools and frameworks to give developers a way to write and run tests. Configuring these tools was rarely simple and easy. Jest aims to fix that by using sensible default configurations that work "out of the box", with little to no additional configuration required in most cases.

Jest is currently one of the most popular testing technology choices, consistently earning high satisfaction marks in the State of JS developer survey since 2017. It's the reliable choice for testing JavaScript projects.

💡Note
Jest also supports TypeScript via Babel.

How to install Jest?

Install the jest package (and optional typings) to a new or existing project's package.json file using your package manager of choice:

# For NPM users
npm install --save-dev jest @types/jest

# Yarn users
yarn add --dev jest @types/jest

That's it! We're now ready to run tests with Jest.

💡Note
It's good practice to install Jest and any other testing tools as development dependencies. This speeds up installation in environments where only dependencies required for the project to build and run are installed.

How to run tests with Jest?

To run tests with Jest call the jest command inside the root of the project folder.

We will update the project's package.json with a test script that calls the jest command for us:

{
    // ... package.json contents
    "scripts": {
        // ... existing scripts
        "test": "jest"
    }
}

We can now run the newly created test script:

# NPM users
npm run test

# Yarn users
yarn run test

If everything is set up correctly Jest will give us the results of any tests it found and ran.

💡Note
Jest exits with status code 1 when a test case fails. Seeing npm ERR! errors in the console is expected in this case.

How to create a test with Jest?

To create a test for use with Jest we create a *.spec.js or *.test.js file that will contain our test cases.

💡Note
Jest is configured by default to look for .js, .jsx, .ts and .tsx files inside of __tests__ folders, as well as any files with a suffix of .test or .spec (this includes files called test or spec).

Since isInteger.js is the name of the module we're testing, we will write our tests in an isInteger.spec.js file created in the same folder as the module:

// isInteger.spec.js
test("Sanity check", () => {
    expect(true).toBe(true);
});

💡Note
Whether you choose to write tests inside a dedicated folder or right next to your modules, there is no right or wrong way to structure tests inside a project. Jest is flexible enough to work with most project architectures without configuration.

The test's description is "Sanity check". Sanity checks are basic tests to ensure the system behaves rationally. The test will assert that we expect the value true to be true.

Run the test and if it passes everything is set up correctly.

Congratulations! We just wrote our first test!

How to write a test case in Jest?

To write a test case we first define the outcomes that we must validate to ensure that the system is working correctly.

The isInteger.js module is a function that takes one parameter and returns true if the parameter is an integer value or false if it isn't. We can create two test cases from that definition:

isInteger() passes for integer value;
isInteger() fails for non-integer value.

To create a test case in Jest we use the test() function. It takes a test name string and handler function as the first two arguments.

💡Note
The test() function can also be called under the alias - it(). Choose one over the other depending on readability or personal preference.

Tests are based on assertions. Assertions are made up of expectations and matchers. The simplest and most common assertion expects the tested value to match a specific value.

An expectation is created with the expect() function. It returns an object of matcher methods with which we assert something expected about the tested value. The matcher method toBe() checks if the expectation matches a given value.

In our tests, we can expect isInteger() to be true for the integer value 1, and false for the non-integer value 1.23.

// isInteger.spec.js
const isInteger = require("./isInteger");

test("isInteger passes for integer value", () => {
    expect(isInteger(1)).toBe(true);
});

test("isInteger fails for non-integer value", () => {
    expect(isInteger(1.23)).toBe(false);
});

Running Jest should now give us a report on which tests pass, and which tests fail.

How to use fixtures in Jest?

To use fixtures in Jest we can use the test.each() function. It performs a test for each fixture in an array of fixtures.

Fixtures are data representing conditions - such as function arguments and return values - under which the unit test is performed. Using fixtures is a quick and easy way to assert that a unit's behaviour matches expectations under different conditions without having to write multiple tests.

In Jest, a fixture can be a single value or an array of values. The fixture is available in the test handler function through parameters. The value or values of a fixture can be injected in the description through printf formatting.

// isInteger.spec.js
const isInteger = require("./isInteger");

const integerNumbers = [-1, 0, 1];

test.each(integerNumbers)(
    "isInteger passes for integer value %j",
    (fixture) => expect(isInteger(fixture)).toBe(true)
);

// ... or...
const integerNumbers = [
  [-1, true],
  [-0, true],
  [1, true]
];

test.each(integerNumbers)(
    "isInteger passes for integer value %j with result %j",
    (fixture, result) => expect(isInteger(fixture)).toBe(result)
);

Running Jest should now give us a report on which tests pass, and which tests fail, where every test corresponds to a fixture from our array of fixtures.

💡Note
%j is a printf formatting specifier that prints the value as JSON. It's a good choice for fixtures that contain values of different types.

How to group test cases in Jest into a test suite?

To group test cases in Jest into a test suite we can use the describe() function. It takes a suite name string and handler function as the first two arguments.

A test suite is a collection of test cases grouped together for execution purposes. The goal of a test suite is to organise tests by common behaviour or functionality. If all tests within a suite pass, we can assume that the tested behaviour or functionality meets expectations.

// isInteger.spec.js
const isInteger = require("./isInteger");

describe("isInteger", () => {
    const integerNumbers = [-10, -1, 0, 1, 10];

    test.each(integerNumbers)(
        "passes for integer value %j",
        (fixture) => expect(isInteger(fixture)).toBe(true)
    );

    const floatNumbers = [-10.1, -1.1, 0.1, 1.1, 10.1];

    test.each(floatNumbers)(
        "fails for non-integer value %j",
        (fixture) => expect(isInteger(fixture)).toBe(false)
    );
});

Running Jest should now give us a report on which tests pass, and which tests fail, grouped into described test suites.

💡Note
describe() blocks can also be nested to create more complex test hierarchies.

How to run Jest every time files change?

To run Jest every time files change we can use the --watch and --watchAll flags.

The --watch flag will tell Jest to watch for changes in files tracked by Git. Jest will run only those tests affected by the changed files. For this to work, the project must also be a Git repository.

The --watchAll flag will tell Jest to watch all files for changes. Whenever a file changes, Jest will run all tests.

Both --watch and --watchAll modes support additional filtering of tests while the tests are running. This makes it possible to only run tests matching a file name, or only run failing tests.

# Runs tests on changed files only and re-runs for any new change
# Note: the project must also be a git repository
jest --watch

# Runs tests on all files and re-runs for any new change
jest --watchAll

How to get a test coverage report with Jest?

To get a test coverage report with Jest we can use the --coverage flag.

Test coverage is a software testing metric that describes how many lines of source code (statements) of the tested unit are executed (covered) by tests. A test coverage of 100% for a unit means every line of code in the unit has been called by the test.

We should always aim for a high test coverage - ideally 100% - but also keep in mind that total coverage does not mean we tested all cases, only lines of code.

# Runs tests and prints a test coverage afterwards
jest --coverage

💡Note
We can combine different flags to get more features out of Jest. For example, to watch all files and get a coverage report we can run jest --watchAll --coverage.

With that we're all set! We can now write tests and run them whenever a file changes, and also review test coverage reports for covered and uncovered lines of code.

Jest unit test example code

To install Jest:

# For NPM users
npm install --save-dev jest @types/jest

# Yarn users
yarn add --dev jest @types/jest

The unit to be tested in isInteger.js:

// isInteger.js
module.exports = (value) => !isNaN(parseInt(value, 10));

The unit test in isInteger.spec.js:

// isInteger.spec.js
const isInteger = require("./isInteger");

describe("isInteger", () => {
    const integerNumbers = [-10, -1, 0, 1, 10];

    test.each(integerNumbers)(
        "passes for integer value %j",
        (fixture) => expect(isInteger(fixture)).toBe(true)
    );

    const floatNumbers = [-10.1, -1.1, 0.1, 1.1, 10.1];

    test.each(floatNumbers)(
        "fails for non-integer value %j",
        (fixture) => expect(isInteger(fixture)).toBe(false)
    );
});

The test script in package.json:

jest --watchAll --coverage

Homework and next steps

Write more comprehensive tests. How are strings handled? Objects? null and undefined? Consider adding more fixtures to cover these cases.
Fix the code so the tests pass or write a newer, better implementation.
Achieve 100% code coverage in the coverage report.

Thank you for taking the time to read through this article!

Have you tried writing unit tests in Jest before? How do you feel about Jest?

Leave a comment and start a discussion!

How to create a binary decision tree in JavaScript

Domagoj Štrekelj — Sat, 29 May 2021 20:40:32 +0000

Stuck writing large and nested if-else if-else conditions? Trouble following how all these different conditions interact and flow together? Here's a tool that can help: decision trees.

Decision trees are a way to model conditional logic in a clear and composable way. Although commonly used in machine learning, they can be just as useful in more "typical" use cases which we will explore in this article.

This article will provide a brief introduction into trees as a data structure and decision trees as a tool, as well as their application in software development.

We will create a binary decision tree in JavaScript step-by-step and apply it to decide whether a value is a positive number, negative number, zero, or not a number at all.

Read on to find out more!

What is a tree data structure?

A tree data structure is a type of data structure in which data - represented by nodes - is connected in such a way that every node branches out into zero or more child nodes.

Visualising node connections gives the structure the appearance of a tree, hence the name.

What is a binary tree data structure?

A binary tree data structure is a special type of tree data structure where every node can have up to two child nodes: a left child node, and a right child node.

A binary tree begins with a root node. The root node can then branch out into left and right child nodes, each child continuing to branch out into left and right child nodes as well.

Nodes that branch out into children are called non-leaf nodes. Nodes without children are called leaf nodes.

Going through the nodes of a binary tree - traversing the tree - gives us the choice of moving to either the left or right child node - a binary choice - earning this type of tree the name binary tree.

What is a decision tree?

A decision tree is a tool to help visualise decisions and the consequences of their outcomes.

At its simplest, a decision tree contains decision nodes and outcome nodes (also called end nodes).

Decision trees may also contain chance nodes. Chance nodes serve as "weights" to favour one family of outcomes over another under certain conditions.

There are many different ways to visualise decision trees, one example being flowchart symbols.

What is a binary decision tree?

A binary decision tree is a decision tree implemented in the form of a binary tree data structure.

A binary decision tree's non-leaf nodes represent conditions and its leaf nodes represent outcomes.

By traversing a binary decision tree we can decide on an outcome under a given context and conditions.

What are decision tree applications?

Decision trees can be applied for predictive modelling in statistics, data mining, and machine learning.

Decision trees can also be applied in game development for building AIs and branching story paths, as well as general development scenarios where there is a need to handle large chains of interconnected conditional statements.

How to turn conditional statements into binary decision tree nodes?

To turn conditional statements into binary decision tree nodes, we have to treat conditional statements and outcomes as arguments passed to decision functions.

We will begin designing our decision tree data structure API by looking at conditional statements in our example.

The decideNumberSign function takes in a parameter x and attempts to return its sign, 0 or ? if the sign cannot be determined:



function decideNumberSign(x) {
    if (x > 0) {
        return "+";
    } else if (x < 0) {
        return "-";
    } else if (x === 0) {
        return "0";
    } else {
        return "?";
    }
}

When it comes to making decisions based on a condition, we need to define an outcome for the case of the condition being true, and another outcome for the case of it being false. With that in mind, our decision node function would look like this:



decision(x > 0, "+", "-");

Combining decision nodes would then look like this:



decision(x > 0, "+", decision(x < 0, "-", decision(x === 0, "0", "?")));

To support more complex conditions and prevent evaluating conditions on nodes that won't be traversed, we can refactor our condition expressions into functions that will only be called when the node is reached:



const isPositive = x => x > 0;
const isNegative= x => x < 0;
const isZero = x => x === 0;

decision(isPositive, "+", decision(isNegative, "-", decision(isZero, "0", "?")));

With the API finalised, we can implement the function:



const decision = (conditionFunction, trueOutcome, falseOutcome) =>
    (context) => conditionFunction(context) ? trueOutcome : falseOutcome;

We can now build a decision tree out of decision nodes, but we can't traverse the tree just yet. To traverse the tree and reach a decision we must be able to test the conditions by calling them with a context.

How to perform binary decision tree traversal?

To traverse a binary decision tree we provide a context to the root node of the tree, which then calls its condition function and any decision node condition functions that follow as outcomes.

Let's again start by outlining the API:



const context = "number";
const numberSignDecision = decision(isPositive, "+", decision(isNegative, "-", decision(isZero, "0", "?")));

decide(context, numberSignDecision);

We have to keep in mind that the outcome of our decisions - our left and / or right child nodes - will either be a new decision node (function) or non-callable value (anything but a function).

If the outcome of our decision is another decision node, we have to decide the new node's outcome for the current context until we reach a non-callable value.

If the outcome of our decision node is a non-callable value we return the value.

By deciding the outcome of every decision node we reach in that way, we will effectively traverse the decision tree and reach a decision.



const decide = (context, decision) => {
    const outcome = decision(context);

    return typeof outcome === "function" ? decide(context, outcome) : outcome;
}

That's it, we're done! That's all there is to creating a simple binary decision tree in JavaScript.

JavaScript binary decision tree example code



// Decision tree API

const decision = (conditionFunction, trueOutcome, falseOutcome) =>
    (context) => conditionFunction(context) ? trueOutcome : falseOutcome;

const decide = (context, decision) => {
    const outcome = decision(context);

    return typeof outcome === "function" ? decide(context, outcome) : outcome;
}

// Example

const isPositive = x => x > 0;
const isNegative= x => x < 0;
const isZero = x => x === 0;

const numberSignDecision =
    decision(isPositive,
        "+",
        decision(isNegative,
            "-",
            decision(isZero,
                "0",
                "?"
            )
        )
    );

const contextValues = [ "number", 1,    0, -1, Number.NaN, ];

for (const value of contextValues) {
    console.log(value, decide(value, numberSignDecision));
}

Homework and next steps

Improve the decision() function to check whether the conditionFunction argument is a function or not before calling it. This will make the function more robust and provide us with a way to short-circuit our decision with truthy or falsey values, which can be very useful for debugging purposes.
Try turning our binary decision tree into an m-ary decision tree. M-ary decision trees can have more than two decision nodes. In their case we may not have true and false as outcomes, but rather 1 and 0 as well as any value in between which would represent how certain we are in the outcome.

Thank you for taking the time to read through this article!

Do you have any experience creating decision trees? Have you tried implementing one yourself?

Leave a comment and start a discussion!