jest/require-top-level-describe

Require tests and hooks to be inside a describe block

A test at the top level of a file shows up in the output with no group name, so a failure says "starts empty" but not what starts empty. A hook at the top level runs for every test in the file, including the ones somebody adds later for something else. Inside a describe, it's clear what both belong to.

Configure#

Off by default. To turn it on:

bunfig.toml
[lint.rules]
"jest/require-top-level-describe" = "error" # or "warn"

Every option, set to its default. The ones that are commented out are unset by default.

bunfig.toml
[lint.rules]
"jest/require-top-level-describe" = ["error", {
  # maxNumberOfTopLevelDescribes = <value>,
}]

Examples#

example.js2 problems
import { beforeEach, expect, test } from "@jest/globals";

beforeEach(() => {
  cart.clear();
});

test("starts empty", () => {
  expect(cart.size).toBe(0);
});
example.jsNo problems
import { beforeEach, describe, expect, test } from "@jest/globals";

describe("cart", () => {
  beforeEach(() => {
    cart.clear();
  });

  test("starts empty", () => {
    expect(cart.size).toBe(0);
  });
});

Options#

OptionDefaultWhat it does
maxNumberOfTopLevelDescribesno limitHow many describe blocks a file can have at the top level. Each one after that is reported. Nested blocks don't count.
example.jswith { "maxNumberOfTopLevelDescribes": 1 }1 problem
import { describe, test } from "@jest/globals";

describe("cart", () => {
  test.todo("starts empty");
});

describe("checkout", () => {
  test.todo("charges the card");
});
example.jswith { "maxNumberOfTopLevelDescribes": 1 }No problems
import { describe, test } from "@jest/globals";

describe("shop", () => {
  describe("cart", () => {
    test.todo("starts empty");
  });

  describe("checkout", () => {
    test.todo("charges the card");
  });
});