puppeteerとは

他の記事とかでも書いてあると思いますが、一応説明をしておくと、puppeteerはDevToolsプロトコルを使ってChromiumもしくはChromeを管理する高レベルAPIを提供するNodeライブラリです。

今回はこのpuppeteerが面白そうだったので、このライブラリを調べたり使ったりしたことを残していきたいと思います。今回はpuppeteerクラスをやっていきたいと思います。

puppeteerクラス

このクラスはChromiumインスタンスを立ち上げるためのメソッドを提供してくれます。この辺りは設定云々のところなので実証していくところはないです。

メソッドはconnect、createBrowserFetcher、defaultArgs、executablePath、launchの5つ。それぞれ説明していきます。

connectメソッド

実際のURLを指定するかWebsocketのURLを指定してブラウザインスタンスにつなげるメソッド。
このメソッドは存在しているChromiumインスタンスにのみに接続します。

puppeteer.connect(options)

options↓
browserWSEndpoint ?string 接続するブラウザwebsocketエンドポイント。
browserURL        ?string 形式がhttp://${host}:${port}である接続するブラウザURL。 
ignoreHTTPSErrors boolean ナビゲーション中にHTTPSエラーを無視するかどうかを決められます。デフォルトはfalse。
defaultViewport   ?Object さまざまなページのviewportを準備します。デフォルトのviewportは800x600。nullはデフォルトのviewportを無効にします。
    width             number  ピクセルでのページのwidth。
    height            number  ピクセルでのページのheight。
    deviceScaleFactor number  デバイスの（dprとして考えることができる）スケール係数を指定できます。デフォルトは1。
    isMobile          boolean メタviewportタグを考慮するかどうかを決めることができます。デフォルトはfalse。
    hasTouch          boolean viewportがタッチイベントをサポートしている場合に指定することができます。デフォルトはfalse。
    isLandscape       boolean viewportがランドスケープモードである場合に指定することができます。デフォルトはfalse。 
    slowMo            number  指定されたミリ秒単位でPuppeteerオペレーションを遅くします。
transport         ConnectionTransport Puppeteerのカスタムトランスポートオブジェクトを指定することができます。このプロパティは実験的なものです。（2020年6月時点）
product           string 可能な値はchrome、firefox。デフォルトはchrome。

createBrowserFetcherメソッド

ChromiumもしくはFirefoxのダウンロードホストやダウンロードフォルダを設定できるメソッド。

puppeteer.createBrowserFetcher([options])

options↓
host     string 使用するダウンロードホスト。デフォルトはhttps://storage.googleapis.com。もしproduct（さっきのconnectメソッドで指定するなど）がfirefoxである場合はデフォルトはhttps://archive.mozilla.org/pub/firefox/nightly/latest-mozilla-central。
path     string ダウンロードフォルダのパス。デフォルトは<root>/.local-chromiumで、<root>はpuppeteerのパッケージルート（大体の場合はnode_modules内のpuppeteerフォルダになってる）。もしproductがfirefoxの場合、デフォルトは<root>/.local-firefox。
platform <"linux"|"mac"|"win32"|"win64"> 現在のプラットフォーム。可能な値はmac、win32、win64、linux。デフォルトは現在のプラットフォーム。
product  <"chrome"|"firefox"> 起動するためのproduct。可能な値はchrome、firefox。デフォルトはchrome。

defaultArgsメソッド

ブラウザを起動させるときの初期引数を設定するメソッド。

puppeteer.defaultArgs([options])

options↓
headless    boolean headlessモードでブラウザを起動するかどうかを設定することができます。デフォルトはdevtoolオプションがtrueである限りはtrue。
args        Array<string> ブラウザインスタンスに渡すために追加の引数を設定することができます。Chromiumフラグは参考文献で参照してください。
userDataDir string ユーザーデータディレクトリのパス。
devtools    boolean 様々なタブのDevToolパネルを自動でオープンするかどうかを決めることができます。もしこのオプションがtrueなら、headlessオプションはfalseになります。

executablePathメソッド

Puppeteerがバンドルされたブラウザを見つけるために期待するパスを取得するメソッド。

launchメソッド

基本的にconnectメソッドとほとんど変わらないですが、connectメソッドよりすこしできることが多くなってます。このメソッドはChromiumインスタンスを起動した後に接続をします。

puppeteer.launch([options])

options↓
product           string 起動するブラウザ。現時点だと、この値はchromeもしくはfirefoxのどちらか。
ignoreHTTPSErrors boolean ナビゲーション中にHTTPSエラーを無視するかどうかを決めることができます。デフォルトはfalse。
headless          boolean headlessモードでブラウザを起動するかどうかを設定することができます。デフォルトはdevtoolオプションはtrueである限りはtrue。
executablePath    string バンドルされたChromiumの代わりの実行可能なブラウザのパス。もしexecutablePathが相対パスなら、現在の作業ディレクトリを基準にして解決されます。注意：PuppeteerはバンドルされているChromiumでの動作のみが保証されていて、この設定は自己責任での使用です。
slowMo            number 指定されたミリ秒単位でPuppeteerオペレーションを遅くします。
defaultViewport   ?Object さまざまなページのviewportを準備します。デフォルトのviewportは800x600。nullはデフォルトのviewportを無効にします。
    width             number  ピクセルでのページのwidth。
    height            number  ピクセルでのページのheight。
    deviceScaleFactor number  デバイスの（dprとして考えることができる）スケール係数を指定できます。デフォルトは1。
    isMobile          boolean メタviewportタグを考慮するかどうかを決めることができます。デフォルトはfalse。
    hasTouch          boolean viewportがタッチイベントをサポートしている場合に指定することができます。デフォルトはfalse。
    isLandscape       boolean viewportがランドスケープモードである場合に指定することができます。デフォルトはfalse。 
args              Array<string> ブラウザインスタンスに渡すために追加の引数を設定することができます。Chromiumフラグは参考文献で参照してください。
ignoreDefaultArgs boolean|Array<string> もしtrueなら、puppeteer.defaultArgs()を使わないでください。もし配列で定義する場合、指定されたデフォルトの引数を除外します。デフォルトではfalseです。
handleSIGINT      boolean Ctrl-Cのブラウザプロセスを閉じます。デフォルトではtrueです。
handleSIGTERM     boolean SIGTERMのブラウザプロセスを閉じます。デフォルトではtrueです。
handleSIGHUP      boolean SIGHUPのブラウザプロセスを閉じます。デフォルトではtrueです。
timeout           number ブラウザインスタンスの起動を待機する最大時間（ミリ秒）。デフォルトは30000（30秒）。タイムアウトを無効にするには、値を0にすること。
dumpio            boolean process.stdoutとprocess.stderr内のブラウザプロセスのstdoutとstderrをパイプするかどうかを設定します。デフォルトではfalseです。
userDataDir       string ユーザーデータディレクトリのパス。
env               Object ブラウザに見ることができる環境変数を指定します。デフォルトではprocess.env。
devtools          boolean 様々なタブのDevToolパネルを自動でオープンするかどうかを決めることができます。もしこのオプションがtrueなら、headlessオプションはfalseになります。
pipe              boolean WebSocketの代わりのパイプを介してブラウザと接続します。デフォルトではfalseです。
extraPrefsFirefox Object Firefoxに渡すことができる追加のパフォーマンスを設定できます。

さいご

次の記事ではBrowserFetcherクラスをやっていきます。おそらく実証なんかもこの辺からだと思います。

参考文献

devtools protocol -- https://chromedevtools.github.io/devtools-protocol/

メタデータエンドポイント -- https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target

Getting Started with Headless Chrome（日本語はバージョンが古い） -- https://developers.google.com/web/updates/2017/04/headless-chrome

Chromiumフラグ -- https://peter.sh/experiments/chromium-command-line-switches/

ユーザーデータディレクトリ -- https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md