Replace ts-mockito with jest-mock-extended

[esuca]

In almost all of the projects that we use archimedes-js we also use ts-mockito for mocking commands, queries, etc.
A few months ago I discovered and used in a few projects jest-mock-extended library, which provides type-safe mocking extensions for Jest, allowing us to use the Jest APIs for all of our mocks.
jest-mock-extended is downloaded almost 160.000 times per week and has a more active development than ts-mockito.

Today I had a conversation with @cesalberca about replacing ts-mockito with jest-mock-extended in new projects and he suggested creating a new discussion here for all.

Code example:

class FirstQry {
  constructor() {
  }

  execute(param: { foo: boolean }) {
    return param.foo ? 'isFoo' : 'notFoo'
  }
}

class SecondQry {
  constructor(private firstQry: FirstQry) {
  }

  execute(foo: boolean) {
    return this.firstQry.execute({ foo })
  }
}

test('mocking example with ts-mockito', () => {
  const firstQryMock = mock(FirstQry)
  const secondQry = new SecondQry(instance(firstQryMock))

  when(firstQryMock.execute(deepEqual({ foo: false }))).thenReturn('mocked')

  const result = secondQry.execute(false)
  expect(result).toBe('mocked')

  verify(firstQryMock.execute(deepEqual({ foo: false }))).once()
})

test('1. mocking example with jest-mock-extended following its documentation example', () => {
  const firstQryMock = mock<FirstQry>()
  const secondQry = new SecondQry(firstQryMock)
  // @ts-expect-error mockReturnValue or mockReturnValueOnce expect the return value to be 'isFoo' or 'notFoo'
  // firstQryMock.execute.mockReturnValueOnce('mocked')
  firstQryMock.execute.mockReturnValue('mocked')

  const result = secondQry.execute(false)
  expect(result).toBe('mocked')
  expect(firstQryMock.execute).toHaveBeenCalledTimes(1)
  expect(firstQryMock.execute).toHaveBeenCalledWith({ foo: false })
})

test('2. mocking example with jest-mock-extended using calledWith to match an object argument', () => {
  const firstQryMock = mock<FirstQry>()
  const secondQry = new SecondQry(firstQryMock)
  // @ts-expect-error mockReturnValue expect the return value to be 'isFoo' or 'notFoo'
  firstQryMock.execute.calledWith(myDeepEqual({ foo: false })).mockReturnValue('mocked')

  const result = secondQry.execute(false)
  expect(result).toBe('mocked')
  expect(firstQryMock.execute).toHaveBeenCalledTimes(1)
  expect(firstQryMock.execute).toHaveBeenCalledWith({ foo: false })
})

export const myDeepEqual: <T>(expectedValue: T) => Matcher<T> = expectedValue =>
  new Matcher(actualValue => JSON.stringify(actualValue) === JSON.stringify(expectedValue))

Advantages of jest-mock-extended over ts-mockito:

1. Provides a familiar Jest like API. We don't need to learn another library.
2. With ts-mockito we need to wrap our mock with the instance() method to make it work. Sometimes we forget to wrap it and ts-mockito does not warn us about it. With jest-mock-extended there is no need for a wrapper, we can pass directly the mock.
3. ts-mockito verify error message does not include the actual calls with the arguments, it only provides us basic error message with the expected times call and the actually called times, making debugging harder.
4. Supports mocking interfaces, functions, deep objects, and class instances.
5. Provides complete Typescript type safety for interfaces, argument types, and return types.

Disadvantages of jest-mock-extended over ts-mockito:

1. By default ts-mockito is matching the arguments by reference, and when we want to match for arguments equality, deepEqual() method is used. ts-mockito's deepEqual is not documented yet.
   Most of the time with jest-mock-extended expecting an argument matching is not necessary, because we can mock directly the function call and later assert that was called correctly as shown on the first jest-mock-extended test. But if we need it, the behaviour of jest-mock-extended is the same as ts-mockito and we could use any of the available jest matchers, like, containsValue('value') or create our own deepEqual method as I did on the second jest-mock-extended test.
2. jest-mock-extended uses the Jest assertion API and there is no toHaveBeenCalledWithOnce() assertion method that combines the
   toHaveBeenCalledTimes(n) and toHaveBeenCalledWith(value) into one single assertion... There is something similar, but not as semantic: expect(firstQryMock.execute).toHaveBeenNthCalledWith(1, { foo: false }). We could wrap it with our own assertion to give it a better naming.

These disadvantages are more limitations of the Jest API than of the library itself... And all of them have an easy workaround.

After using it in a few projects, I noticed that the tests code is cleaner and the debugging is easier because of better assertions error messages and the IDEs integration with the Jest APIs.

What do you think about using jest-mock-extended in new projects?

[cesalberca]

Thank you for such detailed explanation. Seeing that jest-mock-extended can provide more advantages we'll try and change from ts-mockito to these new API and see how it goes. Thanks again!

[cesalberca]

Closed with #6