よくある質問

クロスブラウザ サポートの状況はどうなっていますか?

Firefox の公式サポートは試験運用中です。Mozilla との継続的なコラボレーションは、デベロッパーがクロスブラウザ カバレッジを想定している一般的なエンドツーエンド テストのユースケースをサポートすることを目的としています。Firefox のサポートを安定させ、不足している API についてお知らせするために、Puppeteer チームはユーザーの意見を必要としています。

Puppeteer v2.1.0 以降では、puppeteer.launch({product: 'firefox'}) を指定して、追加のカスタムパッチなしで Firefox Nightly で Puppeteer スクリプトを実行できます。
以前のテストでは Firefox のパッチ適用バージョンが必要でしたが、現在の方法は「ストック」の Firefox で機能します。

Google は、Safari などのブラウザで引き続き Puppeteer をサポートできるよう、他のブラウザ ベンダーとの連携を続けています。この取り組みには、(Chrome で使用される非標準の DevTools プロトコルに依存しない)クロスブラウザ コマンドを実行するための標準の調査も含まれています。

Puppeteer の目標と原則は何ですか?

プロジェクトの目標は次のとおりです。

  • DevTools プロトコルの機能を強調するスリムで正規のライブラリを提供します。
  • 同様のテスト ライブラリのリファレンス実装を提供する。最終的には、こうした他のフレームワークが基盤レイヤとして Puppeteer を採用する可能性があります。
  • ヘッドレス/自動化されたブラウザテストの導入を拡大する。
  • DevTools Protocol の新機能の dogfood サポートとバグ検出にご協力ください
  • ブラウザの自動テストにおける課題について詳しく学び、学習のギャップを埋めるのに役立ちます。

Google は、プロダクトに関する意思決定を促進するために、Chromium の原則を適用しています。

  • 速度: Puppeteer は、自動化されたページと比べてパフォーマンスのオーバーヘッドがほぼゼロです。
  • セキュリティ: Puppeteer は Chromium に関してオフプロセスで動作するため、悪質な可能性のあるページを安全に自動化できます。
  • 安定性: Puppeteer は不安定でなく、メモリリークが発生してはなりません。
  • シンプルさ: Puppeteer は、簡単に使用、理解、デバッグできる高レベル API を提供します。

Puppeteer は Selenium/WebDriver に代わるものですか?

いいえ。どちらのプロジェクトも、その価値は大きく異なります。

  • Selenium/WebDriver はクロスブラウザの自動化に重点を置いており、その価値提案は、すべての主要なブラウザで機能する単一の標準 API であることです。
  • Puppeteer は Chromium に重点を置いており、その価値提案は機能豊富で信頼性が高いことです。

ただし、コミュニティ主導の jest-puppeteer を使用するなど、Puppeteer を使用して Chromium に対してテストを行うことはできます。これが唯一のテスト ソリューションになるとは限りませんが、WebDriver と比べて優れている点がいくつかあります。

  • Puppeteer はセットアップなしで、最適な Chromium バージョンにバンドルされています。テストを一切実行しないよりも、Chromium のみを実行するいくつかのテストを実行することをおすすめします。
  • Puppeteer はイベント ドリブン アーキテクチャを備えており、潜在的な脆弱性の多くを取り除きます。人形師の脚本で邪悪な「sleep(1000)」なんて言わないでよ。
  • Puppeteer は、デフォルトでヘッドレスで実行されるため、高速に実行できます。Puppeteer v1.5.0 ではブラウザのコンテキストも公開されるため、テスト実行を効率的に並列化できます。
  • Puppeteer はデバッグの際に威力を発揮します。「ヘッドレス」ビットを false に設定し、「slowMo」を追加すると、ブラウザの動作を確認できます。Chrome DevTools を開いてテスト環境を調べることもできます。

Puppeteer v.XXX が Chromium v.YYY で動作しないのはなぜですか?

Google では Puppeteer を Chromium では非表示のエンティティと見なしています。Puppeteer の各バージョンには、動作することが保証されている特定のバージョンの Chromium がバンドルされています。

これは人為的な制約ではありません。実は、Puppeteer に関する多くの作業が Chromium リポジトリで行われています。典型的な事例は次のとおりです。

  1. Puppeteer のバグが報告されました
  2. これは DevTools プロトコルの問題であるため、Chromium で修正します
  3. アップストリームの修正が適用されると、更新された Chromium が Puppeteer に追加されます

ただし、Chromium ではなく Google Chrome の公式 Chrome で Puppeteer を使用するほうが望ましい場合がよくあります。これを行うには、Chrome のバージョンに対応する puppeteer-core バージョンをインストールする必要があります。

たとえば、puppeteer-core で Chrome 101 を動かすには、chrome-101 npm タグを使用します。

npm install puppeteer-core@chrome-101

Puppeteer が使用する Chromium バージョン

次のいずれかの方法でバージョンを確認します。

  • revisions.tschromium エントリを探します。対応する Chromium commit とバージョン番号を見つけるには、OmahaProxy の [Find Releases] セクションで、r で始まるリビジョンを検索します。
  • versions.jsversionsPerRelease マップを探します。Chromium と Puppeteer のバージョン間のマッピングが含まれています。注: ファイルには、Chromium が更新された Puppeteer バージョンのみが含まれています。すべての Puppeteer バージョンが表示されるわけではありません。

Puppeteer が使用する Firefox のバージョンを教えてください。

Firefox のサポートは試験運用版であるため、PUPPETEER_PRODUCT 環境変数が firefox に設定されている場合、Puppeteer は最新の Firefox Nightly をダウンロードします。revisions.tsfirefox の値が latest になっているのもそのためです。Puppeteer は特定の Firefox バージョンに関連付けられていません。

Puppeteer のインストールで Firefox Nightly を取得するには:

PUPPETEER_PRODUCT=firefox npm i puppeteer
# or "yarn add puppeteer"

ナビゲーションとは

Puppeteer の観点からは、「ナビゲーション」とはページの URL を変更するものを指します。ブラウザがネットワークにアクセスしてウェブサーバーから新しいドキュメントを取得する通常のナビゲーションのほかに、アンカー ナビゲーションHistory API の使用も含まれます。

このような「ナビゲーション」の定義により、Puppeteer はシングルページ アプリケーションとシームレスに連携します。

入力イベント「信頼できる」と「信頼できない」の違いは何ですか?

ブラウザの場合、入力イベントは、信頼するイベントと信頼できないイベントという 2 つの大きなグループに分けられます。

  • 信頼できるイベント: マウスやキーボードの使用など、ユーザーがページを操作すると生成されるイベント。
  • 信頼できないイベント: document.createEvent メソッドや element.click() メソッドなど、ウェブ API によって生成されるイベント。

ウェブサイトは次の 2 つのグループを区別できます。

  • Event.isTrusted イベントフラグを使用する
  • イベントがないかチェックします。たとえば、信頼できるすべての 'click' イベントの前には、'mousedown' イベントと 'mouseup' イベントがあります。

自動化するには、信頼できるイベントを生成することが重要です。Puppeteer で生成されたすべての入力イベントは信頼され、適切な付随イベントが発行されます。

なんらかの理由で、信頼できないイベントが必要な場合、page.evaluate を使用してページ コンテキストに移動して、疑似イベントを生成することができます。

await page.evaluate(() => {
  document.querySelector('button[type=submit]').click();
});

Puppeteer でサポートされていない機能は何ですか?

音声と動画が組み込まれているページを管理する場合、Puppeteer が期待どおりに動作しないことがあります。たとえば、動画の再生やスクリーンショットが正常に機能しないことがあります)。これには、次の 2 つの理由があります。

  • Puppeteer は(Chrome ではなく)Chromium にバンドルされています。そのため、デフォルトでは Chromium のメディア関連の制限がすべて継承されます。つまり、Puppeteer は AAC や H.264 などのライセンス取得済みの形式をサポートしていません。
    • executablePath オプションを puppeteer.launch に設定することで、Chromium ではなく、別個にインストールされたバージョンの Chrome を Puppeteer に強制的に使用させることができます。この設定は、これらのメディア形式をサポートする Chrome の公式リリースが必要な場合にのみ使用してください。
  • Puppeteer は(すべての構成で)Chrome のデスクトップ版を制御するため、モバイル版の Chrome でのみサポートされている機能はサポートされません。つまり、Puppeteer は HTTP Live Streaming(HLS)をサポートしていません。

テスト環境で Puppeteer をインストールまたは実行できません。サポートが必要な場合

さまざまなオペレーティング システム向けのトラブルシューティング ガイドで、必要な依存関係をご確認いただけます。

Chromium は npm ci の実行ごとにダウンロードされます。ダウンロードをキャッシュに保存するにはどうすればよいですか?

デフォルトのダウンロード パスは node_modules/puppeteer/.local-chromium です。このパスは PUPPETEER_DOWNLOAD_PATH 環境変数で変更できます。

Puppeteer はこの変数を使用して起動時に Chromium の実行可能ファイルの場所を解決するため、PUPPETEER_EXECUTABLE_PATH も指定する必要はありません。

たとえば、Chromium のダウンロードを ~/.npm/chromium に保持するには:

export PUPPETEER_DOWNLOAD_PATH=~/.npm/chromium
npm ci

# by default the Chromium executable path is inferred
# from the download path
npm test

# a new run of npm ci will check for the existence of
# Chromium in ~/.npm/chromium
npm ci

他にも質問がある場合は、どこに問い合わせればよいですか?

Puppeteer に関してサポートを受けるには、さまざまな方法があります。

質問を投稿する前に、これらのチャンネルを検索してください。