---
title: "Playwright VS Code拡張の使い方：テスト実行・デバッグ・Pick locatorと録画の手順【1.65対応】"
url: "https://www.issoh.co.jp/tech/details/19789/"
published: 2026-11-15
updated: 2026-11-15
categories: ["自動化"]
publisher: "株式会社一創"
---

# Playwright VS Code拡張の使い方：テスト実行・デバッグ・Pick locatorと録画の手順【1.65対応】

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の配布ページ](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright)から入手でき、ソースは[GitHubのmicrosoft/playwright-vscode](https://github.com/microsoft/playwright-vscode)で公開されています。Playwright自体の仕組みは[Playwright（プレイライト）とは？仕組み・できること・Seleniumとの違い](https://www.issoh.co.jp/tech/details/3167/)を先に読むと、ブラウザとテストランナーの関係がつかめます。

### 拡張のインストールとInstall Playwrightが実行するnpm initの中身

拡張機能ビューで「Playwright」と検索してMicrosoft提供のものを入れるか、ターミナルからVS CodeのCLIで入れます。

```
# 拡張を入れて、入った版を確かめる
code --install-extension ms-playwright.playwright
code --list-extensions --show-versions | grep playwright
# 出力例：ms-playwright.playwright@1.1.20

# 「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まで書く手順](https://www.issoh.co.jp/tech/details/19779/)で確認できます。[拡張のpackage.json](https://github.com/microsoft/playwright-vscode/blob/main/package.json)では、対応するVS Codeが `^1.93.0` と宣言されています。

### テスト一覧に出ない原因は設定ファイルの命名とPlaywright 1.38未満

拡張を入れてもTestingサイドバーが空のときは、設定ファイルの名前を疑ってください。[extension.ts](https://github.com/microsoft/playwright-vscode/blob/v1.1.20/src/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の最新バージョンの確認・更新方法](https://www.issoh.co.jp/tech/details/9257/)、インストール自体のエラーは[Playwrightのインストール方法とできない時の対処](https://www.issoh.co.jp/tech/details/3563/)で扱っています。

チームで使うなら、`.vscode/extensions.json` の recommendations に `ms-playwright.playwright` を書いてコミットしておくと、clone直後にVS Codeが拡張のインストールを促します。

## テストエクスプローラーとプロジェクト選択でテストを流す操作の基本

拡張がテストを読み込むと、アクティビティバーのTestingアイコンにテストの一覧が並び、同じサイドバーの下側にPlaywright専用の欄が出ます。[公式のVS Code拡張ページ](https://playwright.dev/docs/getting-started-vscode)の手順に沿って、実行の操作を確かめていきます。

### 緑の三角とTestingサイドバーで1件から全件まで実行する手順

テスト関数の左に出る緑の三角を押すとそのテストだけが流れ、終わると成功のチェックか失敗の赤いバツに変わります。ファイル内の全件を実行する操作はファイル単位の三角、プロジェクト全体を実行する操作はTestingサイドバー最上部の三角です。実行中は処理中の行がハイライトされ、終わった行には各ステップの所要時間が表示されます。

失敗したテストは、期待値と実際の値、呼び出しログがエディタ内に出ます。Copilotを入れていれば、エラー横のきらめきアイコン（Fix with AI）から修正案も受け取れますが、ロケーターを緩めて通しただけの案でないかは自分で確かめてください。Copilotの導入は[VS CodeでGitHub Copilotを使うには？導入手順・使い方・料金](https://www.issoh.co.jp/tech/details/6860/)にまとめています。

### Playwrightサイドバーのチェックで複数ブラウザのプロジェクトを選ぶ

playwright.config.tsの `projects` に並べたブラウザ設定は、Playwrightサイドバーにチェックボックスとして並びます。[README](https://github.com/microsoft/playwright-vscode)によると、既定では先頭のプロジェクトだけが選ばれた状態です。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でテストを止めて原因を追う手順

[公式のデバッグのページ](https://playwright.dev/docs/debug)は、デバッグの手段として最初にVS Code拡張を勧めています。止めて見る・画面で見る・記録で見るの3通りを使い分けます。

### Debug Testで止めた行のロケーターをブラウザ上でハイライトさせる

行番号の左をクリックしてブレークポイントを置き、テストの三角を右クリックして「Debug Test」を選ぶと、その行で止まって変数を確かめられます。止まっている間に、カーソルをPlaywrightの操作やロケーターの上に置くと、対応する要素が開いているブラウザ上でハイライトされる仕組みです。READMEが「Tune locators」と呼ぶ機能で、止めたままロケーターの文字列を書き換えると、ハイライトもその場で変わります。

ロケーターが2つの要素に当たって厳密モードで落ちる、といった原因を実行し直さずに確かめられます。ハイライトで見つけた違反をどう1件に絞るかは[Playwrightのlocator入門：getByRoleの書き方とstrict mode違反の直し方【1.65対応】](https://www.issoh.co.jp/tech/details/19791/)にまとめました。壊れにくいロケーターの設計は[Page Object Model（POM）とは？Playwright・Seleniumの実装例](https://www.issoh.co.jp/tech/details/10677/)で扱っています。

### Show browserはブラウザを使い回し1ワーカーで動く仕様と使いどころ

PlaywrightサイドバーのSETTINGS欄にある「Show browser」をオンにすると、ブラウザを表示したままテストが流れます。注意したいのは、この設定の実体がブラウザの再利用である点です。[settingsView.ts](https://github.com/microsoft/playwright-vscode/blob/v1.1.20/src/settingsView.ts)では設定名が `reuseBrowser` で、ラベルの横に「one worker」と書かれ、ツールチップには再利用すると並列実行が無効になると記されています。

そのため、オンのまま全件を流すとワーカー1つで順番に実行され、CLIより大幅に遅くなります。1件を見ながら直すときだけオンにし、全件はオフで流す運用が無難です。開いたブラウザは「Close all Playwright browsers」で閉じます。

### Show trace viewerで失敗したステップの画面と通信を確かめる

「Show trace viewer」をオンにすると、テストが終わった時点でトレースが自動で開きます。[公式のTrace viewerページ](https://playwright.dev/docs/trace-viewer)にあるとおり、操作ごとのDOMスナップショット、ネットワークの要求と応答、コンソールのログ、対応するソースの行を1画面で確かめられる構成です。たまにしか落ちないテストは止めると再現しないことがあり、トレースを後から読むほうが早く原因に届きます。

## Pick locatorとRecord at cursorでテストコードを生成する手順

テストの土台は録画で作り、細部は手で整えます。生成の仕組みは[公式のTest generatorページ](https://playwright.dev/docs/codegen)にあるcodegenと同じで、CLIで `npx playwright codegen` を叩いた場合との違いは、生成先がエディタのファイルになることです。CLI側のオプションは[Playwright CLIコマンド一覧](https://www.issoh.co.jp/tech/details/17730/)で確かめられます。

### 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の使い方](https://www.issoh.co.jp/tech/details/6230/)で解説しています。

### 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の使い方](https://www.issoh.co.jp/tech/details/19781/)で比べられます。

### Update methodの既定値は3wayでCLIのpatchと異なる点に注意

SETTINGS欄の下にある「Update snapshots」と「Update method」は、CLIの `--update-snapshots` と `--update-source-method` に当たります。拡張の既定値はUpdate snapshotsがmissing、Update methodが3wayです。[公式のCommand lineページ](https://playwright.dev/docs/test-cli)によると、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](https://playwright.dev/docs/test-global-setup-teardown)を最初の実行で1度だけ流し、その後のテスト実行では使い回します。[testModel.ts](https://github.com/microsoft/playwright-vscode/blob/v1.1.20/src/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のテスト機能](https://code.visualstudio.com/docs/python/testing)でテストを流し、ロケーターの確認は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実行ガイド](https://www.issoh.co.jp/tech/details/19785/)で扱っています。

### VS Code以外のエディタが混ざるチームはUIモードを共通の手段にする

開発者がWebStormやVimなどVS Code以外のエディタも使うチームでは、拡張を前提にした手順書は半分の人に通じません。`npx playwright test --ui` で開くUIモードはエディタを選ばず、テストの選択・ウォッチ・トレースの確認・ロケーターの取得まで同じことができます。この場合、手順書の基準にするのはUIモードで、拡張の位置づけはVS Codeを使う人のための便利機能です。UIモードの操作は[Playwrightの使い方入門](https://www.issoh.co.jp/tech/details/19779/)で解説しています。

テストを書く人が1〜2人で全員VS Codeなら、拡張を前提にしてextensions.jsonとsettings.jsonをコミットするのが早道です。CIの構成やテスト運用の設計まで外部と組む場合は、[DevOps・CI/CD導入支援](https://www.issoh.co.jp/service/system/devops/)のように、パイプラインとテスト自動化をまとめて扱える体制を選ぶと、手元の道具とCIの条件をそろえるところまで一緒に設計できます。E2Eで守る範囲の決め方は[E2Eテストとは？結合テストとの違いとベストプラクティス](https://www.issoh.co.jp/tech/details/5470/)を参照してください。

## よくある質問

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の最新バージョンの確認方法・アップデート手順](https://www.issoh.co.jp/tech/details/11318/)にあります。拡張は自動更新に任せて構いません。

## 関連記事

- [Playwrightの使い方入門：E2Eテストを初期化から実行・CIまで書く手順【1.65対応】](https://www.issoh.co.jp/tech/details/19779/)：拡張で流す前のテストの書き方とUIモードの操作
- [Playwright（プレイライト）とは？仕組み・できること・Seleniumとの違いを解説](https://www.issoh.co.jp/tech/details/3167/)：ブラウザとテストランナーの関係を押さえる前提知識
- [Playwright CLIコマンド一覧｜test・codegen・installと1.63の新オプション](https://www.issoh.co.jp/tech/details/17730/)：拡張のボタンに当たるCLIのコマンドとオプション
- [Playwright aria snapshotの使い方｜toMatchAriaSnapshotの書き方と更新手順【1.64対応】](https://www.issoh.co.jp/tech/details/6230/)：Aria欄で確かめたYAMLを期待値にする書き方
- [Playwright Docker実行ガイド：公式イメージでのテストとCI組み込み・詰まり所【1.65対応】](https://www.issoh.co.jp/tech/details/19785/)：手元とCIの実行条件をコンテナでそろえる方法

---

出典: [Playwright VS Code拡張の使い方：テスト実行・デバッグ・Pick locatorと録画の手順【1.65対応】](<https://www.issoh.co.jp/tech/details/19789/>)（株式会社一創）