oxc-project/oxc · warning · OxcDiagnostic

Enforces a maximum depth to nested describe calls.

Error message

Enforces a maximum depth to nested describe calls.

What it means

Diagnostic from the oxlint rule `jest/max-nested-describe` (shared with `vitest/max-nested-describe`) in crates/oxc_linter/src/rules/shared/jest_vitest/max_nested_describe.rs:16. It fires when `describe()` blocks are nested deeper than the configured `maxDepth` (default 5). Deeply nested suites hurt readability, so the linter labels the offending `describe` span and reports the current depth versus the maximum in the help text.

Source

Thrown at crates/oxc_linter/src/rules/shared/jest_vitest/max_nested_describe.rs:16

use schemars::JsonSchema;
use serde::Deserialize;

use oxc_ast::AstKind;
use oxc_diagnostics::OxcDiagnostic;
use oxc_span::Span;

use crate::{
    context::LintContext,
    utils::{
        JestFnKind, JestGeneralFnKind, collect_possible_jest_call_node, is_type_of_jest_fn_call,
    },
};

fn exceeded_max_depth(current: u32, max: u32, span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Enforces a maximum depth to nested describe calls.")
        .with_help(format!("Too many nested describe calls ({current}) - maximum allowed is {max}"))
        .with_label(span)
}

pub const DOCUMENTATION: &str = r#"### What it does

This rule enforces a maximum depth to nested `describe()` calls.

### Why is this bad?

Nesting `describe()` blocks too deeply can make the test suite hard to read and understand.

### Examples

The following patterns are considered warnings (with the default option of
`{ "max": 5 } `):

Examples of **incorrect** code for this rule:

View on GitHub (pinned to e1e7af627c)

Solutions

1. Flatten the suite: extract the deepest describe blocks into separate files, or merge levels that add no value
2. Raise the limit explicitly if deeper nesting is intentional: { "jest/max-nested-describe": ["error", { "maxDepth": 8 }] } in .oxlintrc.json
3. Suppress for one file with an oxlint-disable jest/max-nested-describe comment (or turn the rule off) when nesting is deliberate

Example fix

// before (6 levels)
describe('a', () => { describe('b', () => { describe('c', () => { describe('d', () => { describe('e', () => { describe('f', () => { it('works', fn); }); }); }); }); }); });

// after: split into files, keep depth <= 5
// file: a.b.c.d.spec.ts
describe('a b c d', () => { describe('e', () => { it('works', fn); }); });

npx oxlint -c .oxlintrc.json 'tests/**/*.spec.ts' # jest/max-nested-describe reports depth violations before CI

When it happens

Trigger: A test file nests more than maxDepth (default 5) `describe()` calls, e.g. describe inside describe six levels deep. The rule tracks describe depth while walking possible jest call nodes (collect_possible_jest_call_node) and emits exceeded_max_depth(current, max, span) on the describe call that crosses the limit.

Common situations: Suites that mirror a deep folder structure; teams migrating from Mocha where heavy nesting was conventional; generated tests; CI newly enabling the jest/vitest plugin categories in oxlint so the rule starts reporting on legacy files.

Related errors

• Describe block title is used multiple times in the same desc
• Disabled test suite
• Matchers must be called to assert.
• Expect has an unknown modifier.
• Async assertions must be awaited.

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