できない.dev

Playwright の webServer が起動待ちでタイムアウトしてテストが始まらない

webServer は url か port が応答するまで待ち、既定では 60 秒で打ち切る。
ビルドを含む起動コマンドや、待ち先の URL が想定と違う設定が主な原因。
timeout を伸ばすか、待ち条件と起動コマンドを見直す。

公開: 更新:

症状できない · exit 1
npx playwright test
Error: Timed out waiting 60000ms from config.webServer.
解決後できた · exit 0
npx playwright test
…
Running 1 test using 1 worker
[1/1] app.spec.js:3:1 › server responds
  1 passed (1.1m)

2026-10-16 に node:20(Playwright 1.64.1 / Node.js 20.20.2) で実際に打って取った出力。検証環境の詳細

要約

Timed out waiting 60000ms from config.webServer は、webServer に書いた起動コマンドを実行したあと、url または port が応答可能になるのを待ち切れなかった状態だ。
テスト本体のタイムアウト(既定 30 秒)とは別の設定なので、timeout を上げても直らない。

まず起動が遅いだけなのか、そもそも起動していないのかを切り分ける。

// playwright.config.ts
export default defineConfig({
  webServer: {
    command: "npm run start",
    url: "http://localhost:3000",
    timeout: 180 * 1000,
    stdout: "pipe",
  },
});

実行例

起動に 65 秒かかるサーバーを既定の timeout(60 秒)のまま webServer で待たせると、npx playwright test は Timed out waiting 60000ms from config.webServer. を出して終了コード 1 になり、テストは始まらなかった。
timeout を 120 秒に伸ばして stdout: 'pipe' で起動ログを出すようにすると、同じコマンドで 1 件のテストが通り、終了コードは 0 になっている。

$ npx playwright test
Error: Timed out waiting 60000ms from config.webServer.
$ echo $?
1
$ npx playwright test
[WebServer] building...
 
[WebServer] listening on 3000
 
Running 1 test using 1 worker
 
[1/1] app.spec.js:3:1 › server responds
  1 passed (1.1m)
$ echo $?
0

— 2026-10-16 時点の出力

検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-10-16 検証(ほか 2 件)
検証日
実行環境
node:20 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5
  • Playwright 1.64.1

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

解決策

1. timeout を実測に合わせる

まず手元で起動時間を測り、それより余裕のある値を入れる。

// playwright.config.ts
webServer: {
  command: "npm run start",
  url: "http://localhost:3000",
  timeout: 120 * 1000,
},

公式ドキュメント(新しいタブで開く)の timeout の説明どおり、これは「プロセスが起動して応答可能になるまで待つ時間」であり、テスト 1 件あたりのタイムアウトとは独立している。

2. 起動ログを見る

原因の切り分けには標準出力が要る。
ignore になっていたら外す。

// playwright.config.ts
webServer: {
  command: "npm run start",
  url: "http://localhost:3000",
  stdout: "pipe",
  stderr: "pipe",
},

ここで例外やポート衝突が見えるなら、タイムアウトは症状であって原因ではない。

3. ビルドと起動を分ける

CI ではテスト実行前にビルドを終わらせ、webServer.command は起動だけにする。

- run: npm run build
- run: npx playwright test

ビルド時間が webServer の待ち時間から外れるため、timeout を無闇に伸ばさずに済む。

4. 待ち先を素直なパスにする

url にはリダイレクトや認証を挟まないパスを指定する。
ヘルスチェック用のエンドポイントがあるならそれが最適だ。

// playwright.config.ts
webServer: {
  command: "npm run start",
  url: "http://127.0.0.1:3000/api/health",
  reuseExistingServer: !process.env.CI,
},

localhost の名前解決が IPv6 側に倒れて繋がらない環境もあるため、127.0.0.1 を直接書くと切り分けやすい。

よくある原因

  1. 起動が 60 秒に収まっていない。
    webServer.timeout の既定値は 60000 ミリ秒である。
    npm run build && npm run start のようにビルドを含めると、CI では簡単に超える。
  2. 待ち先の URL が条件を満たさない。
    url を指定した場合、Playwright は 2xx / 3xx / 400 / 401 / 402 / 403 のいずれかが返るまで待つ。
    これ以外(500 やタイムアウト)を返し続けると待ち切れない。
  3. ホストやポートが一致していない。
    アプリが 0.0.0.0 以外の特定インターフェースだけで待ち受けていたり、PORT 環境変数で別ポートに変わっていたりすると、待ち先と一致しない。
  4. サーバーが即死している。
    起動直後にエラー終了しているのに、stdout: 'ignore' でログを捨てているため「遅いだけ」に見えている。