Sentry のブラウザ向け SDK の統合テストは、内部で Playwright を使用して実行される。テストは Chromium、Firefox、および WebKit の最新安定版上で並列実行される。

https://playwright.dev/

ディレクトリ構造

テストは機能単位（例: breadcrumbs や onunhandledrejection）でグループ化されている。各グループ内には、個別のテストケースとその補助リソースを含むサブディレクトリが存在する。

各テストグループには、以下のデフォルトファイルが用意されている:

• template.hbs: HTML スケルトン
• init.js: Sentry 初期化スクリプト（Sentry.init() を含む）

テストケースのディレクトリにこれらのファイルが存在しない場合、グループレベルのデフォルトが使用される。

subject.js はテスト対象の環境をセットアップするロジックを含む。これはオプションであり、グループまたは個別テストケースに定義可能。ただし必須ではなく、代わりに utils/helpers.ts 内の injectScriptAndGetEvents を使って動的にスクリプトを注入することもできる。

各テストケースには必ず test.ts が必要で、ここにアサーション（および必要に応じたスクリプト注入ロジック）を記述する。個別の template.hbs、init.js、subject.js が定義されていれば、それらはグループのデフォルトより優先される。

suites/
└── breadcrumbs/
    ├── template.hbs
    ├── init.js
    ├── subject.js
    └── click_event_tree/
        ├── template.hbs
        ├── init.js
        ├── subject.js
        └── test.ts

テストの記述方法

ヘルパー関数

utils/helpers.ts には、Playwright のネイティブ API をラップしたヘルパー関数が定義されており、test.ts 内で利用可能。共通の操作パターンはすべてこのヘルパーに抽象化することが推奨される。

フィクスチャ

フィクスチャにより、テスト全体または個別テストでグローバルな状態や設定を提供できる。utils/fixtures.ts は Playwright の test() 関数を拡張しており、追加のフィクスチャを提供する。すべてのテストは @playwright/test ではなく、このカスタム関数 sentryTest をインポートして使用する必要がある。

https://playwright.dev/docs/api/class-fixtures

ローカルでのテスト実行

Chromium でテストを実行する:

yarn test

他のブラウザで実行するには:

yarn test --browser='firefox'
yarn test --browser='webkit'

全ブラウザで実行:

yarn test --browser='all'

テストタイトルでフィルタリング:

yarn test -g "XMLHttpRequest without any handlers set"

その他の CLI オプションについては Playwright 公式ドキュメントを参照。

https://playwright.dev/docs/test-cli

トラブルシューティング

不安定なテスト

ランダムに失敗し、「Page Closed」や「Target Closed」といったエラーが出る場合、多くのケースで subject.js 内のページ操作と Sentry のイベント収集処理との間に競合状態が発生している。まず utils/helpers.ts の既存ヘルパーで代替できないか確認し、不可であれば Promise.all を使って Playwright の非同期操作を適切に調整することを検討する。手動での setTimeout などによるウェイトは避けるべきである。

http://mdn.io/promise.all

ビルドエラー

テスト実行前に各ケースのページが dist ディレクトリ下にビルドされる。ビルドに失敗する場合は以下の点を確認:

• テストグループにデフォルトの template.hbs と init.js が存在するか
• テストケースに subject.js が正しく定義されているか
• init.js または subject.js に Node.js 専用コードが含まれていないか
• Webpack 設定が有効か

実際の開発フロー

Sentry JavaScript リポジトリをクローン:

git clone https://github.com/getsentry/sentry-javascript.git
cd sentry-javascript

依存パッケージをインストール・ビルド:

yarn
yarn lerna bootstrap
yarn build

統合テストディレクトリに移動して実行:

cd packages/integration-tests
yarn test

Playwright Inspector を起動してデバッグするには:

PWDEBUG=1 yarn test