@morgan-stanley/ts-mocking-bird

A fully type safe mocking, call verification and import replacement library that works with jasmine and jest

Documentation: https://morganstanley.github.io/ts-mocking-bird/

Why use this?

• All operations fully type safe
• Mocks interfaces, existing objects and classes
• Mocks constructor, static functions, static properties as well as instance functions and properties
• Verifies function calls (with type safe parameter verification), as well as getter and setter calls
• Replaces imports (again, fully type safe)

Typescript Version

Requires a minimum Typescript version of 5.0.

Framework support

This library has been tested with and supports Jasmine versions 2 - 5, Jest versions 26 - 29 and vitest version 3. The mocking functionality should work in any environment as it has no dependencies on any particular framework.

Usage

1npm install @morgan-stanley/ts-mocking-bird

Create a Mock

Examples

Creates a mock that is typed as IMyService. Properties and functions can be setup using mockedService. The actual mocked service is accessible at mockedService.mock.

1import {
2    defineProperty,
3    defineStaticProperty,
4    IMocked,
5    Mock,
6    setupFunction,
7    setupProperty,
8    setupStaticFunction,
9} from '@morgan-stanley/ts-mocking-bird';
10
11const mockedService: IMocked<IMyService> = Mock.create<IMyService>().setup(
12    setupFunction('functionOne'), // allows the function to be called and allows verification of calls
13    setupFunction('functionTwo', (value: string) => (value === 'something' ? true : false)), // specifies return value
14    setupProperty('propOne', 'initialValue'),
15    defineProperty('propTwo', () => 'getter return value', (value: string) => console.log(`setter called: ${value}`)), // define getter and setter mocks
16);
17
18const systemUnderTest = new SUT(mockedService.mock); // pass mock instance to system under test

Mocking a Class with Constructor and Statics

Creates a mock that has statics and can be instantiated using new mockedService.mock().

1const mockedService = Mock.create<MyService, typeof MyService>().setup(
2    setupStaticFunction('staticFunctionOne', () => 'mockedReturnValue'),
3    defineStaticProperty('staticPropOne', () => 'mockedStaticGetter'),
4);
5
6const systemUnderTest = new ClassWithConstructorArgument(mockedService.mockConstructor); // pass mock constructor to system under test

Verify Calls

Examples

Adding Custom Matchers

When a mock is created using Mock.create() the custom matchers that are used by ts-mocking-bird are automatically setup in jest, jasmine or vitest - whichever framework you are using. However this can only be done if the creation occurs within a before function. If you need to manually setup the custom matchers please call addMatchers():

1import { addMatchers } from '@morgan-stanley/ts-mocking-bird'
2
3describe("my test", () => {
4    beforeEach(() => {
5        addMatchers();
6    })
7})

For jasmine this has to be done in a beforeEach or beforeAll function but for jest and vitest it can be done in the test setup file.

Verify that a function was called a number of times without checking parameters

1const mockedService: IMocked<IMyService> = Mock.create<IMyService>().setup(setupFunction('functionOne'));
2
3const systemUnderTest = new ClassWithInstanceArgument(mockedService.mock);
4
5expect(mockedService.withFunction('functionOne')).wasCalled(5);

Verify that a function was called once with specific parameters:

1const mockedService: IMocked<IMyService> = Mock.create<IMyService>().setup(setupFunction('functionOne'));
2
3const systemUnderTest = new ClassWithInstanceArgument(mockedService.mock);
4
5expect(
6    mockedService
7        .withFunction('functionTwo')
8        .withParameters('someValue')
9        .strict(),
10).wasCalledOnce();

NOTE: .withParameters doe a strict equality check on the value you give it. It you want to see if the values are equal (for example two identical objects that are different instances) use .withParametersEqualTo.

Verify Constructor Parameters

1const mockInstance = Mock.create<ClassWithInstanceArgument, typeof ClassWithInstanceArgument>().setup(
2            setupConstructor(),
3        );
4
5new mockInstance.mockConstructor(serviceInstance);
6
7expect(mockInstance.withConstructor().withParameters(serviceInstance)).wasCalledOnce();
8

Verify Getter:

1const mockedService: IMocked<IMyService> = Mock.create<IMyService>().setup(setupProperty('propOne'));
2
3const systemUnderTest = new ClassWithInstanceArgument(mockedService.mock);
4
5expect(mockedService.withGetter('propOne')).wasCalledOnce();

Verify Setter:

1const mockedService: IMocked<IMyService> = Mock.create<IMyService>().setup(setupProperty('propOne'));
2
3const systemUnderTest = new ClassWithInstanceArgument(mockedService.mock);
4
5expect(
6    mockedService
7        .withSetter('propOne')
8        .withParameters('someValue')
9        .strict(),
10).wasCalledOnce();

Verify that a function was called once and was not called any other times using strict:

If we use strict() we ensure that the function is ONLY called with the specified parameters

1const mockedService: IMocked<IMyService> = Mock.create<IMyService>().setup(setupFunction('functionTwo'));
2
3const systemUnderTest = new ClassWithInstanceArgument(mockedService.mock);
4
5systemUnderTest.functionsTwo('someValue');
6systemUnderTest.functionsTwo('someOtherValue');
7
8expect(
9    mockedService
10        .withFunction('functionTwo')
11        .withParameters('someValue')
12        .strict()
13    ).wasCalledOnce(); // this will fail as called twice in total
14
15expect(
16    mockedService
17        .withFunction('functionTwo')
18        .withParameters('someValue')
19    ).wasCalledOnce(); // this will pass as only called once with params 'someValue'

Verify function calls using a function verifier returned from myMock.setupFunction():

1const mockedService: IMocked<IMyService> = Mock.create<IMyService>();
2const functionVerifier = mockedService.setupFunction('functionTwo');
3
4const systemUnderTest = new ClassWithInstanceArgument(mockedService.mock);
5
6expect(functionVerifier.withParameters('someValue')).wasCalledOnce();

Verify Function Parameters

Examples

Verify that function parameters match using strict equality

1const sampleMock = Mock.create<ISampleMocked>().setup(setupFunction('functionOne'));
2
3const sampleObject: IPerson = { name: 'Fred', id: 1 };
4sampleMock.mock.functionOne('one', 2, sampleObject);
5
6expect(
7    sampleMock
8        .withFunction('functionOne')
9        .withParameters('one', 2, sampleObject) // strict equality
10    ).wasCalledOnce();

Verify that function parameter values are equal

1const sampleMock = Mock.create<ISampleMocked>().setup(setupFunction('functionOne'));
2
3sampleMock.mock.functionOne('one', 2, { name: 'Fred', id: 1 });
4
5expect(
6    sampleMock
7        .withFunction('functionOne')
8        .withParametersEqualTo('one', 2, { name: 'Fred', id: 1 }) // equals used to match
9    ).wasCalledOnce();

Use alternate matchers

1import { toBeDefined, any } from "@morgan-stanley/ts-mocking-bird"
2
3const sampleMock = Mock.create<ISampleMocked>().setup(setupFunction('functionOne'));
4
5sampleMock.mock.functionOne('one', 2, { name: 'Fred', id: 1 });
6
7expect(
8    sampleMock
9        .withFunction('functionOne')
10        .withParameters('one', toBeDefined(), any())
11    ).wasCalledOnce();

Match values with a function

A function with a signature of (value: T) => boolean can be used to match a parameter value but this will not provide information about what the expected parameter value is in the test failure message.

1const sampleMock = Mock.create<ISampleMocked>().setup(setupFunction('functionOne'));
2
3sampleMock.mock.functionOne('one', 2, { name: 'Fred', id: 1 });
4
5expect(
6    sampleMock
7        .withFunction('functionOne')
8        .withParameters('one', 2, person => person.id === 1)
9    ).wasCalledOnce();

Create a custom IParameterMatcher to create more informative failure messages

1const sampleMock = Mock.create<ISampleMocked>().setup(setupFunction('functionOne'));
2
3sampleMock.mock.functionOne('one', 2, { name: 'Fred', id: 1 });
4
5expect(
6    sampleMock
7        .withFunction('functionOne')
8        .withParameters(toBe('one'), toBe(2), {
9            isExpectedValue: person => person.id === 1,
10            expectedDisplayValue: 'Person with id 1', // Used to display expected parameter value in failure message
11            parameterToString: person => `Person with id ${person.id}`, // Used to display value of actual parameters passed in failure message
12        })
13    ).wasCalledOnce();

Replace Imports

Examples

Jest Modules

Using proxyModule we proxy all functions and constructors in a module so that they can be replaced at a later point. This allows us to create a new mock implementation of a class or function for each test run and means that concurrent tests are not polluted by the state of previous tests.

1import { proxyModule, registerMock, reset } from '@morgan-stanley/ts-mocking-bird';
2
3import * as originalModule from "modulePath";
4
5const proxiedModule = proxyModule(originalModule);
6
7describe("my-system-under-test", () => {
8
9    mockImports(originalModule, proxiedModule);
10
11    beforeEach(() => {
12        const mockedClass = Mock.create<ClassToMock>();
13
14        registerMock(proxiedModule, {ClassToMock: mockedClass})
15    });
16
17    afterEach(() => {
18        reset(proxiedModule);
19    })
20
21});

Using proxyJestModule we register our proxied module with jest.

1import * as moduleProxy from "../../relative-import-path";
2
3jest.mock('../../relative-import-path', () =>
4    require('@morgan-stanley/ts-mocking-bird').proxyJestModule(
5        require.resolve('../../relative-import-path'),
6    ),
7);
8
9describe("my-system-under-test", () => {
10
11    beforeEach(() => {
12        const mockedClass = Mock.create<ClassToMock>();
13
14        registerMock(moduleProxy, {ClassToMock: mockedClass})
15    });
16
17    afterEach(() => {
18        reset(proxiedModule);
19    })
20
21});

This works in a node environment (replaceProperties does not due to the way require works) and is a more reliable way of mocking imports as jest hoists this mocking code above all other imports so it is guaranteed to run before the members of the module are imported into the system under test. For this to work the following must be observed:

• As the jest.mock function is hoisted it can't refer to any variables outside the function. This is why require('@morgan-stanley/ts-mocking-bird') is used rather than using an existing import. The import path for the module must also be specified multiple times rather than using a variable for the same reason.
• The path passed to jest.mock, passed to proxyJestModule and used to import the moduleProxy must all point to same location. For example if a barrel is being imported then all 3 paths must point to same barrel.
• the path passed to proxyJestModule must either be an ambient import such as fs or path, a non relative import such as @morgan-stanley/my-dependency-name or it must be an absolute path. If a relative path such as ../../main/myImport is used this path will not be resolvable from the proxyJestModule function. To get the absolute path use require.resolve('../../relative-import-path')

Replace an imported function with a mocked function once at the start of your test

1import * as myImport from './exampleImports';
2
3describe('replace imports', () => {
4    const someFunctionMock = () => 'mockedReturnValue';
5
6    replaceProperties(myImport, { someFunction: someFunctionMock });
7
8    it('should replace function import', () => {
9        const SUT = new ClassUsingImports('one', 2);
10
11        expect(SUT.someFunctionCallingMockedImport()).toEqual('mockedReturnValue'); // value comes from mock above, not original import
12    });
13});

Replace an imported function and a class and generate a new mock before each test run

1import * as myImport from './exampleImports';
2
3describe('replace imports', () => {
4
5    describe('create new mock before each test', () => {
6        let mockService: IMocked<IMyService>;
7        let mockPackage: IMocked<typeof myImport>;
8
9        replacePropertiesBeforeEach(() => {
10            mockService = Mock.create<IMyService>();
11            mockPackage = Mock.create<typeof myImport>().setup(setupFunction('someFunction')); // recreate mocks for each test run to reset call counts
12
13            return [{ package: myImport, mocks: { ...mockPackage.mock, MyService: mockService.mockConstructor } }];
14        });
15
16        it('so that we can assert number of calls', () => {
17            const SUT = new ClassUsingImports('one', 2);
18
19            expect(SUT.service).toBe(mockService.mock);
20            expect(mockPackage.withFunction('someFunction')).wasNotCalled();
21
22            SUT.someFunctionProxy();
23            expect(mockPackage.withFunction('someFunction')).wasCalledOnce();
24        });
25    });
26});

Vitest

This package has been tested with and can be used with vitest. In some scenarios it needs to be used in a slightly different way. THis is because by default vitest does not use global functions such as beforeEach, expect and so on.

• if addMatchers() is called in a test setup file for example and vitest is running in a non global mode then the expect function must be passed to addMatchers:

1import { expect } from "vitest";
2import { addMatchers } from "@morgan-stanley/ts-mocking-bird";
3
4addMatchers(expect);

• if using replaceProperties or replacePropertiesBeforeEach the beforeEach, afterEach, beforeAll and afterAll functions must be passed in when vitest is not running in global mode:

1import { beforeAll, afterAll, beforeEach, afterEach} from "vitest";
2import { replaceProperties, replacePropertiesBeforeEach } from "@morgan-stanley/ts-mocking-bird";
3
4replaceProperties(targetObject, mockedProperties, { beforeAll, afterAll });
5replacePropertiesBeforeEach(() => {
6    mockService = Mock.create<IMyService>();
7    mockPackage = Mock.create<typeof myImport>().setup(setupFunction('someFunction'));
8
9    return [{ package: myImport, mocks: { ...mockPackage.mock, MyService: mockService.mockConstructor } }];
10
11}, { beforeEach, afterEach });
12

Webpack 4 issues

If you get an error such as

TypeError: Cannot redefine property: BUILD_ID

This is most likely because webpack 4 uses configurable:false when defining properties on import objects. This means that we are unable to replace them when we want to mock them.

This situation is handled by this mocking library but for it to be fully effective the mocking library needs to be imported before any other code - in other words before webpack has a chance to create any import objects.

To do this simply import this library before you import your tests or any other code.

For example:

1import "@morgan-stanley/ts-mocking-bird"; // monkey patch Object.defineProperty before any other code runs
2
3// Find all the tests.
4const context = (require as any).context('./', true, /.spec.ts$/);
5// And load the modules.
6context.keys().map(context);