PlaywrightのwebServerで開発サーバーを起動する方法
Playwright の設定ファイルの webServer に、開発サーバーを起動するコマンドと URL を書いておくと、npx playwright test だけで「サーバーを起動する → 応答するまで待つ → テストする → サーバーを止める」までが進みます。E2E テストのたびに別の端末で npm run dev を動かしておく手間がなくなり、CI でも同じコマンドでテストできます。
検証環境は Ubuntu 24.04、Node.js 22.23.4、@playwright/test 1.63.0、Vite 8.3.8 です。ブラウザは Chromium(ヘッドレス)だけを使いました。Vite 以外のサーバーは、起動の遅れやポートを変えられる小さな Node.js の HTTP サーバーを書いて使っています。CI のサービス上での実行、Windows、reuseExistingServer でサーバーを使い回す動き、HTTPS のサーバーは試していません。
Vite の npm run dev を起動する設定
package.json の dev スクリプトで Vite を起動するプロジェクトに、次の設定ファイルを置きました。
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: './tests',
reporter: 'list',
use: {
baseURL: 'http://localhost:5173',
browserName: 'chromium',
},
webServer: {
command: 'npm run dev',
url: 'http://localhost:5173',
reuseExistingServer: !process.env.CI,
},
});
command が起動するコマンド、url が「この URL が応答したら起動が終わった」とみなす場所です。use の baseURL を書いておくと、テストの中では page.goto('/') のように URL の後ろだけを書けます。reuseExistingServer は、すでにその URL でサーバーが動いていたら起動せずにそれを使う指定で、公式ドキュメントの webServer の説明では !process.env.CI(CI のときだけ毎回起動する)が勧められています。
テストは、ボタンを押すと回数が増えることを確かめるだけのものです。
// tests/counter.spec.ts
import { test, expect } from '@playwright/test';
test('ボタンを押すと回数が増える', async ({ page }) => {
await page.goto('/');
const button = page.getByRole('button', { name: /押した回数/ });
await button.click();
await expect(button).toHaveText('押した回数:1');
});
開発サーバーを何も動かしていない状態で実行すると、Playwright が npm run dev を起動してテストが通りました。
$ npx playwright test
Running 1 test using 1 worker
✓ 1 tests/counter.spec.ts:3:1 › ボタンを押すと回数が増える (197ms)
1 passed (1.8s)
3回続けて実行したところ、全体の時間は 1.8秒、1.3秒、1.3秒でした。終わったあとに curl で http://localhost:5173 に接続すると応答はなく、vite のプロセスも残っていませんでした。テストが終わると、Playwright が起動したサーバーを止めています。
Playwright はサーバーの起動をどう待っているか
起動を待つ様子は、環境変数 DEBUG=pw:webserver を付けて実行すると見えます。Vite の場合の出力の一部です(時刻の前半を省きました)。
02:47:13.254Z pw:webserver Process started
02:47:13.254Z pw:webserver Waiting for availability...
02:47:13.254Z pw:webserver HTTP GET: http://localhost:5173/
02:47:13.257Z pw:webserver Error while checking if http://localhost:5173/ is available: connect ECONNREFUSED 127.0.0.1:5173
02:47:13.257Z pw:webserver Waiting 100ms
02:47:13.357Z pw:webserver HTTP GET: http://localhost:5173/
…(中略)
[WebServer] VITE v8.3.8 ready in 199 ms
…(中略)
02:47:13.643Z pw:webserver HTTP Status: 200
02:47:13.645Z pw:webserver WebServer available
Playwright は url に繰り返し GET を送り、応答が返った時点でテストを始めます。問い合わせの間隔は、100ミリ秒、250ミリ秒、500ミリ秒と延びていき、そのあとは1秒ごとでした。Playwright 1.63.0 のソースでも、待つ時間は [100, 250, 500] を順に使い、使い切ったら1000ミリ秒になっています。
この間隔の影響を見るため、待ち受けを始めるまでに3秒かかるサーバーを用意して、同じように問い合わせの時刻を記録しました。

サーバーは約3.0秒で待ち受けを始めましたが、その直前の問い合わせが2.87秒だったため、Playwright が気づいたのは次の3.87秒でした。間隔が1秒になってからは、サーバーの準備ができてからテストが始まるまでに、最大で1秒ほどの遅れが出ます。テスト1件が0.1秒ほどで終わるこの構成でも、全体の時間は4.6秒でした。
なお、webServer で起動したコマンドの標準出力は、初期設定では表示されません(stdout の初期値が 'ignore')。上の出力に Vite のログが出ているのは、DEBUG=pw:webserver を付けて実行したためです。付けずに実行したときは表示されませんでした。
url には「準備ができたら応答する」場所を書く
url は、何でも応答があればよいわけではありません。TestConfig の webServer の説明によると、起動が終わったとみなすのは、2xx、3xx、400、401、402、403 のどれかが返ったときです。404 は入っていません。
API だけのサーバーのように、/ に何も置いていないと 404 になります。そういうサーバーを url: 'http://localhost:4000'、timeout: 5_000 で待たせたところ、5秒待ってテストを始めずに終わりました。
$ npx playwright test -c api-404.config.ts
Error: Timed out waiting 5000ms from config.webServer.
DEBUG=pw:webserver を付けると、サーバーは動いていて、問い合わせに 404 が返り続けていたことが分かります。
02:47:32.579Z pw:webserver HTTP Status: 404
02:47:32.582Z pw:webserver HTTP Status: 404
…(中略)
02:47:37.358Z pw:webserver HTTP Status: 404
Error: Timed out waiting 5000ms from config.webServer.
同じサーバーに 200 を返す /health を用意し、url: 'http://localhost:4000/health' に変えると、テストは 0.7秒で通りました。
起動に8秒かかるサーバーを timeout: 5_000 で待たせたときも、出たのはまったく同じ Timed out waiting 5000ms from config.webServer. でした。メッセージだけでは「起動が遅い」のか「起動しているのに URL が 404」なのかを区別できないので、時間切れになったら DEBUG=pw:webserver を付けて、HTTP Status の行が出ているかを見ると早く切り分けられます。起動が遅いだけなら、timeout(初期値は60秒)を延ばします。
設定ファイルをサブフォルダに置くときは cwd を書く
command は、初期設定では設定ファイルのあるフォルダで実行されます(TestConfig の webServer の説明の cwd)。設定ファイルを configs/ に置き、command: 'node server.mjs' のまま実行すると、configs/server.mjs を探して失敗しました。出力は一部を省き、パスを /path/to/app に置き換えています。
$ npx playwright test -c configs/cwd.config.ts
[WebServer] Error: Cannot find module '/path/to/app/configs/server.mjs'
…(中略)
Error: Process from config.webServer was not able to start. Exit code: 1
この場合は、サーバーのプロセスがすぐに終了したため、timeout(初期値は60秒)を待たずに1.0秒で止まりました。webServer に cwd: '..' を足してプロジェクトの直下で実行させると、テストは通りました。
フロントエンドと API の2つのサーバーを起動する
webServer には配列も書けます。API(待ち受けまで2秒)と画面のサーバー(待ち受けまで1秒)を起動する設定です。
// multi.config.ts(抜粋)
webServer: [
{
name: 'API',
command: 'NAME=api PORT=4000 DELAY=2000 node server.mjs',
url: 'http://localhost:4000/health',
stdout: 'pipe',
},
{
name: 'Web',
command: 'NAME=web PORT=4173 DELAY=1000 node server.mjs',
url: 'http://localhost:4173',
stdout: 'pipe',
},
],
stdout: 'pipe' にすると、サーバーの出力がテストの出力に混ざって表示されます。name を付けると、行の先頭が初期設定の [WebServer] から、その名前に変わります。
$ npx playwright test -c multi.config.ts
[API] [api] 起動を開始(2000ms 後に待ち受ける)PLAYWRIGHT_TEST=1
[API] [api] listening on port 4000(起動から 2010ms)
[API] [api] GET /health
[Web] [web] 起動を開始(1000ms 後に待ち受ける)PLAYWRIGHT_TEST=1
[Web] [web] listening on port 4173(起動から 1009ms)
[Web] [web] GET /
Running 1 test using 1 worker
[Web] [web] GET /
[API] [api] GET /api/message
✓ 1 tests/multi.spec.ts:3:1 › 画面と API の両方に届く (160ms)
1 passed (5.6s)
出力の PLAYWRIGHT_TEST=1 は、サーバーが自分の環境変数を表示したものです。公式ドキュメントの webServer の説明にあるとおり、webServer で起動したコマンドには PLAYWRIGHT_TEST=1 が渡されていました。
ここで注目したいのは起動の順番です。公式ドキュメントには、複数のサーバーを「同時に」起動できると書かれています。しかし、この検証環境(1.63.0)では、API の起動が終わって /health が応答してから、画面のサーバーの起動が始まりました。DEBUG=pw:webserver の出力でも、2つめの Starting WebServer process は、1つめの WebServer available の2ミリ秒後です。
02:47:55.725Z pw:webserver Starting WebServer process NAME=api PORT=4000 DELAY=2000 node server.mjs...
02:47:58.604Z pw:webserver WebServer available
02:47:58.606Z pw:webserver Starting WebServer process NAME=web PORT=4173 DELAY=1000 node server.mjs...
02:48:00.476Z pw:webserver WebServer available
そのため、2つの起動待ちの時間は足し算になり、全体で5.6秒かかりました。起動に時間のかかるサーバーを並べるときは、この合計の時間を見込んでおく必要があります。
テストが終わったときの止め方
TestConfig の webServer の説明によると、何も指定しなければ、起動したプロセスのグループは SIGKILL で強制的に止められます。検証用のサーバーには、SIGTERM を受け取ったら shutdown.log に1行書いてから終了する処理を入れておきました。初期設定のまま実行すると、テストは通りましたが、shutdown.log は作られませんでした。SIGTERM を受け取る処理が動かないまま止められています。
gracefulShutdown を書くと、先に指定したシグナルを送り、timeout のミリ秒数を過ぎても終わらなければ SIGKILL を送ります。
webServer: {
command: 'node server.mjs',
url: 'http://localhost:4173',
stdout: 'pipe',
gracefulShutdown: { signal: 'SIGTERM', timeout: 5_000 },
},
この設定では、テストのあとに [WebServer] [web] SIGTERM を受け取った と表示され、shutdown.log に「SIGTERM を受け取り、後片付けをして終了」の1行が書かれていました。初期設定で止めたあとも、続けて同じ 4173 番でサーバーを起動できました。gracefulShutdown で止めたあとは、4173 番に接続しても応答はありませんでした。
サーバーが終了するときに、ファイルへの書き出しや一時ファイルの削除などの後片付けをしている場合、初期設定の SIGKILL ではその処理が動きません。gracefulShutdown を書いておきましょう。なお、gracefulShutdown は Windows では使われません(TestConfig の説明より)。
ポート番号をサーバーの出力から受け取る
url の代わりに wait を使うと、サーバーの出力に決まった文字列が出たところで起動が終わったとみなせます。正規表現に名前付きのグループを書くと、その部分が環境変数に入ります(TestConfig の webServer の説明)。これを使って、空いているポートでサーバーを起動し、そのポートでテストしてみました。
// wait.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: './tests',
testMatch: 'port.spec.ts',
reporter: 'list',
use: { baseURL: `http://localhost:${process.env.WEB_PORT}` },
webServer: {
command: 'PORT=0 node server.mjs',
stdout: 'pipe',
wait: { stdout: /listening on port (?<web_port>\d+)/ },
},
});
PORT=0 で起動すると、検証用のサーバーは OS が選んだ空いているポートで待ち受け、listening on port 44309 のように出力します。グループの名前 web_port は、大文字の WEB_PORT という環境変数になります。2回実行すると、ポートは 44309 と 40015 で、どちらもテストの中の page.goto('/') はそのポートを開いて通りました。
$ npx playwright test -c wait.config.ts
[WebServer] [web] 起動を開始(0ms 後に待ち受ける)PLAYWRIGHT_TEST=1
[WebServer] [web] listening on port 44309(起動から 10ms)
Running 1 test using 1 worker
[WebServer] [web] GET /
開いた URL: http://localhost:44309/
✓ 1 tests/port.spec.ts:3:1 › ランダムなポートのサーバーを開く (126ms)
1 passed (988ms)
設定ファイルの baseURL で process.env.WEB_PORT を読む書き方は、この検証では2回とも動きました。ただし、公式ドキュメントに書かれているのは名前付きのグループが環境変数に入ることまでで、それを baseURL に使う書き方の説明はありません。ポート番号を決め打ちにしたくないときに使える書き方ですが、Playwright を更新したときは、まずこの設定で通るかを確かめてください。





