oxc-project/oxc · error

Unexpected return statement in describe callback

Error message

Unexpected return statement in describe callback

What it means

Diagnostic from the oxlint `jest/valid-describe-callback` rule (source: crates/oxc_linter/src/rules/shared/jest_vitest/valid_describe_callback.rs:18). This variant ('Unexpected return statement in describe callback') fires when the describe callback contains a `return` statement. Returning from describe does nothing meaningful and usually signals copy-pasted factory logic; jest similarly rejects it.

Source

Thrown at crates/oxc_linter/src/rules/shared/jest_vitest/valid_describe_callback.rs:18

use oxc_ast::{
    AstKind,
    ast::{Argument, Expression, FunctionBody, Statement},
};
use oxc_diagnostics::OxcDiagnostic;
use oxc_span::{GetSpan, Span};

use crate::{
    context::LintContext,
    utils::{JestFnKind, JestGeneralFnKind, PossibleJestNode, parse_general_jest_fn_call},
};

fn valid_describe_callback_diagnostic(
    x1: &'static str,
    x2: &'static str,
    span3: Span,
) -> OxcDiagnostic {
    OxcDiagnostic::warn(x1).with_help(x2).with_label(span3)
}

#[derive(Clone, Copy)]
pub struct ValidDescribeCallbackOptions {
    allow_async_describe_callback: bool,
    allow_describe_options_argument: bool,
}

impl ValidDescribeCallbackOptions {
    pub const JEST: Self =
        Self { allow_async_describe_callback: false, allow_describe_options_argument: false };

    pub const VITEST: Self =
        Self { allow_async_describe_callback: true, allow_describe_options_argument: true };
}

pub fn run<'a>(
    possible_jest_node: &PossibleJestNode<'a, '_>,

View on GitHub (pinned to e1e7af627c)

Solutions

1. Remove the `return`; call the builder directly: `describe('feature', () => { buildTests(); })`.
2. If the return value was data for tests, assign it to a `const` inside the describe or compute it in `beforeAll`.
3. Keep the return inside the inner `test` callbacks, where returning from a test is allowed.

Example fix

// before
describe('routes', () => {
  return registerRouteTests();
});

// after
describe('routes', () => {
  registerRouteTests();
});

// rg -nU "describe\([\s\S]{0,200}?\breturn\b" tests/ -t ts -t js

When it happens

Trigger: `describe('feature', () => { return buildTests(); })` - any `return` statement in the describe callback body, found by walking the callback function for ReturnStatement nodes (source imports GetSpan for reporting the span).

Common situations: Converting a helper that builds tests via `return` into a describe body; early-exit logic copied from a test; generated test code that returns config objects.

Related errors

• Enforces a maximum depth to nested describe calls.
• Describe block title is used multiple times in the same desc
• Require test cases and hooks to be inside a `describe` block
• Describe requires name and callback arguments
• Second argument must be a function

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