PlaywrightのテストをVS Codeで書くなら、Microsoft公式の拡張機能「Playwright Test for VSCode」を入れると、テストの実行・ブレークポイントでのデバッグ・ロケーターの取得・操作の録画までをエディタから離れずに行えます。この記事では、導入から実行・デバッグ・コード生成・settings.jsonの設定値までを、コピーして使える設定例と一緒にまとめました。挙動は拡張のv1.1.20（2026年10月公開）のソースと、Playwright 1.65系（2026年11月時点の最新は1.65.1）の公式ドキュメントで確かめています。
まとめ：Playwright VS Code拡張は実行・デバッグ・コード生成を1画面で回す道具
- 導入：拡張ID
ms-playwright.playwrightを入れ、コマンドパレットの「Test: Install Playwright」で初期化する。動く条件はVS Code 1.93以上とPlaywright 1.38以上。 - 認識：拡張が探す設定ファイルは名前に「playwright」を含む
.config.ts・.js・.mts・.mjsだけ。.cjsや名前にplaywrightが無いファイルはテスト一覧に出ない。 - 実行：テスト横の緑の三角で1件、Testingサイドバーで全件。複数ブラウザはPlaywrightサイドバーのプロジェクトのチェックで切り替える。
- デバッグ：Show browserをオンにするとブラウザを使い回す代わりにワーカーが1つになる。失敗の原因はShow trace viewerで追う。
- コード生成：Pick locatorで要素のロケーターを取り、Record at cursorでカーソル位置にテストの続きを録画する。
- 落とし穴：global setupは初回の実行だけで流れ、以降は使い回される。テストデータを毎回戻すなら「Run global setup on each run」をオンにする。
Playwright Test for VSCodeを入れて設定ファイルを認識させる手順
拡張はVisual Studio MarketplaceのPlaywright Test for VSCodeの配布ページから入手でき、ソースはGitHubのmicrosoft/playwright-vscodeで公開されています。Playwright自体の仕組みはPlaywright（プレイライト）とは？仕組み・できること・Seleniumとの違いを先に読むと、ブラウザとテストランナーの関係がつかめます。
拡張のインストールとInstall Playwrightが実行するnpm initの中身
拡張機能ビューで「Playwright」と検索してMicrosoft提供のものを入れるか、ターミナルからVS CodeのCLIで入れます。
# 拡張を入れて、入った版を確かめる
code --install-extension ms-playwright.playwright
code --list-extensions --show-versions | grep playwright
# 出力例：[email protected]
# 「Test: Install Playwright」が裏で流すコマンド（v1.1.20のinstaller.ts）
npm init playwright@latest --yes "--" . --quiet空のフォルダか、package.jsonのあるフォルダを開いた状態で、コマンドパレットから「Test: Install Playwright」を実行します。ブラウザ（Chromium・Firefox・WebKit）とGitHub Actionsのワークフローを足すかを選ぶと、拡張がターミナルに上の npm init playwright@latest を選択内容に対応する引数付きで送る仕組みです。手で初期化した場合と同じファイル一式ができるので、生成物の意味はPlaywrightの使い方入門：E2Eテストを初期化から実行・CIまで書く手順で確認できます。拡張のpackage.jsonでは、対応するVS Codeが ^1.93.0 と宣言されています。
テスト一覧に出ない原因は設定ファイルの命名とPlaywright 1.38未満
拡張を入れてもTestingサイドバーが空のときは、設定ファイルの名前を疑ってください。extension.tsは、ワークスペース内を **/*playwright*.config.{ts,js,mts,mjs} のパターンで探し、node_modulesの中は除外します。
repo/
├─ apps/web/playwright.config.ts ← 認識される
├─ apps/admin/playwright.admin.config.ts ← 認識される（名前にplaywrightを含む）
├─ legacy/playwright.config.cjs ← 認識されない（拡張子が対象外）
└─ e2e/e2e.config.ts ← 認識されない（名前にplaywrightが無い）もう1つの原因は版です。同じファイルで最小版が1.38と定められ、それより古い @playwright/test を検出すると「Playwright Test v1.38 or newer is required」と表示して読み込みません。拡張が版を読むのは、プロジェクトのnode_modulesに入っている @playwright/test か playwright のpackage.jsonです。npm installの前に開くと「インストールが見つからない」扱いになります。版の確認と更新はPlaywrightの最新バージョンの確認・更新方法、インストール自体のエラーはPlaywrightのインストール方法とできない時の対処で扱っています。
チームで使うなら、.vscode/extensions.json の recommendations に ms-playwright.playwright を書いてコミットしておくと、clone直後にVS Codeが拡張のインストールを促します。
テストエクスプローラーとプロジェクト選択でテストを流す操作の基本
拡張がテストを読み込むと、アクティビティバーのTestingアイコンにテストの一覧が並び、同じサイドバーの下側にPlaywright専用の欄が出ます。公式のVS Code拡張ページの手順に沿って、実行の操作を確かめていきます。
緑の三角とTestingサイドバーで1件から全件まで実行する手順
テスト関数の左に出る緑の三角を押すとそのテストだけが流れ、終わると成功のチェックか失敗の赤いバツに変わります。ファイル内の全件を実行する操作はファイル単位の三角、プロジェクト全体を実行する操作はTestingサイドバー最上部の三角です。実行中は処理中の行がハイライトされ、終わった行には各ステップの所要時間が表示されます。
失敗したテストは、期待値と実際の値、呼び出しログがエディタ内に出ます。Copilotを入れていれば、エラー横のきらめきアイコン（Fix with AI）から修正案も受け取れますが、ロケーターを緩めて通しただけの案でないかは自分で確かめてください。Copilotの導入はVS CodeでGitHub Copilotを使うには？導入手順・使い方・料金にまとめています。
Playwrightサイドバーのチェックで複数ブラウザのプロジェクトを選ぶ
playwright.config.tsの projects に並べたブラウザ設定は、Playwrightサイドバーにチェックボックスとして並びます。READMEによると、既定では先頭のプロジェクトだけが選ばれた状態です。WebKitでも確かめたいときはチェックを足すと、選んだすべてのプロジェクトで同じテストが流れます。
// playwright.config.ts（抜粋）
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests',
globalSetup: './global-setup.ts',
use: { baseURL: process.env.BASE_URL ?? 'http://localhost:3000' },
projects: [
{ name: 'setup', testMatch: /.*\.setup\.ts/ },
{
name: 'chromium',
use: { ...devices['Desktop Chrome'], storageState: 'playwright/.auth/user.json' },
dependencies: ['setup'],
},
{
name: 'webkit',
use: { ...devices['Desktop Safari'], storageState: 'playwright/.auth/user.json' },
dependencies: ['setup'],
},
],
});dependencies で指定したsetupプロジェクトはTestingサイドバーにも出て、単独で流せます。ログイン状態を作り直したいときだけsetupを手で実行する、という使い方も可能です。設定ファイルが複数あるモノレポでは、Playwrightサイドバーの歯車アイコン（Toggle Playwright Configs）で対象の設定を切り替えます。
目のアイコンのウォッチモードで保存のたびにテストを再実行させる
Testingサイドバーで目のアイコンを押すと、そのテストがウォッチ対象になり、ファイルを保存するたびに再実行されます。期待値を少しずつ直しながら通すときに便利です。対象を絞らないと、保存のたびに重いテストまで走ります。
ブレークポイントとShow browserでテストを止めて原因を追う手順
公式のデバッグのページは、デバッグの手段として最初にVS Code拡張を勧めています。止めて見る・画面で見る・記録で見るの3通りを使い分けます。
Debug Testで止めた行のロケーターをブラウザ上でハイライトさせる
行番号の左をクリックしてブレークポイントを置き、テストの三角を右クリックして「Debug Test」を選ぶと、その行で止まって変数を確かめられます。止まっている間に、カーソルをPlaywrightの操作やロケーターの上に置くと、対応する要素が開いているブラウザ上でハイライトされる仕組みです。READMEが「Tune locators」と呼ぶ機能で、止めたままロケーターの文字列を書き換えると、ハイライトもその場で変わります。
ロケーターが2つの要素に当たって厳密モードで落ちる、といった原因を実行し直さずに確かめられます。ハイライトで見つけた違反をどう1件に絞るかはPlaywrightのlocator入門：getByRoleの書き方とstrict mode違反の直し方【1.65対応】にまとめました。壊れにくいロケーターの設計はPage Object Model（POM）とは？Playwright・Seleniumの実装例で扱っています。
Show browserはブラウザを使い回し1ワーカーで動く仕様と使いどころ
PlaywrightサイドバーのSETTINGS欄にある「Show browser」をオンにすると、ブラウザを表示したままテストが流れます。注意したいのは、この設定の実体がブラウザの再利用である点です。settingsView.tsでは設定名が reuseBrowser で、ラベルの横に「one worker」と書かれ、ツールチップには再利用すると並列実行が無効になると記されています。
そのため、オンのまま全件を流すとワーカー1つで順番に実行され、CLIより大幅に遅くなります。1件を見ながら直すときだけオンにし、全件はオフで流す運用が無難です。開いたブラウザは「Close all Playwright browsers」で閉じます。
Show trace viewerで失敗したステップの画面と通信を確かめる
「Show trace viewer」をオンにすると、テストが終わった時点でトレースが自動で開きます。公式のTrace viewerページにあるとおり、操作ごとのDOMスナップショット、ネットワークの要求と応答、コンソールのログ、対応するソースの行を1画面で確かめられる構成です。たまにしか落ちないテストは止めると再現しないことがあり、トレースを後から読むほうが早く原因に届きます。
Pick locatorとRecord at cursorでテストコードを生成する手順
テストの土台は録画で作り、細部は手で整えます。生成の仕組みは公式のTest generatorページにあるcodegenと同じで、CLIで npx playwright codegen を叩いた場合との違いは、生成先がエディタのファイルになることです。CLI側のオプションはPlaywright CLIコマンド一覧で確かめられます。
Pick locatorの結果はLocators欄に入り自動コピーは既定でオフ
Playwrightサイドバーの「Pick locator」を押してブラウザ上の要素にマウスを重ねると、使えるロケーターが表示されます。クリックした要素のロケーターは、Testingサイドバー内のLocators欄に入ります。v1.1.20の設定 playwright.pickLocatorCopyToClipboard は既定がfalseなので、クリックしただけではクリップボードに入りません。Locators欄でEnterを押してコピーするか、欄の「Copy on pick」をオンにしてください。
Locators欄の下のAria欄（Playwright 1.50以上）には、選んだ要素のARIAスナップショットがYAMLで出ます。書き換えると一致する要素がハイライトされるので、toMatchAriaSnapshot の期待値を確認するための欄として使用可能です。書き方はPlaywright aria snapshotの使い方で解説しています。
Record newで新規ファイルを作りRecord at cursorで続きを足す
「Record new」を押すとブラウザが開き、URLを開いて操作した内容が新しいテストファイルに書き込まれていきます。録画中のツールバーからは、表示の確認や値の確認といったアサーションも足せます。
既存のテストに操作を足すときは、テスト関数の中の続きを書きたい行にカーソルを置き、「Record at cursor」を押します。
// tests/login.spec.ts
import { test, expect } from '@playwright/test';
test('ログイン後に請求一覧へ移動できる', async ({ page }) => {
await page.goto('/login');
await page.getByLabel('ユーザーID').fill('qa-user01');
await page.getByLabel('パスワード').fill(process.env.E2E_PASSWORD ?? '');
await page.getByRole('button', { name: 'ログイン' }).click();
// ↓ここにカーソルを置いて Record at cursor を押すと、続きの操作が挿入される
await page.getByRole('link', { name: '請求一覧' }).click();
await expect(page.getByRole('heading', { name: '請求一覧' })).toBeVisible();
});録画で入るのは画面で入力した値そのものです。パスワードが平文で書き込まれるので、コミット前に環境変数へ置き換えてください。AIにテストの計画から生成まで任せる方法はPlaywright Agentsの使い方で比べられます。
Update methodの既定値は3wayでCLIのpatchと異なる点に注意
SETTINGS欄の下にある「Update snapshots」と「Update method」は、CLIの --update-snapshots と --update-source-method に当たります。拡張の既定値はUpdate snapshotsがmissing、Update methodが3wayです。公式のCommand lineページによると、CLIの --update-source-method の既定はpatchで、3wayはソースに競合マーカーを書き込む方式です。
つまり、VS Codeから流してaria snapshotの期待値がずれると、テストファイルに直接 <<<<<<< 形式の競合マーカーが入ります。差分ファイルを出してから確認したいチームは、下の設定でpatchに合わせておくとCLIと挙動がそろいます。
settings.jsonの環境変数とglobal setupの再実行設定を整える
チームで設定をそろえるなら .vscode/settings.json に書いてコミットします。v1.1.20で使える設定は次の7つです。
// .vscode/settings.json
{
"playwright.env": {
"BASE_URL": "http://localhost:3000",
"E2E_USER": "qa-user01",
"RETRY_LIMIT": 2
},
"playwright.reuseBrowser": false,
"playwright.showTrace": true,
"playwright.runGlobalSetupOnEachRun": true,
"playwright.pickLocatorCopyToClipboard": true,
"playwright.updateSnapshots": "missing",
"playwright.updateSourceMethod": "patch"
}playwright.envで渡す環境変数は文字列以外がJSON文字列に変わる
playwright.env に書いた値は、拡張から起動するテストに環境変数として渡ります。extension.tsの処理では、文字列以外の値は JSON.stringify で文字列にされるため、上の例の RETRY_LIMIT をテスト側で読むと、取得される値は文字列の “2” です。Yarn PnPのプロジェクトでは、拡張が NODE_OPTIONS に読み込み設定を自動で足します。
パスワードやAPIキーをこのファイルに書くと、コミットした時点でリポジトリに残ります。秘密の値はOSの環境変数か、Gitに含めない.envファイルから読み込む形にしてください。
global setupは初回だけ流れるので毎回の初期化はRun on each run
拡張は、global setupを最初の実行で1度だけ流し、その後のテスト実行では使い回します。testModel.tsを読むと、2回目以降は runGlobalSetupOnEachRun がオンのときだけ再実行する作りです。対象になるのは設定に globalSetup・globalTeardown・webServer のどれかがある場合で、PlaywrightサイドバーのSETUP欄から手動で流したり、teardownを呼んだりもできます。
// global-setup.ts
import { execSync } from 'node:child_process';
export default async function globalSetup() {
// テスト用DBを初期データに戻す（npm scriptの中身はプロジェクトに合わせる）
execSync('npm run db:seed:test', { stdio: 'inherit' });
}データを初期化する処理を置いたまま設定がオフだと、2回目以降は前回のデータが残り、VS Codeでだけ落ちる状態になります。「Run global setup on each run」をオンにするか、テストの前にSETUP欄から手で流してください。
Python版Playwrightは拡張の対象外でpytestのテスト機能を使う
この拡張が扱うのはNode.jsのPlaywright Testで、2026-11-15時点でPython版の公式ドキュメントにVS Codeのページはありません。Pythonで書く場合は、VS CodeのPython拡張が持つpytestのテスト機能でテストを流し、ロケーターの確認はPlaywright Inspectorで行います。
# pytest-playwrightを入れてブラウザを取得する
pip install pytest-playwright
playwright install chromium
# Inspectorを開いて1ステップずつ進めながらロケーターを確かめる
PWDEBUG=1 pytest -s tests/test_login.py
// .vscode/settings.json（VS CodeのTestingからpytestを流す）
{
"python.testing.pytestEnabled": true,
"python.testing.pytestArgs": ["tests", "--headed"]
}VS Code拡張で回すかCLIとUIモードで回すか：使い分けの判断基準
拡張は便利ですが、テスト運用のすべてを任せる道具ではありません。E2Eテストを組む側から、使い分けの線を引いておきます。
1件ずつ書いて直す段階は拡張に任せ全件とCIはCLIの結果で判断する
拡張が強いのは、Record at cursorで土台を作り、Debug Testで止めてロケーターを直し、ウォッチモードで通るまで回す短い往復です。
一方、全件の合否は拡張の結果で判断しないほうが安全です。Show browserをオンにすれば1ワーカーで流れ、global setupは使い回され、環境変数はsettings.json経由で入ります。CLIやCIと条件が3点ずれるため、拡張で全件が通ってもCIで落ちることは珍しくありません。プルリクエストを出す前は npx playwright test をCLIで1度流し、CI上の結果を正とする運用にしておきます。コンテナで条件をそろえる方法はPlaywright Docker実行ガイドで扱っています。
VS Code以外のエディタが混ざるチームはUIモードを共通の手段にする
開発者がWebStormやVimなどVS Code以外のエディタも使うチームでは、拡張を前提にした手順書は半分の人に通じません。npx playwright test --ui で開くUIモードはエディタを選ばず、テストの選択・ウォッチ・トレースの確認・ロケーターの取得まで同じことができます。この場合、手順書の基準にするのはUIモードで、拡張の位置づけはVS Codeを使う人のための便利機能です。UIモードの操作はPlaywrightの使い方入門で解説しています。
テストを書く人が1〜2人で全員VS Codeなら、拡張を前提にしてextensions.jsonとsettings.jsonをコミットするのが早道です。CIの構成やテスト運用の設計まで外部と組む場合は、DevOps・CI/CD導入支援のように、パイプラインとテスト自動化をまとめて扱える体制を選ぶと、手元の道具とCIの条件をそろえるところまで一緒に設計できます。E2Eで守る範囲の決め方はE2Eテストとは？結合テストとの違いとベストプラクティスを参照してください。
よくある質問
PlaywrightのVS Code拡張について、使い始めに出やすい疑問をまとめました。
拡張を入れてもテストが一覧に表示されないのはなぜですか？
多いのは3つの原因です。設定ファイルの名前に「playwright」が含まれていないか拡張子が .cjs であること、プロジェクトのPlaywrightが1.38より古いこと、npm installの前で @playwright/test がnode_modulesに無いことです。モノレポで設定ファイルが複数ある場合は、Playwrightサイドバーの歯車アイコンで対象の設定が選ばれているかも確かめてください。
Show browserをオンにするとテストが遅くなるのはなぜですか？
Show browserの実体は「ブラウザを再利用する」設定で、再利用のためにワーカーが1つに固定され、並列実行が止まるからです。1件を目で追いながら直すときだけオンにし、全件はオフにして流すか、CLIで実行してください。
VS Code拡張とUIモードはどちらを使えばよいですか？
VS Codeで書くならブレークポイントで止められる拡張、エディタが混在するチームではUIモードが向いています。内部は同じテストランナーなので併用できます。
拡張のFix with AIはCopilotの契約がなくても使えますか？
公式ページの説明では、Fix with AIはGitHub Copilotが失敗を解析して修正案を出す機能です。Copilotを入れていない環境ではアイコンからの提案は受けられません。テストの実行・デバッグ・録画などの基本機能はCopilotなしで使えます。
拡張のバージョンはどこで確かめて、いつ上げればよいですか？
拡張機能ビューの詳細か、code --list-extensions --show-versions で確かめられます。2026年11月時点の最新はv1.1.20で、VS Codeは1.93以上が必要です。VS Code本体の版の確かめ方はVS Codeの最新バージョンの確認方法・アップデート手順にあります。拡張は自動更新に任せて構いません。
関連記事
- Playwrightの使い方入門：E2Eテストを初期化から実行・CIまで書く手順【1.65対応】：拡張で流す前のテストの書き方とUIモードの操作
- Playwright（プレイライト）とは？仕組み・できること・Seleniumとの違いを解説：ブラウザとテストランナーの関係を押さえる前提知識
- Playwright CLIコマンド一覧｜test・codegen・installと1.63の新オプション：拡張のボタンに当たるCLIのコマンドとオプション
- Playwright aria snapshotの使い方｜toMatchAriaSnapshotの書き方と更新手順【1.64対応】：Aria欄で確かめたYAMLを期待値にする書き方
- Playwright Docker実行ガイド：公式イメージでのテストとCI組み込み・詰まり所【1.65対応】：手元とCIの実行条件をコンテナでそろえる方法
