useCalledWith (JavaScript)

Language JavaScript (and super languages)

Summary

Rule available since: v2.6.8
Diagnostic Category: lint/nursery/useCalledWith
This rule doesn’t have a fix.
The default severity of this rule is information.
This rule belongs to the following domains:
- test
Sources:
- Same as jest/prefer-called-with
- Same as vitest/prefer-called-with

How to configure

1
{
2
  "linter": {
3
    "rules": {
4
      "nursery": {
5
        "useCalledWith": "error"
6
      }
7
    }
8
  }
9
}

Description

Enforce using toHaveBeenCalledWith() to check the arguments of a function call.

toHaveBeenCalled() and its alias toBeCalled() only check that a mock function (a fake function that records how it is called) was called at least once. The test still passes when the function receives the wrong arguments. toHaveBeenCalledWith() also checks the arguments, so the test catches more mistakes.

When the value of an argument is hard to predict, pass a placeholder such as expect.anything() or expect.any(Date). The test then still checks the number and the position of the arguments. When the function is expected to be called without arguments, use toHaveBeenCalledWith() without arguments.

This rule also reports toHaveBeenCalledOnce() from Vitest, which has toHaveBeenCalledExactlyOnceWith() as the equivalent that checks the arguments.

Assertions that use .not are ignored. For example, expect(sendEmail).not.toHaveBeenCalled() checks that the function was never called, so there are no arguments to check.

Examples

Invalid

1
expect(sendEmail).toHaveBeenCalled();

code-block.js:1:19 lint/nursery/useCalledWith ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ toHaveBeenCalled() doesn't check the arguments that the function was called with.
  
  > 1 │ expect(sendEmail).toHaveBeenCalled();
      │                   ^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ The test passes even when the function receives the wrong arguments.
  
  ℹ Use toHaveBeenCalledWith() and pass the expected arguments. For an argument that is hard to predict, pass expect.anything().
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.

1
expect(sendEmail).toBeCalled();

code-block.js:1:19 lint/nursery/useCalledWith ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ toBeCalled() doesn't check the arguments that the function was called with.
  
  > 1 │ expect(sendEmail).toBeCalled();
      │                   ^^^^^^^^^^
    2 │ 
  
  ℹ The test passes even when the function receives the wrong arguments.
  
  ℹ Use toBeCalledWith() and pass the expected arguments. For an argument that is hard to predict, pass expect.anything().
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.

1
expect(sendEmail).toHaveBeenCalledOnce();

code-block.js:1:19 lint/nursery/useCalledWith ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ toHaveBeenCalledOnce() doesn't check the arguments that the function was called with.
  
  > 1 │ expect(sendEmail).toHaveBeenCalledOnce();
      │                   ^^^^^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ The test passes even when the function receives the wrong arguments.
  
  ℹ Use toHaveBeenCalledExactlyOnceWith() and pass the expected arguments. For an argument that is hard to predict, pass expect.anything().
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.

Valid

1
expect(sendEmail).toHaveBeenCalledWith("user@example.com", expect.anything());
2
expect(sendEmail).toHaveBeenCalledExactlyOnceWith("user@example.com");
3
expect(refresh).toHaveBeenCalledWith();
4
expect(sendEmail).toHaveBeenCalledTimes(1);
5
expect(sendEmail).not.toHaveBeenCalled();