ESLint Plugin for Jest-When Best Practices

This ESLint plugin provides rules to help you use the jest-when library effectively and follow recommended patterns.

be careful. This is not best example of code generated by AI on request of someone inexperinced in JS/TS dev.

Installation

You'll first need to install ESLint and jest-when:

npm install eslint jest-when --save-dev

Next, install the plugin:

npm install eslint-plugin-jest-when --save-dev # Replace with the actual package name

Usage

Add eslint-plugin-jest-when to the plugins section of your .eslintrc configuration file. You can then configure the rules you want to use under the rules section.

{
    "plugins": [
        "eslint-plugin-jest-when"
    ],
    "rules": {
        "your-plugin-name/no-reset-when-mocks-at-end": "warn",
        "your-plugin-name/no-reset-when-mocks-in-after-each": "warn",
        "your-plugin-name/prefer-jest-when-with-debug": "off", // Or "warn" to enable with debug suggestion
        "your-plugin-name/prefer-jest-when": "warn", // Use this OR prefer-jest-when-with-debug
        "your-plugin-name/prefer-once-mock-methods": "warn",
        "your-plugin-name/verify-when-mocks-in-after-each": "error"
    }
}

Note: You should typically enable either prefer-jest-when or prefer-jest-when-with-debug, but not both. prefer-jest-when-with-debug includes an extra debug logging suggestion when applying the fix.

Supported Rules

no-reset-when-mocks-at-end

Discourages using resetAllWhenMocks() at the end of it or test blocks. It is recommended to use verifyAllWhenMocksCalled() in an afterEach block instead for ensuring all mocks were called and resetAllWhenMocks() at the beginning of a test case if needed.

Incorrect:

it('should do something', () => {
  // ... test logic ...
  resetAllWhenMocks();
});

Recommended:

afterEach(() => {
  verifyAllWhenMocksCalled();
});

it('should do something', () => {
  resetAllWhenMocks(); // If needed at the start
  // ... test logic ...
  // No resetAllWhenMocks here
});

no-reset-when-mocks-in-after-each

Discourages using resetAllWhenMocks() within an afterEach block. resetAllWhenMocks() should ideally be used at the beginning of individual test cases if necessary, while verifyAllWhenMocksCalled() is recommended for afterEach.

Incorrect:

afterEach(() => {
  resetAllWhenMocks();
  verifyAllWhenMocksCalled();
});

Recommended:

afterEach(() => {
  verifyAllWhenMocksCalled();
});

it('should do something', () => {
  resetAllWhenMocks(); // Use at the start of the test if required
  // ...
});

prefer-jest-when

Suggests using the jest-when library for mocking methods like mockReturnValue, mockResolvedValue, etc.

Incorrect:

myMock.mockReturnValue(1);

Recommended:

import { when } from 'jest-when';

when(myMock).calledWith(...).mockReturnValue(1); // Add specific arguments to calledWith

prefer-jest-when-with-debug

Similar to prefer-jest-when, this rule also suggests using jest-when but includes a debug helper (when.allArgs) in the suggested fix to make it easier to inspect the arguments a mock was called with. Disable prefer-jest-when if using this rule.

Incorrect:

myMock.mockReturnValue(1);

Recommended (with fix enabled):

import { when } from 'jest-when';

when(myMock).calledWith(when.allArgs((args) => {
  console.log(args); // <-- set breakpoint here to debug sent arguments
  return true;
})).mockReturnValue(1);

prefer-once-mock-methods

Encourages the use of *Once variants (e.g., mockReturnValueOnce) for mock methods when using jest-when, promoting better test isolation.

Incorrect:

import { when } from 'jest-when';

when(myMock).calledWith(1).mockReturnValue(1);

Recommended:

import { when } from 'jest-when';

when(myMock).calledWith(1).mockReturnValueOnce(1);

verify-when-mocks-in-after-each

Ensures that verifyAllWhenMocksCalled() is included in an afterEach block when jest-when is used in the test file. This helps confirm that all configured when mocks were called during the test.

Incorrect (when using jest-when but no verification):

import { when } from 'jest-when';

it('should use a mock', () => {
  when(someMock).calledWith(1).mockReturnValue(true);
  // ...
});

Recommended:

import { when, verifyAllWhenMocksCalled } from 'jest-when';

afterEach(() => {
  verifyAllWhenMocksCalled();
});

it('should use a mock', () => {
  when(someMock).calledWith(1).mockReturnValue(true);
  // ...
});

License

MIT