require-hook.md

Require setup and teardown code to be within a hook (require-hook)

Often while writing tests you have some setup work that needs to happen before tests run, and you have some finishing work that needs to happen after tests run. Jest provides helper functions to handle this.

It's common when writing tests to need to perform setup work that needs to happen before tests run, and finishing work after tests run.

Because Jest executes all describe handlers in a test file before it executes any of the actual tests, it's important to ensure setup and teardown work is done inside before* and after* handlers respectively, rather than inside the describe blocks.

Rule details

This rule flags any expression that is either at the toplevel of a test file or directly within the body of a describe, except for the following:

• import statements
• const variables
• let declarations, and initializations to null or undefined
• Classes
• Types
• Calls to the standard Jest globals

This rule flags any function calls within test files that are directly within the body of a describe, and suggests wrapping them in one of the four lifecycle hooks.

Here is a slightly contrived test file showcasing some common cases that would be flagged:

import { database, isCity } from '../database';
import { Logger } from '../../../src/Logger';
import { loadCities } from '../api';

jest.mock('../api');

const initializeCityDatabase = () => {
  database.addCity('Vienna');
  database.addCity('San Juan');
  database.addCity('Wellington');
};

const clearCityDatabase = () => {
  database.clear();
};

initializeCityDatabase();

test('that persists cities', () => {
  expect(database.cities.length).toHaveLength(3);
});

test('city database has Vienna', () => {
  expect(isCity('Vienna')).toBeTruthy();
});

test('city database has San Juan', () => {
  expect(isCity('San Juan')).toBeTruthy();
});

describe('when loading cities from the api', () => {
  let consoleWarnSpy = jest.spyOn(console, 'warn');

  loadCities.mockResolvedValue(['Wellington', 'London']);

  it('does not duplicate cities', async () => {
    await database.loadCities();

    expect(database.cities).toHaveLength(4);
  });

  it('logs any duplicates', async () => {
    await database.loadCities();

    expect(consoleWarnSpy).toHaveBeenCalledWith(
      'Ignored duplicate cities: Wellington',
    );
  });
});

clearCityDatabase();

Here is the same slightly contrived test file showcasing the same common cases but in ways that would be not flagged:

import { database, isCity } from '../database';
import { Logger } from '../../../src/Logger';
import { loadCities } from '../api';

jest.mock('../api');

const initializeCityDatabase = () => {
  database.addCity('Vienna');
  database.addCity('San Juan');
  database.addCity('Wellington');
};

const clearCityDatabase = () => {
  database.clear();
};

beforeEach(() => {
  initializeCityDatabase();
});

test('that persists cities', () => {
  expect(database.cities.length).toHaveLength(3);
});

test('city database has Vienna', () => {
  expect(isCity('Vienna')).toBeTruthy();
});

test('city database has San Juan', () => {
  expect(isCity('San Juan')).toBeTruthy();
});

describe('when loading cities from the api', () => {
  let consoleWarnSpy;

  beforeEach(() => {
    consoleWarnSpy = jest.spyOn(console, 'warn');
    loadCities.mockResolvedValue(['Wellington', 'London']);
  });

  it('does not duplicate cities', async () => {
    await database.loadCities();

    expect(database.cities).toHaveLength(4);
  });

  it('logs any duplicates', async () => {
    await database.loadCities();

    expect(consoleWarnSpy).toHaveBeenCalledWith(
      'Ignored duplicate cities: Wellington',
    );
  });
});

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

Options

Some test utils provides methods which takes hook as an argument and should be executed outside a hook.

For example https://vue-test-utils.vuejs.org/api/#enableautodestroy-hook which takes the hook as an argument. To exclude them you can update settings

{
  "jest/require-hook": [
    "error",
    {
      "excludedFunctions": [
        "enableAutoDestroy"
      ]
    }
  ]
}

For additional control you might need to reduce possible hooks which can be passed as an argument (by default it is beforeAll, beforeEach, afterAll, afterEach)

{
  "jest/require-hook": [
    "error",
    {
      "excludedFunctions": [
        "enableAutoDestroy"
      ],
      "allowedHooks": ["beforeEach"]
    }
  ]
}

Examples of incorrect code for the { "excludedFunctions": ["expect"], "allowedHooks": ["beforeEach"] } option:

/* eslint jest/require-hook: ["error", { "excludedFunctions": ["expect"], "allowedHooks": ["beforeEach"] }] */

import {
  enableAutoDestroy,
  resetAutoDestroyState,
  mount
} from '@vue/test-utils';
import initDatabase from './initDatabase';

enableAutoDestroy(afterEach);
afterAll(resetAutoDestroyState); // this will throw a linting error
initDatabase(); // this will too

describe('Foo', () => {
  test('always returns 42', () => {
    expect(global.getAnswer()).toBe(42);
  })
})

Examples of correct code for the { "excludedFunctions": ["expect"], "allowedHooks": ["beforeEach", "afterAll"] } option:

/* eslint jest/require-hook: ["error", { "excludedFunctions": ["expect"], "allowedHooks": ["beforeEach", "afterAll"] }] */

import {
  enableAutoDestroy,
  resetAutoDestroyState,
  mount
} from '@vue/test-utils';
import {initDatabase, tearDownDatabase} from './databaseUtils';

enableAutoDestroy(afterEach);
afterAll(resetAutoDestroyState);

beforeEach(initDatabase);
afterEach(tearDownDatabase);

describe('Foo', () => {
  test('always returns 42', () => {
    expect(global.getAnswer()).toBe(42);
  });
});