feat(expect): add toHaveBeenCalledAfter and toHaveBeenCalledBefore utility (#6056)

Co-authored-by: Vladimir Sheremet <sleuths.slews0s@icloud.com>

Author: Barbapapazes

docs/api/expect.md

@@ -876,6 +876,44 @@ test('spy function', () => {
 })
 ```
 
+## toHaveBeenCalledBefore <Version>2.2.0</Version> {#tohavebeencalledbefore}
+
+- **Type**: `(mock: MockInstance, failIfNoFirstInvocation?: boolean) => Awaitable<void>`
+
+This assertion checks if a `Mock` was called before another `Mock`.
+
+```ts
+test('calls mock1 before mock2', () => {
+  const mock1 = vi.fn()
+  const mock2 = vi.fn()
+
+  mock1()
+  mock2()
+  mock1()
+
+  expect(mock1).toHaveBeenCalledBefore(mock2)
+})
+```
+
+## toHaveBeenCalledAfter <Version>2.2.0</Version> {#tohavebeencalledafter}
+
+- **Type**: `(mock: MockInstance, failIfNoFirstInvocation?: boolean) => Awaitable<void>`
+
+This assertion checks if a `Mock` was called after another `Mock`.
+
+```ts
+test('calls mock1 after mock2', () => {
+  const mock1 = vi.fn()
+  const mock2 = vi.fn()
+
+  mock2()
+  mock1()
+  mock2()
+
+  expect(mock1).toHaveBeenCalledAfter(mock2)
+})
+```
+
 ## toHaveBeenCalledExactlyOnceWith <Version>2.2.0</Version> {#tohavebeencalledexactlyoncewith}
 
 - **Type**: `(...args: any[]) => Awaitable<void>`

packages/expect/src/jest-expect.ts

@@ -656,6 +656,74 @@ export const JestChaiExpect: ChaiPlugin = (chai, utils) => {
       )
     },
   )
+
+  /**
+   * Used for `toHaveBeenCalledBefore` and `toHaveBeenCalledAfter` to determine if the expected spy was called before the result spy.
+   */
+  function isSpyCalledBeforeAnotherSpy(beforeSpy: MockInstance, afterSpy: MockInstance, failIfNoFirstInvocation: number): boolean {
+    const beforeInvocationCallOrder = beforeSpy.mock.invocationCallOrder
+
+    const afterInvocationCallOrder = afterSpy.mock.invocationCallOrder
+
+    if (beforeInvocationCallOrder.length === 0) {
+      return !failIfNoFirstInvocation
+    }
+
+    if (afterInvocationCallOrder.length === 0) {
+      return false
+    }
+
+    return beforeInvocationCallOrder[0] < afterInvocationCallOrder[0]
+  }
+
+  def(
+    ['toHaveBeenCalledBefore'],
+    function (resultSpy: MockInstance, failIfNoFirstInvocation = true) {
+      const expectSpy = getSpy(this)
+
+      if (!isMockFunction(resultSpy)) {
+        throw new TypeError(
+          `${utils.inspect(resultSpy)} is not a spy or a call to a spy`,
+        )
+      }
+
+      this.assert(
+        isSpyCalledBeforeAnotherSpy(
+          expectSpy,
+          resultSpy,
+          failIfNoFirstInvocation,
+        ),
+        `expected "${expectSpy.getMockName()}" to have been called before "${resultSpy.getMockName()}"`,
+        `expected "${expectSpy.getMockName()}" to not have been called before "${resultSpy.getMockName()}"`,
+        resultSpy,
+        expectSpy,
+      )
+    },
+  )
+  def(
+    ['toHaveBeenCalledAfter'],
+    function (resultSpy: MockInstance, failIfNoFirstInvocation = true) {
+      const expectSpy = getSpy(this)
+
+      if (!isMockFunction(resultSpy)) {
+        throw new TypeError(
+          `${utils.inspect(resultSpy)} is not a spy or a call to a spy`,
+        )
+      }
+
+      this.assert(
+        isSpyCalledBeforeAnotherSpy(
+          resultSpy,
+          expectSpy,
+          failIfNoFirstInvocation,
+        ),
+        `expected "${expectSpy.getMockName()}" to have been called after "${resultSpy.getMockName()}"`,
+        `expected "${expectSpy.getMockName()}" to not have been called after "${resultSpy.getMockName()}"`,
+        resultSpy,
+        expectSpy,
+      )
+    },
+  )
   def(
     ['toThrow', 'toThrowError'],
     function (expected?: string | Constructable | RegExp | Error) {

packages/expect/src/types.ts

@@ -6,6 +6,7 @@
  *
  */
 
+import type { MockInstance } from '@vitest/spy'
 import type { Constructable } from '@vitest/utils'
 import type { Formatter } from 'tinyrainbow'
 import type { diff, getMatcherUtils, stringify } from './jest-matcher-utils'
@@ -655,6 +656,38 @@ export interface Assertion<T = any>
    */
   toSatisfy: <E>(matcher: (value: E) => boolean, message?: string) => void
 
+  /**
+   * This assertion checks if a `Mock` was called before another `Mock`.
+   * @param mock - A mock function created by `vi.spyOn` or `vi.fn`
+   * @param failIfNoFirstInvocation - Fail if the first mock was never called
+   * @example
+   * const mock1 = vi.fn()
+   * const mock2 = vi.fn()
+   *
+   * mock1()
+   * mock2()
+   * mock1()
+   *
+   * expect(mock1).toHaveBeenCalledBefore(mock2)
+   */
+  toHaveBeenCalledBefore: (mock: MockInstance, failIfNoFirstInvocation?: boolean) => void
+
+  /**
+   * This assertion checks if a `Mock` was called after another `Mock`.
+   * @param mock - A mock function created by `vi.spyOn` or `vi.fn`
+   * @param failIfNoFirstInvocation - Fail if the first mock was never called
+   * @example
+   * const mock1 = vi.fn()
+   * const mock2 = vi.fn()
+   *
+   * mock2()
+   * mock1()
+   * mock2()
+   *
+   * expect(mock1).toHaveBeenCalledAfter(mock2)
+   */
+  toHaveBeenCalledAfter: (mock: MockInstance, failIfNoFirstInvocation?: boolean) => void
+
   /**
    * Checks that a promise resolves successfully at least once.
    *

pnpm-lock.yaml

@@ -698,6 +698,158 @@ describe('toHaveBeenCalledExactlyOnceWith', () => {
   })
 })
 
+describe('toHaveBeenCalledBefore', () => {
+  it('success if expect mock is called before result mock', () => {
+    const expectMock = vi.fn()
+    const resultMock = vi.fn()
+
+    expectMock()
+    resultMock()
+
+    expect(expectMock).toHaveBeenCalledBefore(resultMock)
+  })
+
+  it('throws if expect is not a spy', () => {
+    expect(() => {
+      expect(1).toHaveBeenCalledBefore(vi.fn())
+    }).toThrow(/^1 is not a spy or a call to a spy/)
+  })
+
+  it('throws if result is not a spy', () => {
+    expect(() => {
+      expect(vi.fn()).toHaveBeenCalledBefore(1 as any)
+    }).toThrow(/^1 is not a spy or a call to a spy/)
+  })
+
+  it('throws if expect mock is called after result mock', () => {
+    const expectMock = vi.fn()
+    const resultMock = vi.fn()
+
+    resultMock()
+    expectMock()
+
+    expect(() => {
+      expect(expectMock).toHaveBeenCalledBefore(resultMock)
+    }).toThrow(/^expected "spy" to have been called before "spy"/)
+  })
+
+  it('throws with correct mock name if failed', () => {
+    const mock1 = vi.fn().mockName('mock1')
+    const mock2 = vi.fn().mockName('mock2')
+
+    mock2()
+    mock1()
+
+    expect(() => {
+      expect(mock1).toHaveBeenCalledBefore(mock2)
+    }).toThrow(/^expected "mock1" to have been called before "mock2"/)
+  })
+
+  it('fails if expect mock is not called', () => {
+    const resultMock = vi.fn()
+
+    resultMock()
+
+    expect(() => {
+      expect(vi.fn()).toHaveBeenCalledBefore(resultMock)
+    }).toThrow(/^expected "spy" to have been called before "spy"/)
+  })
+
+  it('not fails if expect mock is not called with option `failIfNoFirstInvocation` set to false', () => {
+    const resultMock = vi.fn()
+
+    resultMock()
+
+    expect(vi.fn()).toHaveBeenCalledBefore(resultMock, false)
+  })
+
+  it('fails if result mock is not called', () => {
+    const expectMock = vi.fn()
+
+    expectMock()
+
+    expect(() => {
+      expect(expectMock).toHaveBeenCalledBefore(vi.fn())
+    }).toThrow(/^expected "spy" to have been called before "spy"/)
+  })
+})
+
+describe('toHaveBeenCalledAfter', () => {
+  it('success if expect mock is called after result mock', () => {
+    const resultMock = vi.fn()
+    const expectMock = vi.fn()
+
+    resultMock()
+    expectMock()
+
+    expect(expectMock).toHaveBeenCalledAfter(resultMock)
+  })
+
+  it('throws if expect is not a spy', () => {
+    expect(() => {
+      expect(1).toHaveBeenCalledAfter(vi.fn())
+    }).toThrow(/^1 is not a spy or a call to a spy/)
+  })
+
+  it('throws if result is not a spy', () => {
+    expect(() => {
+      expect(vi.fn()).toHaveBeenCalledAfter(1 as any)
+    }).toThrow(/^1 is not a spy or a call to a spy/)
+  })
+
+  it('throws if expect mock is called before result mock', () => {
+    const resultMock = vi.fn()
+    const expectMock = vi.fn()
+
+    expectMock()
+    resultMock()
+
+    expect(() => {
+      expect(expectMock).toHaveBeenCalledAfter(resultMock)
+    }).toThrow(/^expected "spy" to have been called after "spy"/)
+  })
+
+  it('throws with correct mock name if failed', () => {
+    const mock1 = vi.fn().mockName('mock1')
+    const mock2 = vi.fn().mockName('mock2')
+
+    mock1()
+    mock2()
+
+    expect(() => {
+      expect(mock1).toHaveBeenCalledAfter(mock2)
+    }).toThrow(/^expected "mock1" to have been called after "mock2"/)
+  })
+
+  it('fails if result mock is not called', () => {
+    const expectMock = vi.fn()
+
+    expectMock()
+
+    expect(() => {
+      expect(expectMock).toHaveBeenCalledAfter(vi.fn())
+    }).toThrow(/^expected "spy" to have been called after "spy"/)
+  })
+
+  it('not fails if result mock is not called with option `failIfNoFirstInvocation` set to false', () => {
+    const expectMock = vi.fn()
+
+    expectMock()
+
+    expect(expectMock).toHaveBeenCalledAfter(vi.fn(), false)
+  })
+
+  it('fails if expect mock is not called', () => {
+    const resultMock = vi.fn()
+
+    resultMock()
+
+    expect(() => {
+      expect(vi.fn()).toHaveBeenCalledAfter(resultMock)
+    }).toThrow(/^expected "spy" to have been called after "spy"/)
+  })
+})
+
 describe('async expect', () => {
   it('resolves', async () => {
     await expect((async () => 'true')()).resolves.toBe('true')