できない.dev

Vitest「Promise returned by … was not awaited」の原因と直し方

Promise returned by … was not awaited は、Vitest 5 で await していない resolves や rejects があると出る。
expect に await を付けるか return すれば直る。

公開:

症状できない · exit 1
npx vitest run
…
 ❯ user.test.js (2 tests | 2 failed) 5ms
   × fetchUser 3ms
   × deleteUser 1ms
解決後できた · exit 0
npx vitest run
…
 Test Files  1 passed (1)
      Tests  2 passed (2)
   Start at  21:49:52
   Duration  91ms (transform 49%, import 26%, tests 13%, worker 11%)

2026-11-07 に node:24(Vitest 5.1.0 / Node.js 24.22.2) で実際に打って取った出力。検証環境の詳細

要約

Error: Promise returned by `expect(actual).resolves.toEqual(expected)` was not awaited. は、Vitest 5 で await していない resolves や rejects を書いたテストが落ちるときに出る。
rejects.toThrow なら expect(actual).rejects.toThrow(expected) のように、エラー文の中の書き方は使ったマッチャーに合わせて変わる。

4.1 は同じテストを警告だけで通し、テストの終わりに自動で待っていた。
5 は待たずにテストを落とす。
直し方は、テストの関数を async にして expect の前に await を付けるか、expect の戻り値を return することだ。

実行例

node:24 のコンテナで Vitest 5.1.0 を入れ、await していない resolves と rejects のテストを打つと、2 本とも落ちて終了コード 1 になった。
await と return に書き換えると通り、元のファイルは 4.1.12 では警告だけで通った。

$ cat user.test.js
import { expect, test } from "vitest";
 
const fetchUser = async (id) => ({ id, name: "sato" });
const deleteUser = async (id) => {
  throw new Error(`user ${id} not found`);
};
 
test("fetchUser", () => {
  expect(fetchUser(1)).resolves.toEqual({ id: 1, name: "sato" });
});
 
test("deleteUser", () => {
  expect(deleteUser(2)).rejects.toThrow("not found");
});
$ npx vitest run
 RUN  v5.1.0 /tmp/tmp.u6mfAY7EHh
 
 ❯ user.test.js (2 tests | 2 failed) 5ms
   × fetchUser 3ms
   × deleteUser 1ms
 
⎯⎯⎯⎯⎯⎯⎯ Failed Tests 2 ⎯⎯⎯⎯⎯⎯⎯
 
 FAIL  user.test.js > fetchUser
Error: Promise returned by `expect(actual).resolves.toEqual(expected)` was not awaited. This assertion is asynchronous and must be awaited; otherwise, it is not guaranteed to complete before the test finishes:
 
await expect(actual).resolves.toEqual(expected)
 
 ❯ user.test.js:9:23
      7|
      8| test("fetchUser", () => {
      9|   expect(fetchUser(1)).resolves.toEqual({ id: 1, name: "sato" });
       |                       ^
     10| });
     11|
 
⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[1/2]⎯
 
 FAIL  user.test.js > deleteUser
Error: Promise returned by `expect(actual).rejects.toThrow(expected)` was not awaited. This assertion is asynchronous and must be awaited; otherwise, it is not guaranteed to complete before the test finishes:
 
await expect(actual).rejects.toThrow(expected)
 
 ❯ user.test.js:13:24
     11|
     12| test("deleteUser", () => {
     13|   expect(deleteUser(2)).rejects.toThrow("not found");
       |                        ^
     14| });
     15|
 
⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[2/2]⎯
 
 Test Files  1 failed (1)
      Tests  2 failed (2)
   Start at  21:49:51
   Duration  108ms (transform 43%, import 27%, tests 20%, worker 10%)
$ echo $?
1
$ cat user.test.js
import { expect, test } from "vitest";
 
const fetchUser = async (id) => ({ id, name: "sato" });
const deleteUser = async (id) => {
  throw new Error(`user ${id} not found`);
};
 
test("fetchUser", async () => {
  await expect(fetchUser(1)).resolves.toEqual({ id: 1, name: "sato" });
});
 
test("deleteUser", () => {
  return expect(deleteUser(2)).rejects.toThrow("not found");
});
$ npx vitest run
 RUN  v5.1.0 /tmp/tmp.u6mfAY7EHh
 
 ✓ user.test.js (2 tests) 3ms
 
 Test Files  1 passed (1)
      Tests  2 passed (2)
   Start at  21:49:52
   Duration  91ms (transform 49%, import 26%, tests 13%, worker 11%)
$ echo $?
0
$ npx vitest --version
vitest/4.1.12 linux-x64 node-v24.22.2
$ npx vitest run
 RUN  v4.1.12 /opt/v4
 
stderr | user.test.js > fetchUser
Promise returned by `expect(actual).resolves.toEqual(expected)` was not awaited. Vitest currently auto-awaits hanging assertions at the end of the test, but this will cause the test to fail in the next Vitest major. Please remember to await the assertion.
    at /opt/v4/user.test.js:9:23
 
stderr | user.test.js > deleteUser
Promise returned by `expect(actual).rejects.toThrow(expected)` was not awaited. Vitest currently auto-awaits hanging assertions at the end of the test, but this will cause the test to fail in the next Vitest major. Please remember to await the assertion.
    at /opt/v4/user.test.js:13:24
 
 ✓ user.test.js (2 tests) 8ms
 
 Test Files  1 passed (1)
      Tests  2 passed (2)
   Start at  21:49:55
   Duration  131ms (transform 13ms, setup 0ms, import 26ms, tests 8ms, environment 0ms)
$ echo $?
0

— 2026-11-07 時点の出力

検証環境Node.js 24.22.2 / npm 11.19.1 / Python 3.11.2 / 2026-11-07 検証(ほか 2 件)
検証日
実行環境
node:24 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 24.22.2
  • npm 11.19.1
  • Python 3.11.2
  • Git 2.39.5
  • Vitest 5.1.0

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. テストを async にして await を付ける

test("fetchUser", async () => {
  await expect(fetchUser(1)).resolves.toEqual({ id: 1, name: "sato" });
});

await を付けると、Promise が決着するまでテストは終わらない。
rejects と toMatchFileSnapshot も同じ書き方で直る。

2. expect の戻り値を return する

test("deleteUser", () => {
  return expect(deleteUser(2)).rejects.toThrow("not found");
});

テストの関数が Promise を返すと、Vitest はそれが決着してからテストを終える。
return できるのは 1 つだけなので、同じテストに resolves や rejects が 2 つ以上あるなら、1 の書き方で 1 つずつ待つ。

3. 4.1 のうちに警告を探して直す

5 に上げる前に、4.1 で npx vitest run を打つ。
stderr | user.test.js > fetchUser の下に「was not awaited」の警告が出たテストが、5 で落ちるテストだ。
警告の最後の行に、await が要る行の番号が出る。

よくある原因

  1. resolves か rejects の前に await を付けていない。
    どちらも Promise を返すので、待たないと結果が出る前にテストが終わる。
    テストの関数を async にしただけで await を書き忘れた場合も、同じエラーになる。
  2. 4.1 で出ていた警告をそのままにして 5 に上げた。
    4.1 の警告も「Promise returned by … was not awaited」で始まり、次のメジャー版でテストが落ちるようになると予告していた。
  3. toMatchFileSnapshot を await せずに呼んでいる。
    公式の移行ガイドによると、ファイルに書き出すスナップショットも非同期のマッチャーで、5 では resolves と同じ扱いになった。