Playwrightでawaitを書き忘れたときに出るエラーの直し方

​​Playwright​E2Eテスト,ESLint,TypeScript,トラブルシュート

Playwright のテストで Error: locator.click: Target page, context or browser has been closed と出るのは、ページがもう閉じられたあとに、そのページの操作が始まったときです。テストの中で await を書き忘れると、テストが終わってページが閉じられても、操作だけが残って動き出すため、この状態になります。E2E テストで、コードに問題が見当たらないテストが落ちるときも、原因がほかのテストの await の書き忘れのことがあります。

私は検証環境で await の抜けたテストをいくつか書き、出たエラーと、直したあとの結果を確かめました。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4、@playwright/test 1.63.0 です。テストは TypeScript で書き、ブラウザは Chromium(ヘッドレス)だけで動かしました。Firefox・WebKit や、Python などほかの言語の Playwright では試していません。テストするページは、外部のサイトではなく page.setContent() でその場に作りました。ESLint は 10.15.0、typescript-eslint は 8.72.2、eslint-plugin-playwright は 2.12.2 です。

await のないテストは通り、次のテストが落ちる

検証に使ったのは、「保存」ボタンと3つのチェックボックスがあるページです。ボタンを押すと、300ミリ秒後に「保存しました」と出ます。

次のテストでは、ボタンを押す処理を saveAfterInput() という関数にまとめ、呼び出すときに await を書き忘れています。2つ目のテストは、ボタンには触れない別のテストです。

ts
// tests/bad/helper.spec.ts
import { test, type Page } from '@playwright/test';
import { html } from '../page';

async function saveAfterInput(page: Page) {
  await new Promise((resolve) => setTimeout(resolve, 300)); // 入力が落ち着くのを待つつもり
  await page.getByRole('button', { name: '保存' }).click();
}

test('ヘルパーの呼び出しに await がない', async ({ page }) => {
  await page.setContent(html);
  saveAfterInput(page);
});

test('次のテスト', async ({ page }) => {
  await page.setContent(html);
  await page.getByLabel('記事A').check();
  await page.waitForTimeout(1000);
});

1つ目のテストだけを -g で選んで動かすと、成功しました(出力は一部だけ抜き出しています)。ボタンは押されていないのに、結果は成功(✓)です。

text
  ✓  1 tests/bad/helper.spec.ts:9:1 › ヘルパーの呼び出しに await がない (91ms)

  1 passed (696ms)

2つを続けて動かすと、1つ目は成功のまま、2つ目が失敗しました(パスは /path/to/app に置き換えています。先頭の Running 2 tests using 1 worker の行と、Error: page.waitForTimeout: Test ended. より後ろ(コードの抜き出しと集計など)は省いています)。

text
  ✓  1 tests/bad/helper.spec.ts:9:1 › ヘルパーの呼び出しに await がない (71ms)
  ✘  2 tests/bad/helper.spec.ts:14:1 › 次のテスト (297ms)


  1) tests/bad/helper.spec.ts:14:1 › 次のテスト ─────────────────────────────────────────────────────────

    Error: locator.click: Target page, context or browser has been closed

      4 | async function saveAfterInput(page: Page) {
      5 |   await new Promise((resolve) => setTimeout(resolve, 300)); // 入力が落ち着くのを待つつもり
    > 6 |   await page.getByRole('button', { name: '保存' }).click();
        |                                                  ^
      7 | }
      8 |
      9 | test('ヘルパーの呼び出しに await がない', async ({ page }) => {
        at saveAfterInput (/path/to/app/tests/bad/helper.spec.ts:6:50)

    Error: page.waitForTimeout: Test ended.

失敗として数えられたのは「次のテスト」ですが、エラーが指している行は、1つ目のテストから呼んだ saveAfterInput() の click() です。落ちたテストではなく、エラーに表示されるコードの行と at の行を見ると、書き忘れた場所にたどり着けます。

ページが閉じたあとに操作が始まるから

Playwright Test は、テストごとに新しいブラウザコンテキストを作ります。page フィクスチャはそのコンテキストの中のページで、テストが終わると後片付けされます。検証環境の node_modules/playwright/lib/index.js を見ると、この後片付けでコンテキストを閉じています。テストの関数は、await を書き忘れた操作を待たずに終わるので、操作が終わる前に後片付けが進んでしまいます。

1つ目のテストで await なしで呼んだヘルパーが300ミリ秒待つ間に、テストの関数が終わってページが閉じられ、2つ目のテストが動いている最中にヘルパーの click() が始まって「Target page, context or browser has been closed」になる流れを、時間の順に並べた図
await のないヘルパーと、エラーが出る場所

上のテストでは、saveAfterInput() が300ミリ秒待っている間に1つ目のテストの関数が終わり、ページが閉じられました。そのあと click() が始まったときには、ページはもうありません。このときに出るのが Target page, context or browser has been closed です。エラーは、その時点で動いていた2つ目のテストに付けられました。

2つ目のテストは、1秒待っている途中で、このエラーで失敗しました(297ms)。1つ目だけを動かしたときは、エラーは出ずに成功しました。

「Test ended.」と出る場合もある

await の書き忘れでも、エラーの文面が違うことがあります。テストの最後の click() から await を外したところ、次のように出ました(出力は一部だけ抜き出しています)。

ts
test('最後の click に await がない', async ({ page }) => {
  await page.setContent(html);
  page.getByRole('button', { name: '保存' }).click();
});
text
    Error: locator.click: Test ended.
    Call log:
      - waiting for getByRole('button', { name: '保存' })

違いは、ページが閉じられたときに、その操作がもう始まっていたかどうかです。Playwright Test は、テストの終わりにコンテキストを閉じるとき、閉じる理由として Test ended. を context.close() に渡しています(同じ index.js で確かめました)。BrowserContext.close() の reason の説明にあるとおり、この理由は、閉じたことで中断された操作のエラーに出ます。

Playwright Test を使わない Node.js のスクリプトで、両方を並べて確かめました(ブラウザとページを用意する部分と、最後の browser.close() は省いています。ページに「保存」ボタンはないので、閉じる前の click() はボタンを待ち続けています)。

js
const inFlight = page.getByRole('button', { name: '保存' }).click().catch((e) => e.message.split('\n')[0]);
await context.close({ reason: '閉じた理由のテキスト' });
console.log('閉じる前から待っていた操作:', await inFlight);
const after = await page.getByRole('button', { name: '保存' }).click().catch((e) => e.message.split('\n')[0]);
console.log('閉じたあとに始めた操作:', after);
text
閉じる前から待っていた操作: locator.click: 閉じた理由のテキスト
閉じたあとに始めた操作: locator.click: Target page, context or browser has been closed

上の click() のテストで Test ended. が出たのも、原因は同じ await の書き忘れです。forEach() に async の関数を渡して、3つのチェックボックスに順にチェックを入れようとしたテストも locator.check: Test ended. で落ちました。MDN の forEach() の説明にあるとおり、forEach() は渡した関数が返す Promise を待ちません。

書き忘れの場所ごとの直し方

どれも、操作の前に await を書いて、テストの関数がその操作の終わりを待つようにすれば直ります。直したテストは5つとも通りました(出力は一部だけ抜き出しています)。

text
  ✓  1 tests/fixed/click.spec.ts:4:1 › 最後の click に await を付ける (947ms)
  ✓  2 tests/fixed/fixture.spec.ts:13:1 › 自作のフィクスチャで use に await を付ける (399ms)
  ✓  3 tests/fixed/foreach.spec.ts:4:1 › for...of で1つずつ await する (178ms)
  ✓  4 tests/fixed/helper.spec.ts:9:1 › ヘルパーの呼び出しに await を付ける (695ms)
  ✓  5 tests/fixed/helper.spec.ts:15:1 › 次のテスト (116ms)

関数にまとめた処理は、関数の中だけでなく、呼び出す側にも await が要ります。saveAfterInput(page); を await saveAfterInput(page); にすると、押したあとの expect() まで通りました。

forEach() は for...of に書き換えます。

ts
for (const name of ['記事A', '記事B', '記事C']) {
  await page.getByLabel(name).check();
}
await expect(page.getByRole('checkbox', { checked: true })).toHaveCount(3);

自分で作ったフィクスチャでは、use() にも await が要ります。次のように書くと、テストに myPage を渡した直後に context.close() まで進んでしまいます。

ts
const test = base.extend<{ myPage: Page }>({
  myPage: async ({ browser }, use) => {
    const context = await browser.newContext();
    const page = await context.newPage();
    use(page); // ← await がない
    await context.close();
  },
});

このフィクスチャを使ったテストは、最初の await myPage.setContent(html) で page.setContent: Target page, context or browser has been closed になりました。テストの1行目で落ちるので、フィクスチャの側を疑う手がかりになります。公式ドキュメントのフィクスチャの例はどれも await use(...) と書かれています。await use(page); に直すと通りました。

Playwright Test を使わずに playwright パッケージで書くスクリプトでも、click() に await がないまま await browser.close() まで進むと、同じ locator.click: Target page, context or browser has been closed で Node.js が止まりました。

ESLint で書き忘れを先に見つける

Playwright のベストプラクティスでは、typescript-eslint の no-floating-promises を使って、Playwright の API の前の await の抜けを見つけることをすすめています。このルールは型の情報を使うので、parserOptions.projectService を有効にして、テストのファイルが tsconfig.json に含まれるようにしておきます。

js
// eslint.config.mjs
import { defineConfig } from 'eslint/config';
import tseslint from 'typescript-eslint';
import playwright from 'eslint-plugin-playwright';

export default defineConfig({
  files: ['tests/**/*.ts'],
  extends: [playwright.configs['flat/recommended']],
  languageOptions: {
    parser: tseslint.parser,
    parserOptions: { projectService: true },
  },
  plugins: { '@typescript-eslint': tseslint.plugin },
  rules: {
    'playwright/missing-playwright-await': 'error',
    '@typescript-eslint/no-floating-promises': 'error',
    '@typescript-eslint/no-misused-promises': 'error',
  },
});

この設定で、上の4つの書き忘れをすべて見つけられました(アサーションのないテストを知らせる playwright/expect-expect は止めて動かしました。パスは置き換え、最後の集計の行は省いています)。

text
/path/to/app/tests/bad/click.spec.ts
  6:3  error  Promises must be awaited, end with a call to .catch, end with a call to .then with a rejection handler or be explicitly marked as ignored with the `void` operator  @typescript-eslint/no-floating-promises

/path/to/app/tests/bad/fixture.spec.ts
  8:5  error  Promises must be awaited, end with a call to .catch, end with a call to .then with a rejection handler or be explicitly marked as ignored with the `void` operator  @typescript-eslint/no-floating-promises

/path/to/app/tests/bad/foreach.spec.ts
  6:33  error  Promise returned in function argument where a void return was expected  @typescript-eslint/no-misused-promises

/path/to/app/tests/bad/helper.spec.ts
  11:3  error    Promises must be awaited, end with a call to .catch, end with a call to .then with a rejection handler or be explicitly marked as ignored with the `void` operator  @typescript-eslint/no-floating-promises
  17:9  warning  Unexpected use of page.waitForTimeout()                                                                                                                             playwright/no-wait-for-timeout

forEach() の書き方は、no-floating-promises ではなく no-misused-promises が見つけています。戻り値を使わない場所に async の関数を渡している、という指摘です。

eslint-plugin-playwright の推奨設定だけで同じファイルを調べると、4つとも見つかりませんでした。出たのは waitForTimeout() の警告1つだけです。このプラグインの missing-playwright-await が初期設定で調べるのは、toHaveText() などのアサーションや test.step()、waitFor で始まるメソッドで、click() は対象に入っていません。同じページにある includePageLocatorMethods: true のオプションを付けると、page.click() や locator.click() なども調べるようになります。付けて試したところ、最後の click() の書き忘れは 'click' must be awaited or returned と見つかりましたが、ヘルパーの呼び出し、forEach()、フィクスチャの use() の3つは見つかりませんでした。

ポイント

自作の関数や use() の書き忘れまで見つけるには、eslint-plugin-playwright だけでなく、型の情報を使う typescript-eslint のルールが要ります。

​Posted by 86