oxc-project/oxc · warning

Require test cases and hooks to be inside a `describe` block

Error message

Require test cases and hooks to be inside a `describe` block

What it means

Warning from the oxlint `jest/require-top-level-describe` rule (source: crates/oxc_linter/src/rules/shared/jest_vitest/require_top_level_describe.rs:19, function `too_many_describes`). It fires when the number of top-level `describe` blocks exceeds the configured maximum; the diagnostic help text interpolates the max and a pluralization suffix ('' or 's').

Source

Thrown at crates/oxc_linter/src/rules/shared/jest_vitest/require_top_level_describe.rs:19

use oxc_ast::AstKind;
use oxc_diagnostics::OxcDiagnostic;
use oxc_semantic::ScopeId;
use oxc_span::Span;
use rustc_hash::FxHashMap;
use schemars::JsonSchema;
use serde::Deserialize;

use crate::{
    context::LintContext,
    rule::DefaultRuleConfig,
    utils::{
        JestFnKind, JestGeneralFnKind, ParsedGeneralJestFnCall, ParsedJestFnCallNew,
        PossibleJestNode, collect_possible_jest_call_node, parse_jest_fn_call,
    },
};

fn too_many_describes(max: u32, repeat: &str, span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Require test cases and hooks to be inside a `describe` block")
        .with_help(format!(
            "There should not be more than {max:?} describe{repeat} at the top level."
        ))
        .with_label(span)
}

fn unexpected_test_case(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Require test cases and hooks to be inside a `describe` block")
        .with_help("All test cases must be wrapped in a describe block.")
        .with_label(span)
}

fn unexpected_hook(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Require test cases and hooks to be inside a `describe` block")
        .with_help("All hooks must be wrapped in a describe block.")
        .with_label(span)
}

View on GitHub (pinned to e1e7af627c)

Solutions

1. Consolidate the top-level describes into one: keep a single `describe('module', ...)` and nest the others inside it.
2. If multiple top-level suites are intentional, raise the rule's `max` option in `.oxlintrc.json` (e.g. `"jest/require-top-level-describe": ["warn", { "max": 2 }]`).
3. Suppress the file with `/* oxlint-disable jest/require-top-level-describe */` when the layout is deliberate.

Example fix

// before (two top-level describes, max 1)
describe('parser', () => { /* ... */ });
describe('printer', () => { /* ... */ });

// after (single top-level describe)
describe('compiler', () => {
  describe('parser', () => { /* ... */ });
  describe('printer', () => { /* ... */ });
});

// awk/grep heuristic: count top-level describe calls per file
// rg -n "^describe\(" tests/foo.spec.ts

When it happens

Trigger: A file with more than the configured `max` top-level `describe()` calls (e.g. two sibling describes when max is 1). Nested describes do not count - only ones at the top level of the module.

Common situations: Appending a second describe for a new feature instead of nesting it inside the existing one; refactors that split test groups; enabling the rule after files already accumulated multiple top-level suites.

Related errors

• Enforces a maximum depth to nested describe calls.
• Describe block title is used multiple times in the same desc
• Suggest using `test.todo`.
• Require setup and teardown code to be within a hook.
• Describe requires name and callback arguments

AI-assisted analysis of oxc-project/oxc@e1e7af627c (2026-08-20). Data as JSON: /api/errors/47fd98b4fa22cf27. Report an issue: GitHub.