メインコンテンツへスキップ
バージョン: 22.5.0

貢献

まず最初に、Puppeteerにご興味をお持ちいただきありがとうございます！皆様からのパッチや貢献を歓迎します！

貢献者ライセンス契約​

このプロジェクトへの貢献には、貢献者ライセンス契約が必須です。あなた（またはあなたの雇用主）は貢献に対する著作権を保持しますが、これは単にプロジェクトの一部としてあなたの貢献を使用し、再配布する許可を私たちに与えるものです。<https://cla.developers.google.com/> にアクセスして、現在ファイルにある契約を確認するか、新しい契約に署名してください。

一般的にCLAは一度提出するだけで済みます。そのため、すでに（別のプロジェクトのものであっても）提出済みの場合は、再度提出する必要はないでしょう。

はじめに​

  1. このリポジトリをクローンします。

    git clone https://github.com/puppeteer/puppeteer
    cd puppeteer

    または

    Open in GitHub Codespaces

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

    npm install
    # Or to download Firefox by default
    PUPPETEER_PRODUCT=firefox npm install

  3. すべてのパッケージをビルドします

    npm run build

  4. すべてのテストを実行します

    npm test

単一のパッケージのビルド​

単一のパッケージをビルドするには、以下を実行できます。

npm run build --workspace <package> # e.g. puppeteer

これにより、依存するすべてのパッケージが自動的にビルドされるため、単一のパッケージを指定するだけで十分です。これはすべて、wireit のおかげで、GNU Make と同様に動作します。

ウォッチモード​

パッケージを継続的にビルドするには、以下を実行できます。

npm run build --watch --workspace <package> # e.g. puppeteer

ウォッチ対象として単一のパッケージのみを指定する必要があります。そうしないと、期待どおりに動作しません。上記のように wireit のおかげで、変更が発生すると、すべての依存関係がビルドまたは再ビルドされます（必要な場合）。

古い成果物の削除​

生成された一部の成果物（packages/puppeteer-core/src/types.ts など）は、ビルドシステムでキャプチャできない複雑な条件（異なるファイルの名前など）に依存しているため、古くなる可能性があります。成果物をクリーンアップするには、以下を実行できます。

npm run clean
# or specify the package
npm run clean --workspace <package>

包括的なテスト​

npm test の他にも、CI を通して通常チェックされるいくつかの npm スクリプト があります。

  • test-install - puppeteer および puppeteer-core が正しくインストールされ、機能するかどうかをテストします。
  • test-types - tsd を使用して、puppeteer の TypeScript 型をテストします。
  • test:chrome:** - Chromium で puppeteer をテストします。
  • test:firefox:** - Firefox で puppeteer をテストします。
  • unit - ユニットテストを実行します。

デフォルトの npm test では test:{chrome,firefox}:headless が実行されます。これは一般的に十分です。

Puppeteer は、TestExpectations.json を参照して、特定のテスト結果が期待どおりかどうかを確認する、Mocha の上に構築されたカスタムテストランナーを使用しています。テストランナーの詳細については、tools/mocha-runner を参照してください。

ユニットテスト​

コードのみをテストするテスト（実行中のブラウザなし）は、テスト対象のクラスの横に配置され、Node テストランナーを使用して実行されます（Node 20以降が必要です）。

npm run unit

コードレビュー​

プロジェクトメンバーによる提出を含め、すべての提出にはレビューが必要です。この目的のために GitHub プルリクエストを使用します。プルリクエストの使用方法の詳細については、GitHubヘルプ を参照してください。

コードスタイル​

私たちのコーディングスタイルは、.eslintrc（ESLint）および .prettierrc.cjs（Prettier）で完全に定義されています。

コードは PR に対して自動的にチェックされます。以下のコマンドを実行して、手動でコードをチェックできます。

npm run lint

エラーが返された場合は、以下を使用して修正を試みることができます。

npm run format

プロジェクト構成​

以下は、Puppeteer の主要なフォルダーの説明です。

  • packages には、すべての公開ソースコードが含まれています。
  • test には、すべてのテストソースコードが含まれています。
  • test-d には、tsd を使用した型テストが含まれています。
  • tools には、ビルドなどで使用されるさまざまなスクリプトが含まれています。
  • tools/mocha-runner - テストランナーのソースコードが含まれています。

API ガイドライン​

新しい API メソッドを作成する際は、以下を考慮してください。

  • 必要な最小限の情報だけを公開します。迷った場合は、新しい情報を公開しないでください。
  • メソッドはゲッター/セッターよりも優先されます。
    • 唯一の例外は、名前空間（例：page.keyboard および page.coverage）です。
  • すべての文字列リテラルは小文字にする必要があります。これには、イベント名とオプション値が含まれます。
  • 非常に需要がない限り、「砂糖」API（ユーザー空間で簡単に実装できる API）の追加は避けてください。

コミットメッセージ​

コミットメッセージは、Conventional Commits 形式に従う必要があります。

特に、破壊的な変更はコミットメッセージフッターに「BREAKING CHANGE:」として明確に記載する必要があります。例：

fix(page): fix page.pizza method

This patch fixes page.pizza so that it works with iframes.

Issues: #123, #234

BREAKING CHANGE: page.pizza now delivers pizza at home by default.
To deliver to a different location, use the "deliver" option:
  `page.pizza({deliver: 'work'})`.

ドキュメントの作成​

ドキュメントは、npm run docs を介して TSDoc コメントから生成されます。マージ時にドキュメントサイトに自動的に公開され、リリース時にバージョン管理されます。

つまり、docs/api ファイル内の Markdown を手動で変更しないでください。

TSDoc コメントの作成​

Puppeteer へのすべての変更は、TSDoc コメントを使用して徹底的にドキュメント化する必要があります。正確な構文については、API Extractor ドキュメントを参照してください。

  • すべての新しいメソッドには、公開 API の一部であるかどうかによって、@public または @internal をタグとして追加する必要があります。
  • コメント内の各行は、90文字以内にしてください（これを超えると ESLint が警告します）。VSCode ユーザーの場合は、Rewrap プラグイン を強くお勧めします！

ドキュメントサイトをローカルで実行する​

  1. ルートで、npm i --ignore-scripts を使用してすべての依存関係をインストールします。
  2. npm run docs を実行すると、すべての .md ファイルが puppeteer/docs/api に生成されます。
  3. puppeteer/website で npm i を実行します。
  4. puppeteer/website で npm start を実行します。

新しい依存関係の追加​

すべての依存関係（インストールと開発の両方）について：

  • 目的の機能が簡単に実装できる場合は、依存関係を追加しないでください。
  • 依存関係を追加する場合は、適切にメンテナンスされ、信頼できるものでなければなりません。

新しいインストール依存関係を導入するハードルは特に高くなっています。

  • プロジェクトの成功に不可欠な場合を除き、インストール依存関係を追加しないでください。

環境に依存しない依存関係については、追加の考慮事項があります。詳細については、third_party/README.md を参照してください。

テストのヒント​

  • すべての機能にはテストを伴う必要があります。
  • すべての公開 API イベント/メソッドにはテストを伴う必要があります。
  • テストは外部サービスに依存すべきではありません。
  • テストは、Mac、Linux、Win の3つのすべてのプラットフォームで動作する必要があります。これは、スクリーンショットテストにとって特に重要です。

特定の構成でテストが失敗することが予想される場合、または不安定になった場合は、TestExpectations.json を更新して、それを反映してください。TestExpectations.json の詳細については、tools/mocha-runner を参照してください。

API カバレッジ​

すべての公開APIメソッドまたはイベントは、テストで少なくとも1回は呼び出す必要があります。これを保証するために、メインのtestコマンドはテスト中にカバレッジを実行します。

Puppeteerのデバッグ​

デバッグのヒントを参照してください。

VSCode経由でのPuppeteerテストのデバッグ​

提供されているデフォルトの.vscode/launch.template.jsonを.vscode/launch.jsonにコピーし、統合されたVSCodeデバッガーを使用してテストをデバッグします。

起動する前に、以下でテストをビルドすることを忘れないでください。

npm run build --workspace @puppeteer-test/test

プロジェクトメンテナー向け

新しいChromeバージョンのロール​

1日に1回実行されるGitHubアクションがあります。このアクションには、アクションタブで見つけることができる手動トリガーがあります。

手動での手順​

tools/update_chrome_revision.mjsをローカルで実行し、コミットする必要がある変更があるかどうかを確認できます。

注：スクリプトはfetchに依存しているため、node --experimental-fetch tools/update_chrome_revision.mjsを実行する必要がある場合があります

以下の手順は、上記のスクリプトの手動バージョンです。

  1. https://googlechromelabs.github.io/chrome-for-testing/またはhttps://chromiumdash.appspot.com/で適切なChromeのrevisionとversionを見つけてください。
  2. 見つけたversion番号でpackages/puppeteer-core/src/revisions.tsを更新します。
  3. 新しいChromeとPuppeteerのversionマッピングでversions.jsを更新し、リストから次のバージョンでlastMaintainedChromeVersionを更新します。
  4. npm run checkを実行します。失敗した場合は、予想されるdevtools-protocolバージョンでpackages/puppeteer-core/package.jsonを更新し、npm installを実行して更新されたpackage-lock.jsonを生成します。
  5. npm run clean、npm install、npm run buildを実行します。
  6. npm testを実行し、すべてのテストが合格することを確認します。テストが失敗した場合は、失敗の原因となった上流側の変更を二分探索し、それに応じてテストの期待値を更新するか（意図された変更の場合）、Puppeteerの動作を変更することが望ましくない場合は、Puppeteerの変更を回避します。
  7. 変更をコミットしてプッシュし、プルリクエストを開きます。コミットメッセージには、pptr.devが正しく解析できるように、Chrome <version> (r<revision>)形式でバージョンを含める必要があります。例：feat(chrome): roll to Chrome 90.0.4427.0 (r856583)。

注：バージョンに対応するバージョンを見つけることができるもう1つの場所は、Find Releasesでr<revision>を検索することで見つけることができるomahaproxy.appspot.comです。

上流の変更の二分探索​

Chrome/Chromiumの変更を二分探索するには、https://www.chromium.org/developers/bisect-builds-py/を使用してください。

npmへのリリース​

リリースを自動化するためにrelease-pleaseを使用します。リリースを実行する必要がある場合は、プルリクエストでリリースPRを確認し、マージします。

Release Pleaseが失敗した場合​

release-pleaseが失敗した場合、以下を実行する必要があります

  1. 公開されるはずだったすべてのパッケージのCHANGELOGに不足しているものを更新します。たとえば、ヘッダーが不足している場合は、次を追加する必要がある場合があります。

    • puppeteerの場合

      ## [{NEW_VERSION}](https://github.com/puppeteer/puppeteer/compare/v{PREVIOUS_VERSION}...v{NEW_VERSION}) ({CURRENT_DATE})`

    • その他のパッケージの場合

      ## [{NEW_VERSION}](https://github.com/puppeteer/puppeteer/compare/{PACKAGE_FOLDER_NAME}-v{PREVIOUS_VERSION}...{PACKAGE_FOLDER_NAME}-v{NEW_VERSION}) ({CURRENT_DATE})

  2. 以前のリリースに従って、各パッケージのGitHubリリースを作成します。

バグトリアージのガイドライン​

confirmedまたはneeds-feedbackラベルのない受信したバグレポートを確認してください

  1. 問題をbugまたはfeatureのいずれかとしてラベル付けされていることを確認してください。
  2. 問題に明確な再現手順がない場合、または再現できない場合は、再現手順を要求し、needs-feedbackラベルを設定します。
  3. 以前にフィードバックを求めた問題についてフォローアップします（ユーザーが応答すると、GitHubで通知が表示されます）。
  4. ユーザーがフィードバックを提供しない場合、問題は最終的にstale botによって閉じられます。
  5. 問題を再現できる場合は、confirmedラベルを追加します。
  6. バグがChromium側にある場合は、対応するcrbug.comの問題を作成し、GitHubの問題にupstreamラベルを付け、コメントにcrbug.comへのリンクを投稿します。
  7. 問題がPuppeteerまたはChromiumのいずれにも関連していない場合は、問題を閉じます。
  8. 問題が不足している/不適切なドキュメントに関するものである場合は、documentationとしてラベル付けします。

PDFに関する問題

  1. 通常印刷ダイアログまたはヘッドフルを使用して問題が再現される場合は、Blink>Layoutコンポーネントに対してcrbug.comを提出してください。
  2. 問題がヘッドレスモード固有のものである場合は、Internals>Headlessコンポーネントに対してcrbug.comに問題を提出してください。