Testing TypeScript with Jest

Installation and Jest setup

Refer to https://jestjs.io/docs/getting-started

Matchers

Full list of matchers: https://jestjs.io/docs/expect

Matching exact equality with `toBe`

1
test('two plus two is four', () => {
2
  expect(2 + 2).toBe(4);
3
});

Matching value equality with `toEqual`

1
test('object assignment', () => {
2
  const data = {one: 1};
3
  data['two'] = 2;
4
  expect(data).toEqual({one: 1, two: 2});
5
});

Matching opposites with `not`

1
test('two plus two is four', () => {
2
  expect(2 + 2).not.toBe(22);
3
});

Matching truthiness, null, undefined and defined

toBeNull matches only null
toBeUndefined matches only undefined
toBeDefined is the opposite of toBeUndefined
toBeTruthy matches anything that an if statement treats as true
toBeFalsy matches anything that an if statement treats as false

Matching numbers

1
test('two plus two', () => {
2
  const value = 2 + 2;
3
  expect(value).toBeGreaterThan(3);
4
  expect(value).toBeGreaterThanOrEqual(3.5);
5
  expect(value).toBeLessThan(5);
6
  expect(value).toBeLessThanOrEqual(4.5);
7

8
  // toBe and toEqual are equivalent for numbers
9
  expect(value).toBe(4);
10
  expect(value).toEqual(4);
11
});

Matching floating point numbers

1
test('adding floating point numbers', () => {
2
  const value = 0.1 + 0.2;
3
  //expect(value).toBe(0.3);           This won't work because of rounding error
4
  expect(value).toBeCloseTo(0.3); // This works.
5
});

Matching strings using regular expression with `toMatch`

1
test('there is no I in team', () => {
2
  expect('team').not.toMatch(/I/);
3
});
4

5
test('but there is a "stop" in Christoph', () => {
6
  expect('Christoph').toMatch(/stop/);
7
});

Matching arrays and iterables with `toContain`

1
const shoppingList = [
2
  'diapers',
3
  'kleenex',
4
  'trash bags',
5
  'paper towels',
6
  'milk',
7
];
8

9
test('the shopping list has milk on it', () => {
10
  expect(shoppingList).toContain('milk');
11
  expect(new Set(shoppingList)).toContain('milk');
12
});

Matching exceptions with `toThrow`

1
function compileAndroidCode() {
2
  throw new Error('you are using the wrong JDK!');
3
}
4

5
test('compiling android goes as expected', () => {
6
  expect(() => compileAndroidCode()).toThrow();
7
  expect(() => compileAndroidCode()).toThrow(Error);
8

9
  // You can also use a string that must be contained in the error message or a regexp
10
  expect(() => compileAndroidCode()).toThrow('you are using the wrong JDK');
11
  expect(() => compileAndroidCode()).toThrow(/JDK/);
12

13
  // Or you can match an exact error message using a regexp like below
14
  expect(() => compileAndroidCode()).toThrow(/^you are using the wrong JDK$/); // Test fails
15
  expect(() => compileAndroidCode()).toThrow(/^you are using the wrong JDK!$/); // Test pass
16
});

Testing Promises

1
test('the data is peanut butter', () => {
2
  return fetchData().then(data => {
3
    expect(data).toBe('peanut butter');
4
  });
5
});

Make sure to return the Promise, otherwise the test will complete prematurely.

Testing async/await with `.resolves` and `.rejects`

1
test('the data is peanut butter', async () => {
2
  await expect(fetchData()).resolves.toBe('peanut butter');
3
});
4

5
test('the fetch fails with an error', async () => {
6
  await expect(fetchData()).rejects.toMatch('error');
7
});

Testing callbacks with `done`

1
test('the data is peanut butter', done => {
2
  function callback(error, data) {
3
    if (error) {
4
      done(error);
5
      return;
6
    }
7
    try {
8
      expect(data).toBe('peanut butter');
9
      done();
10
    } catch (error) {
11
      done(error);
12
    }
13
  }
14

15
  fetchData(callback);
16
});

Inspecting a `jest.fn()` mock

jest.fn() is used to create a new, standalone mock function. It’s not tied to any specific object or method, and you can use it to replace any function in your test code. The mock property on a jest.fn() tracks calls, results, contexts, instances and lastCall:

1
const myMock1 = jest.fn();
2
const a = new myMock1();
3
console.log(myMock1.mock.instances);
4
// > [ <a> ]
5

6
const myMock2 = jest.fn();
7
const b = {};
8
const bound = myMock2.bind(b);
9
bound();
10
console.log(myMock2.mock.contexts);
11

12
// The function was called exactly once
13
expect(someMockFunction.mock.calls).toHaveLength(1);
14

15
// The first arg of the first call to the function was 'first arg'
16
expect(someMockFunction.mock.calls[0][0]).toBe('first arg');
17

18
// The first argument of the last call to the function was 'test'
19
expect(someMockFunction.mock.lastCall[0]).toBe('test');

Alternatively, there are convenient matchers:

1
// The mock function was called at least once
2
expect(mockFunc).toHaveBeenCalled();
3

4
// The mock function was called at least once with the specified args
5
expect(mockFunc).toHaveBeenCalledWith(arg1, arg2);
6

7
// The last call to the mock function was called with the specified args
8
expect(mockFunc).toHaveBeenLastCalledWith(arg1, arg2);
9

10
// All calls and the name of the mock is written as a snapshot
11
expect(mockFunc).toMatchSnapshot();

Spying on implementation with jest.spyOn

jest.spyOn is primarily used to spy on existing functions or methods, tracking their calls and behavior without modifying their implementation.

1
const obj = {
2
  method: () => {}
3
};
4

5
const spy = jest.spyOn(obj, 'method');
6

7
// Now 'method' is a spy, you can check if it's been called, etc.
8
obj.method();
9
expect(spy).toHaveBeenCalled();

Mocking `jest.fn()` return values

1
// By default a mock returns undefined
2
const myMock = jest.fn();
3
console.log(myMock());
4

5
// Mock can be chained
6
myMock.mockReturnValueOnce(10).mockReturnValueOnce('x').mockReturnValue(true);
7

8
console.log(myMock(), myMock(), myMock(), myMock());
9
// > 10, 'x', true, true

Mocking implementation of a function with `jest.fn` or the `mockImplementation`

Instead of just mocking the return values, we can mock the whole functionality of a function:

1
jest.mock('../foo'); // this happens automatically with automocking
2
const foo = require('../foo');
3

4
// foo is a mock function
5
foo.mockImplementation(() => 42);
6
foo();
7
// > 42

We can also change implementation on a per-invocation basis:

1
const myMockFn = jest
2
  .fn(() => 'default')
3
  .mockImplementationOnce(() => 'first call')
4
  .mockImplementationOnce(() => 'second call');
5

6
console.log(myMockFn(), myMockFn(), myMockFn(), myMockFn());
7
// > 'first call', 'second call', 'default', 'default'

Mocking functions that must return this keyword (to allow chaining):

1
const myObj = {
2
  myMethod: jest.fn().mockReturnThis(),
3
};
4

5
// is the same as
6

7
const otherObj = {
8
  myMethod: jest.fn(function () {
9
    return this;
10
  }),
11
};

Adding a name with `mockName`

To be able to quickly identify the mock function reporting an error in your test output.

1
const myMockFn = jest
2
  .fn()
3
  .mockReturnValue('default')
4
  .mockImplementation(scalar => 42 + scalar)
5
  .mockName('add42');

Mocking a whole module with `jest.mock`

This code uses a third-party module axios to make a request.

1
import axios from 'axios';
2

3
class Users {
4
  static all() {
5
    return axios.get('/users.json').then(resp => resp.data);
6
  }
7
}
8

9
export default Users;

We want to mock the whole axios module, especially axios.get function to prevent making a real request. By specifying jest.mock('axios') jest automatically mocks the whole module, effectively replacing every method in axios module with a jest.fn() function, giving us the possibility to return custom mock-values.

1
import axios from 'axios';
2
import Users from './users';
3

4
jest.mock('axios');
5

6
test('should fetch users', () => {
7
  const users = [{name: 'Bob'}];
8
  const resp = {data: users};
9
  axios.get.mockResolvedValue(resp);
10

11
  // or you could use the following depending on your use case:
12
  // axios.get.mockImplementation(() => Promise.resolve(resp))
13

14
  return Users.all().then(data => expect(data).toEqual(users));
15
});

Mocking a whole module with `jest.mock` and `mocks` folder (Manual mocks)

https://jestjs.io/docs/manual-mocks

Let’s assume your code looks like that:

1
import user from './user';
2

3
class Employees {
4
  static all() {
5
    return user.getThemAll();
6
  }
7
}
8

9
export default Employees;

You want to mock the whole user module. First locate user.js, then create a folder __mocks__ on the same level, then add an empty user.js to __mocks__ folder and insert your mock code:

1
// Define a mock implementation for the user module
2

3
const user = {
4
  getThemAll: jest.fn().mockReturnValue(['John', 'Jane', 'Doe']),
5
};
6

7
export default user;

And your test file

1
import Employees from './Employees'; // Import the module to be tested
2
import user from './user'; // Import the mocked user module
3

4
describe('Employees', () => {
5
  // Test suite for the Employees class
6

7
  // Test case for the static all() method
8
  describe('all', () => {
9
    it('returns an array of employees', () => {
10
      // Define a mock implementation for user.getThemAll()
11
      user.getThemAll.mockReturnValue(['John', 'Jane', 'Doe']);
12

13
      // Call the static all() method of Employees
14
      const employees = Employees.all();
15

16
      // Assertions
17
      expect(employees).toEqual(['John', 'Jane', 'Doe']); // Check if the return value is as expected
18
      expect(user.getThemAll).toHaveBeenCalled(); // Check if user.getThemAll() has been called
19
    });
20
  });
21
});

Mocking parts of a module with `jest.requireActual`

Let’s say we have this module

1
export const foo = 'foo';
2
export const bar = () => 'bar';
3
export default () => 'baz';

We only want to mock it partially, for example we only want to mock the default export and foo but leave bar untouched:

1
import defaultExport, {bar, foo} from '../foo-bar-baz';
2

3
jest.mock('../foo-bar-baz', () => {
4
  const originalModule = jest.requireActual('../foo-bar-baz');
5

6
  //Mock the default export and named export 'foo'
7
  return {
8
    __esModule: true,
9
    ...originalModule,
10
    default: jest.fn(() => 'mocked baz'),
11
    foo: 'mocked foo',
12
  };
13
});
14

15
test('should do a partial mock', () => {
16
  const defaultExportResult = defaultExport();
17
  expect(defaultExportResult).toBe('mocked baz');
18
  expect(defaultExport).toHaveBeenCalled();
19

20
  expect(foo).toBe('mocked foo');
21
  expect(bar()).toBe('bar');
22
});

Partial mocking makes sense when you test code that still relies partly on the real implementation of the module. Consider you have this code:

1
import fetch from 'node-fetch';
2

3
export const createUser = async () => {
4
  const response = await fetch('https://website.com/users', {method: 'POST'});
5
  const userId = await response.text();
6
  return userId;
7
};

You write a test an completely mock node-fetch:

1
jest.mock('node-fetch');
2

3
import fetch, {Response} from 'node-fetch';
4
import {createUser} from './createUser';
5

6
test('createUser calls fetch with the right args and returns the user id', async () => {
7
  fetch.mockReturnValue(Promise.resolve(new Response('4')));
8

9
  const userId = await createUser();
10

11
  expect(fetch).toHaveBeenCalledTimes(1);
12
  expect(fetch).toHaveBeenCalledWith('https://website.com/users', {
13
    method: 'POST',
14
  });
15
  expect(userId).toBe('4');
16
});

Running the test creates an error TypeError: response.text is not a function. That is because you unintentionally mocked a part of node-fetch that is responsible for properly handling a Response. To solve this, you need to tell Jest to exclude the Response object from mocking. You can do this by adding requireActual:

1
jest.mock('node-fetch');
2
import fetch from 'node-fetch';
3
const {Response} = jest.requireActual('node-fetch');

Automatic mocks vs Manual mocks

Automatic Mocks with `jest.mock()`

Advantages:

Ease of Use: It’s convenient to use jest.mock() directly in your test file. You simply specify the module you want to mock, and Jest takes care of replacing all its exports with mock functions.
Granular Control: jest.mock() allows you to mock specific functions or classes within a module, providing granular control over what gets mocked and what doesn’t.
Dynamic Mocking: You can dynamically adjust the behavior of mocked functions using mockReturnValue(), mockResolvedValue(), etc., based on your test scenarios.
Local Scope: Mocks applied with jest.mock() are local to the test file where they’re defined, making it easier to manage and reason about the mocks in each test.

Disadvantages:

Verbose Setup: In some cases, setting up mocks using jest.mock() can be verbose, especially when dealing with multiple mocked functions or complex mock configurations.
Less Discoverable: Since mocks are defined within the test file, it may be less discoverable for other developers who are not familiar with the test suite.

Manual Mocks with `mocks` Folder

Advantages:

Separation of Concerns: Manual mocks in the __mocks__ folder keep your test code cleaner and separate from your source code, promoting a clearer separation of concerns.
Global Configuration: Mocks defined in the __mocks__ folder are global, meaning they apply across all test files that import the mocked module. This can be advantageous for ensuring consistent behavior across tests.
Simplified Test Code: Test files become simpler as they don’t need to define mocks explicitly. The mocked implementations are automatically applied when importing the module.

Disadvantages:

Less Granular Control: Manual mocks may not offer as granular control over mocking specific functions or classes within a module compared to jest.mock().
Potential Overhead: The __mocks__ folder might introduce overhead in larger projects, especially if multiple modules require manual mocks, potentially cluttering the project structure.
Global Scope: Since mocks defined in the __mocks__ folder are global, they can lead to unintended consequences if not used carefully, potentially affecting unrelated tests.

In summary, choosing between automatic mocks with jest.mock() and manual mocks using the __mocks__ folder depends on factors like project size, complexity, and developer preference. jest.mock() offers more granular control and local scope, while __mocks__ provides a cleaner separation of concerns and global configuration. Consider these factors when deciding which approach best suits your testing needs.

Installation and Jest setup

Matchers

Matching exact equality with toBe

Matching value equality with toEqual

Matching opposites with not

Matching numbers

Matching floating point numbers

Matching strings using regular expression with toMatch

Matching arrays and iterables with toContain

Matching exceptions with toThrow

Testing Promises

Testing async/await with .resolves and .rejects

Testing callbacks with done

Inspecting a jest.fn() mock