テストをローカルで書き込み、デバッグ、実行する

この記事では、完全なローカル開発ループ (エディターでのテストの記述、ライブ Power Platform 環境に対するテストの実行、Playwright の組み込みツールを使用したエラーのデバッグ) について説明します。 Claude Code と GitHub Copilot から AI の支援を受けます。

前提条件

開始する前に、次のツールとアクセス権があることを確認します。

Node.js 18 以降
VS Code (推奨) または TypeScript 対応エディター
アプリがデプロイされた Power Platform 環境
構成された認証 - 認証ガイドを参照

ワークスペースを設定する

次の手順に従って、リポジトリを複製し、依存関係をインストールし、VS Code でプロジェクトを開きます。

リポジトリを複製します。

git clone https://github.com/microsoft/power-platform-playwright-samples.git
cd power-platform-playwright-samples

依存関係をインストールします。

node common/scripts/install-run-rush.js install

推奨される VS Code 拡張機能をインストールします。
- VS Code のプレイライトテスト (ms-playwright.playwright) - サイドバーからテストを実行およびデバッグする
- GitHub Copilot (GitHub.copilot) - エディターでの AI テスト作成
- ESLint (dbaeumer.vscode-eslint) - インラインリンティング

ワークスペースを開きます。

code power-platform-playwright-samples.code-workspace

テストを記述する

このセクションでは、テストファイルを配置する場所、テストファイルを構成する方法、セレクターに必要なコントロール名を見つける方法について説明します。

ファイルの名前付けと場所

テストファイルを packages/e2e-tests/tests/に配置します。名前付けパターンの <feature>.test.tsを使用します。

packages/e2e-tests/
└── tests/
    └── northwind/
        ├── canvas/
        │   └── canvas-app-crud.test.ts
        └── mda/
            ├── model-driven-crud.test.ts
            └── custom-page-crud.test.ts

基本的なテスト構造

すべてのテストファイルは同じパターンに従います。ツールキットをインポートし、 beforeEachでアプリを起動し、アサーションを使用して個々の test() ブロックを書き込みます。

import { test, expect } from '@playwright/test';
import {
  AppProvider,
  AppType,
  AppLaunchMode,
  buildCanvasAppUrlFromEnv,
} from 'power-platform-playwright-toolkit';

test.describe('Feature name', () => {
  test.beforeEach(async ({ page, context }) => {
    const app = new AppProvider(page, context);
    await app.launch({
      app: 'My App',
      type: AppType.Canvas,
      mode: AppLaunchMode.Play,
      skipMakerPortal: true,
      directUrl: buildCanvasAppUrlFromEnv(),
    });
  });

  test('should do something', async ({ page }) => {
    const canvasFrame = page.frameLocator('iframe[name="fullscreen-app-host"]');
    await canvasFrame
      .locator('[data-control-part="gallery-item"]')
      .first()
      .waitFor({ state: 'visible', timeout: 60000 });

    // your assertions here
  });
});

Power Apps キャンバスアプリでコントロール名を検索する

キャンバスコントロールのセレクターを記述するには、 data-control-name 値が必要です。

ブラウザーで再生モードでアプリを開きます。
F12 キーを押して DevTools を開きます。
[ インスペクター ] ([要素] タブ) をクリックします。
コントロールの上にマウスポインターを置くと、属性 data-control-name="Button1" が表示されます。

または、Claude Code または GitHub Copilot に、Playwright MCP サーバーを使用して DOM を検査するように依頼します。

テストを実行する

Playwright CLI を使用して、コマンドラインからテストを実行できます。次のサブセクションでは、一般的なオプションを示します。

すべてのテストを実行する

プロジェクト内のすべてのテストを実行するには、次のコマンドを使用します。

cd packages/e2e-tests
npx playwright test

特定のファイルを実行する

ファイルパスを渡して、そのファイル内のテストのみを実行します。

npx playwright test tests/northwind/canvas/canvas-app-crud.test.ts

名前で特定のテストを実行する

--grepを使用して、名前がパターンと一致するテストのみを実行します。

npx playwright test --grep "should create an account"

特定のプロジェクト (キャンバスまたは MDA) を実行する

--projectを使用して、Playwright 構成で定義されている特定のアプリの種類を対象とします。

npx playwright test --project=canvas
npx playwright test --project=mda

Playwright UI を使用して実行する (ローカル開発に推奨)

Playwright UI は、タイムトラベルデバッグを備えた視覚的なテストランナーを提供します。

npx playwright test --ui

UI を使用して次の操作を行います。

合格または失敗の状態で一覧表示された各テストを確認する
テストをクリックして段階的に再生する
各手順でスクリーンショット、トレース、およびネットワーク要求を表示する
1 回のクリックで 1 つのテストを再実行する

ヘッディッドモードで実行する

ヘッドモードでは、表示されているブラウザーウィンドウが開き、テストがアプリと対話するのを見ることができます。

npx playwright test --headed

ヘッドモードを使用すると、テストの実行時にブラウザーを監視できます。各ステップでアプリがどのように表示されるかを理解するのに役立ちます。

スローモーションで実行する

スローモーションでは、各Playwrightアクションの間に遅延が追加されるため、視覚的に追跡できます。

npx playwright test --headed --slow-mo=500

各アクションは 500 ミリ秒遅れるので、テストの実行を視覚的に簡単に実行できます。

デバッグテスト

テストが失敗した場合は、これらのツールを使用して実行を順に追って確認し、DOMを検査し、トレースを確認します。

Playwright Inspector を使用したデバッグ

インスペクターは実行を一時停止し、次の操作を順番にステップ実行できます。

npx playwright test --debug

または、中断したい箇所でテストに await page.pause() を追加します。

test('should do something', async ({ page }) => {
  const canvasFrame = page.frameLocator('iframe[name="fullscreen-app-host"]');
  await canvasFrame.locator('[data-control-part="gallery-item"]').first()
    .waitFor({ state: 'visible', timeout: 60000 });

  await page.pause(); // <-- execution pauses here; Inspector opens

  await canvasFrame.locator('[data-control-name="MyButton"]').click();
});

一時停止すると、インスペクターに次の情報が表示されます。

ブラウザーで強調表示されている現在のロケーター
任意の要素をクリックしてそのセレクターを取得するロケーターピッカーツール
進むと戻る操作のコントロール

VS Code でのデバッグ

Playwright Test for VS Code 拡張機能により、テスト サイドバー (beaker アイコン) が追加されます。そこから、次のことができます。

テストの横にある再生ボタンをクリックして実行します。
バグアイコンをクリックしてデバッグモードで実行します。VS Code ブレークポイントは機能します。
テストの任意の行にブレークポイントを設定し、[ デバッグテスト] を選択すると、VS Code がそこで一時停止します。

VS Code デバッガーを手動で構成するには、 .vscode/launch.jsonに追加します。

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Playwright Test",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/.bin/playwright",
      "args": ["test", "--project=canvas", "--headed", "--debug"],
      "cwd": "${workspaceFolder}/packages/e2e-tests",
      "console": "integratedTerminal",
      "env": {
        "PWDEBUG": "1"
      }
    }
  ]
}

HTML レポートを読み取る

テストの実行後、HTML レポートを開きます。

npx playwright show-report

レポートには次の情報が表示されます。

各テストの合格または失敗の状態
失敗時にキャプチャされたスクリーンショット
各テストの完全なトレース ( trace: 'on-first-retry' が設定されている場合)

トレースビューアーを読み取る

トレースには ZIP ファイルが記録されます。このファイルを使用して、テスト実行を段階的に再生できます。

npx playwright show-trace test-results/<test-folder>/trace.zip

または、ZIP ファイルを trace.playwright.dev にドラッグします。

トレースビューアーには、次の情報が表示されます。

タイミングを持つすべての Playwright アクション
各アクションの前後の DOM スナップショット
ネットワーク要求
コンソールのログとエラー

Tip

デバッグ中にtrace: 'on'にplaywright.config.tsを設定して、再試行だけでなく、すべての実行のトレースをキャプチャします。

Claude Code を使用した書き込みとデバッグ

Claude Code は、(Playwright MCP サーバー経由で) プロジェクトファイル、シェル、ブラウザーへのフルアクセスを使用してターミナルで実行される AI コーディングアシスタントです。

このプロジェクトのクロードコードを設定する

Claude Code をインストールし、Playwright MCP サーバーに接続するには、次の手順を実行します。

Claude Code をインストールします。
```
npm install -g @anthropic-ai/claude-code
```
プロジェクト規則を使用して packages/e2e-tests/CLAUDE.md を作成します。 AI エージェントのカスタム手順を参照してください。

Playwright MCP サーバーを ~/.claude/settings.jsonに追加します。

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp"]
    }
  }
}

リポジトリルートから Claude Code を開始します。
```
claude
```

Claude Code を使用して新しいテストを作成する

Claude Code セッションで、目的のテストについて説明します。

アカウントキャンバスアプリ用の Playwright テストを作成します。ギャラリーが開き、[追加] をクリックし、アカウント名に一意の値を入力して保存し、ギャラリーに新しい項目が表示されていることを確認します。 packages/e2e-tests/tests/accounts/accounts.test.tsに配置します。

Claude Code は、 CLAUDE.md 規則を読み取り、テストファイルを書き込み、確認します。実行する前にファイルを確認します。

Claude Code にアプリの検査を依頼する

プレイライト MCP サーバーが接続されている場合:

" <your-canvas-app-url>に移動します。 iframe[name='fullscreen-app-host']内の DOM を調べて、ギャラリー、追加ボタン、アカウント名の入力のdata-control-name値を見つけます。次に、それぞれのセレクターを書き込みます。

Claude Code はブラウザーを開き、移動して DOM を検査し、正確なセレクターを返します。

Claude Code で失敗したテストを修正する

テスト出力を Claude Code に貼り付けます。

"このテストは、次のエラーで失敗しています: [貼り付けエラー]。テストファイルを次に示します。[ファイルを貼り付けるか参照します]。問題を診断して修正してください。

Claude Code はファイルを読み取り、エラーを理解し、修正プログラムを提案します。多くの場合、間違ったセレクター、不足している waitFor、データの競合などの問題をキャッチします。

Claude Code からテストを実行する

Claude Code では、テストを直接実行できます。

" npx playwright test tests/accounts/accounts.test.ts --headed を実行し、合格したかどうかを教えてください。"

Claude Code はコマンドを実行し、出力を読み取り、結果を報告します。テストが失敗した場合は、直ちに修正プログラムを提案できます。

GitHub Copilotを使用した書き込みとデバッグ

GitHub Copilotは VS Code と JetBrains IDE に直接統合され、インライン入力候補とチャットパネルが提供されます。

このプロジェクトのCopilotを有効にする

Copilotをアクティブ化し、プロジェクト固有の手順を構成するには、次の手順を実行します。

VS Code に GitHub Copilot 拡張機能をインストールします。
プロジェクト規則を使用して .github/copilot-instructions.md を作成する - AI エージェントのカスタム手順を参照してください。
テストファイルを開く - Copilot既存のテストを読み取り、パターンを学習します。

インライン補完を使用する

入力すると、Copilotはコンテキストに基づいてテストコードを完了します。 test() ブロックの入力を開始し、Tab キーを押して同意します。

test('should filter orders by keyword', async ({ page }) => {
  // Copilot suggests: await mda.grid.filterByKeyword('ORD-001');

表示できる既存のテストが多いほど、提案が優れています。

Copilot Chatを使用してテストを生成する

Copilot Chat (Ctrl+Shift+I) を開き、次の質問をします。

"@workspace注文モデル駆動型アプリに移動し、'ORD-001' でグリッドをフィルター処理し、最初のレコードを開き、ノートフィールドを更新し、保存し、フォームが汚れなくなったことを確認するテストを記述します。"

Copilotは、@workspace を介してコードベースを読み取り、既存のスタイルに一致するテストを生成します。

Copilotを使用して失敗したテストを修正する

Copilot Chatを使用して、合格していないテストを診断して修正します。

失敗したテストファイルを開きます。
失敗したテスト関数を選択します。
Copilot Chatを開き、次の質問をします。

"このテストを修正します。ギャラリーセレクターがタイムアウトするため、失敗します。ギャラリーは、Dataverse データを読み込むのに最大 60 秒かかります。"

Copilotは、waitFor タイムアウトを更新し、他の改善を提案する可能性があります。

Copilotを使用してエラーを説明する

エラーメッセージをCopilot Chatに貼り付けます。

「Power Platform キャンバスアプリのテストのコンテキストで、この Playwright エラーの原因と解決方法を説明します: TimeoutError: locator.waitFor: Timeout 30000ms exceeded」

Copilotエラーについて説明し、キャンバス iframe のスコープ設定とタイムアウト設定に関する具体的なアドバイスを提供します。

Copilotを使用してセレクターを生成する

ブラウザーで DevTools を開き、キャンバス DOM が表示されたら、関連する HTML をコピーして、Copilot に質問します。

「Power Apps キャンバスアプリから取得したこの HTML に基づき、iframe[name='fullscreen-app-host'] のスコープ内で保存ボタンをクリックする Playwright ロケーターを作成します。」

Playwright テストに推奨されるローカル開発ワークフロー

このエンドツーエンドのワークフローでは、初期セットアップからテストのコミットまでの一般的な手順について説明します。

1 回設定します。.envを構成し、auth:headfulを実行し、サンプルテストに合格したかどうかを確認します。
最初に検査します。 アプリを開き、DevTools または Playwright MCP サーバーを使用してコントロール名を検索します。
AIで書き込む: Claude Code または Copilot Chat を使用して、説明からテストを構築します。
UI で実行: npx playwright test --ui
Inspector を使用したデバッグ:await page.pause() 障害個所で状態をライブで検査します。
トレースを読み取る: CI でテストが不安定な場合は、トレース zip を開いて、何が起こったかを正確に確認します。
選択的にコミットする: テストファイルのみをステージングします。 .env や .playwright-ms-auth/をコミットしないでください。

一般的なローカルの問題のトラブルシューティング

この表を使用して、テストをローカルで実行するときに最も頻繁に発生する問題を診断して解決します。

症状	考えられる原因	修正
`Storage state file does not exist`	認証が実行されない	`npm run auth:headful`
`Authentication tokens have expired`	セッションの期限切れ (>1 時間)	再実行 `npm run auth:headful`
`TimeoutError` のギャラリーで	Dataverse の読み込み時間	タイムアウトを次の値に増やします `60000`
`Strict mode violation` — N 個の要素	セレクターが広すぎる	`.filter()`または`.first()`を追加
テストがローカルで成功し、CI で失敗する	タイミングまたは環境の相違	`await page.waitForLoadState()`の追加、再試行の確認
`ERR_ABORTED` モデル駆動型アプリの認証中	前回のブラウザープロセスが稼働中	数秒待ってから再試行してください `npm run auth:mda:headful`
VS Code Playwright 拡張機能でテストが見つからない	間違って `testDir`	`playwright.config.ts`を確認→`testDir: './tests'`