@hughescr/eslint-plugin-test-hygiene

ESLint rules for test-file hygiene: fake-timer cleanup, mock cleanup, no module mocks in test bodies, and mock-reset enforcement.

Compatible with ESLint v10+ and Node 20+. Works natively with Bun.

Installation

bun add -D @hughescr/eslint-plugin-test-hygiene eslint
# or
npm install --save-dev @hughescr/eslint-plugin-test-hygiene eslint

Usage

Flat config (recommended — ESLint v9+)

// eslint.config.mjs
import { defineConfig } from 'eslint';
import testHygiene from '@hughescr/eslint-plugin-test-hygiene';

export default defineConfig([
    // Spread the recommended config over your test files
    {
        files: ['tests/**/*.ts', '**/*.test.ts'],
        ...testHygiene.configs.recommended,
    },
]);

The recommended config enables all four rules at 'error' severity:

| Rule | Severity | |------|----------| | @hughescr/test-hygiene/no-mock-module-in-test-body | error | | @hughescr/test-hygiene/require-fake-timers-cleanup | error | | @hughescr/test-hygiene/require-mock-cleanup | error | | @hughescr/test-hygiene/require-mock-reset | error |

Configuring require-mock-reset

The require-mock-reset rule requires explicit configuration to know which mock identifiers to track:

// eslint.config.mjs
import { defineConfig } from 'eslint';
import testHygiene from '@hughescr/eslint-plugin-test-hygiene';

export default defineConfig([
    {
        files: ['tests/**/*.ts'],
        plugins: { '@hughescr/test-hygiene': testHygiene },
        rules: {
            // spread other recommended rules, then override require-mock-reset
            ...testHygiene.configs.recommended.rules,
            '@hughescr/test-hygiene/require-mock-reset': ['error', {
                mocks: {
                    mockFsPromises:  ['resetMockFs', 'resetMockFsPrefix'],
                    mockSstResource: ['resetMockSstResource'],
                },
                setupModules: ['setup'],  // matches ./setup, ../setup, path/to/setup
            }],
        },
    },
]);

Rules

| Rule | Description | Docs | |------|-------------|------| | no-mock-module-in-test-body | Disallow mock.module() outside designated setup files | docs | | require-fake-timers-cleanup | Require jest.useRealTimers() when jest.useFakeTimers() is used in a hook or test | docs | | require-mock-cleanup | Require jest.restoreAllMocks() or mockRestore() when jest.spyOn() is used | docs | | require-mock-reset | Require configured reset helpers for mocks imported from setup modules | docs |

License

BSD-3-Clause. See LICENSE.md.