oxc-project/oxc · warning

Prefer `await expect(...).resolves` over `expect(await ...)`

Error message

Prefer `await expect(...).resolves` over `expect(await ...)` syntax.

What it means

This is the oxlint `prefer-expect-resolves` rule (jest/vitest plugin). When you `await` inside the expect argument — `expect(await getUser())` — the promise settles before expect sees it, so a rejected promise throws an ordinary (unmatched, less descriptive) error and `.rejects` handling is impossible. The rule requires the `await expect(...).resolves` form where Jest itself awaits and reports the settled value.

Source

Thrown at crates/oxc_linter/src/rules/shared/jest_vitest/prefer_expect_resolves.rs:14

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

use crate::{
    context::LintContext,
    utils::{PossibleJestNode, parse_expect_jest_fn_call},
};

fn expect_resolves(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Prefer `await expect(...).resolves` over `expect(await ...)` syntax.")
        .with_help("Use `await expect(...).resolves` instead")
        .with_label(span)
}

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

Prefer `await expect(...).resolves` over `expect(await ...)` when testing
promises.

### Why is this bad?

When working with promises, there are two primary ways you can test the
resolved value:

1. use the `resolve` modifier on `expect`
(`await expect(...).resolves.<matcher>` style)
2. `await` the promise and assert against its result
(`expect(await ...).<matcher>` style)

View on GitHub (pinned to e1e7af627c)

Solutions

1. Move the await: `await expect(getUser()).resolves.toEqual(user)`.
2. For failure paths, use `await expect(getUser()).rejects.toThrow('not found')`.
3. Keep `expect(await x)` only if you deliberately want the throw to escape the matcher (rare; prefer not to).

Example fix

// before
it('gets user', async () => {
  expect(await getUser(1)).toEqual({ id: 1 });
});

// after
it('gets user', async () => {
  await expect(getUser(1)).resolves.toEqual({ id: 1 });
});

// .oxlintrc.json
{ "rules": { "jest/prefer-expect-resolves": "error" } }

npx oxlint tests/

When it happens

Trigger: An expect() call whose single Argument contains an `await` expression — `expect(await promise)` — typically followed by matchers like `.toBe`, `.toEqual`.

Common situations: Habitual `await` before passing to expect; refactoring async code where the await got pulled into the call; teams unaware of the `.resolves` matcher.

Related errors

• Unnecessary async function wrapper
• Jest tests should not return a value
• `expect` must be inside of a test block.
• Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()`
• Enforce using `each` rather than manual loops

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