Playwright → Gemini Export Tool

PlaywrightのE2Eテストコードを、安全にGeminiに渡すためのサニタイズエクスポートツール。

目的

プロジェクトのgitリポジトリは機密
GitHubミラーは禁止
Google Workspace上のGemini/NotebookLMを活用したい
そのため、AIに渡してよい最小限のコード断面だけを抽出する

特徴

sourcePathsによるallowlist方式（基本）
典型的な危険ディレクトリや成果物の除外
テキストベースの簡易redaction
fixtures/sandboxの構造化ファイル（JSON/YAML）の匿名化（決定的擬似化）
AI用README自動生成（README_FOR_AI.md）
manifest出力による人間レビュー
sensitiveっぽい内容へのwarning
--check（dry-run）で「何が出るか」だけ確認可能
--packでoutDir/_pack/にindex・chunk・bundleを生成（Gemini/NotebookLM向けの分割成果物。詳細はdocs/gemini-workflow.md）

前提

Node.js 18以上を推奨

セットアップ

まず置く場所（共通）

この手順は、**エクスポートしたいPlaywrightプロジェクト（Playwrightのテストを含むリポジトリ）**で実行します。迷ったら、そのリポジトリのpackage.jsonがあるフォルダーへ移動してから進めてください。モノレポでpackage.jsonが複数ある場合は、Playwrightのテストが含まれるパッケージ側を選びます。次のファイル・ディレクトリは、コマンドを実行するフォルダーを基準に置きます。

置くもの	場所（ルートからの相対）	役割
`.gemini-export.json`	ルート直下	allowlist などの設定（必須。ない場合は内蔵デフォルトとマージ）
`tools/` 一式	`tools/export-gemini-playwright-context.mjs` ほか	CLI 本体（自プロジェクトへ取り込む場合）
出力	既定では `.ai-context/playwright-gemini/`（`outDir` で変更可）	Gemini に渡す成果物（`.gitignore` 推奨）

sourcePaths や outDir に書くパスは、いずれもコマンドを実行するフォルダーからの相対パスです。

実行場所ごとの例（モノレポルート / `playwright/`）

sourcePaths の書き方は、どこでコマンドを実行するかで変わります。まずは、次の例のいずれで運用するかを決めてください。

例A: モノレポルートで実行する（`playwright/` が直下にある）

実行する場所: モノレポのルート
sourcePaths の例: playwright/ で始める

.gemini-export.example.json は、この例A（モノレポルート実行）を想定したサンプルです。

{
  "sourcePaths": [
    "playwright/tests",
    "playwright/pages",
    "playwright/helpers",
    "playwright/fixtures/sandbox",
    "playwright/playwright.config.ts",
    "playwright/AI_CONTEXT.md"
  ],
  "outDir": ".ai-context/playwright-gemini"
}

例B: `playwright/` で実行する（設定・出力も `playwright/` 配下に閉じる）

実行する場所: playwright/ ディレクトリ
sourcePaths の例: playwright/ を付けない

{
  "sourcePaths": [
    "tests",
    "pages",
    "helpers",
    "fixtures/sandbox",
    "playwright.config.ts",
    "AI_CONTEXT.md"
  ],
  "outDir": ".ai-context/playwright-gemini"
}

例C: ツールのルートとモノレポのルートを分ける

モノレポのルートに package.json があり、このツール側にも package.json や .gemini-export.json を置くため、同じディレクトリに両方を置きたくない場合の例です。モノレポのチェックアウト先を子フォルダー workdir/ にまとめ、常にその親でコマンドを実行します。

実行する場所: workdir の親（例では export-workspace/）。このフォルダーに、このリポジトリの package.json・tools/・.gemini-export.json を置く。
workdir/: モノレポのルート（workdir/playwright/がPlaywright用のルートになる構成を想定）。Gitのsparse checkoutでplaywright/だけを展開してもよい。
sourcePathsの例: 例Aと同じ並びだが、先頭にworkdir/を付ける。

export-workspace/          ← ここで npm run export（process.cwd() がこのツールのルート）
  .gemini-export.json
  package.json
  tools/
  workdir/                 ← モノレポのルート
    playwright/
      tests/
      ...

{
  "sourcePaths": [
    "workdir/playwright/tests",
    "workdir/playwright/pages",
    "workdir/playwright/helpers",
    "workdir/playwright/fixtures/sandbox",
    "workdir/playwright/playwright.config.ts",
    "workdir/playwright/AI_CONTEXT.md"
  ],
  "outDir": ".ai-context/playwright-gemini"
}

includeFiles（ロックファイルや tsconfig.json など）も、すべて実行時のルートからの相対パスです。モノレポ側のファイルを含めたい場合は、例として workdir/package.json のように workdir/ を付けて列挙してください。

注意

export-workspace/playwright-export-gemini/ と export-workspace/workdir/ を兄弟にし、常に前者だけに cd して実行すると、モノレポへ向けるパスが ../workdir/... になります。設定では .. を含む相対パスは使えないため、この配置のままでは困りがちです。親を1つにまとめる（この例Cの形）か、実行時は必ず workdir を子として含む親に cd してください。
リポジトリ外に解決するシンボリックリンクはエクスポート対象外になることがあります（CI での推奨の固定タグ [symlink-outside-repo] など）。

パターンA: このリポジトリをクローンして使う

GitHubからこのリポジトリを任意の作業フォルダーにクローンする。
クローンしたディレクトリに移動する（以降、このディレクトリがルート）。モノレポのルートとツールのルートを分けたい場合は、例C のレイアウトに合わせて親フォルダーへファイルを置き、workdir/ にモノレポをチェックアウトしてもよい。
npm install で依存関係を入れる。
ルートに設定ファイルを作る。.gemini-export.example.jsonをコピーして.gemini-export.jsonという名前で置く。
必要に応じてsourcePathsを修正する（後述の「推奨設定」も参照）。
ルートにいる状態で npm run export:gemini:check を試し、問題なければ npm run export:gemini を実行する。

本リポジトリではローカル用の .gemini-export.json を .gitignore しているため、手元では例からコピーして編集してください。

パターンB: 既存の別プロジェクト（自前の Playwright リポジトリ）に組み込む

npmパッケージとしては公開していない（package.json は private）ため、ツールのファイルを対象プロジェクト側へ取り込む形になります。

このリポジトリから tools/ ディレクトリ全体（export-gemini-playwright-context.mjs・gemini-export/・lib/）を、対象プロジェクトのルート直下にコピーする（ディレクトリ構成はこのリポジトリと同じ tools/... を推奨）。
対象プロジェクトの package.json に、依存として yaml（例: "yaml": "^2.8.3"）と、export:gemini / export:gemini:check（Pack利用時はexport:gemini:pack）用の scripts を追加する（中身はこのリポジトリの package.json をそのまま流用できる）。
対象プロジェクトのルートで npm install を実行する。
対象プロジェクトのルートに .gemini-export.json を置く（このリポジトリの .gemini-export.example.json をコピーしてリネームし、プロジェクトのディレクトリ構成に合わせて sourcePaths を編集する）。
必ず対象プロジェクトのルートに cd した状態で npm run export:gemini:check → 問題なければ npm run export:gemini を実行する。

チームで設定を共有したい場合は、自プロジェクトの運用に合わせて .gemini-export.json をリポジトリにコミットしてよい（機密が含まれないことを確認すること）。

実行

通常実行（書き込みあり）

npm run export:gemini

dry-run（書き込みなし）

npm run export:gemini:check

Pack（index / chunk / bundle）

コンテキストウィンドウに収めやすいよう、outDir 配下の _pack/ に索引・チャンク・バンドルを追加生成します。運用の考え方は docs/gemini-workflow.md を参照してください。

npm run export:gemini:pack

（同等: npm run export:gemini -- --pack）

--checkと併用した場合は_pack/は作らず、標準出力にchunk/bundle数の概算のみ出します。

npm run export:gemini:check -- --pack

.gemini-export.json の pack（chunkMode / chunkMaxLines / maxChunkBytes / bundleGroupDepth / outSubDir）で調整できます。既定値は tools/gemini-export/default-config.mjs の pack を参照してください。

CI での推奨

本番相当のリポジトリでは、パイプラインでnpm run export:gemini（または先にexport:gemini:check）を実行し、**failOnWarnings: true**を有効にすると、機密っぽい検知・設定ミス・セキュリティ関連スキップを警告のまま放置しにくくなります。設定例の断片はtemplates/gemini-export.ci.snippet.jsonを参照し、.gemini-export.jsonにマージしてください。
ローカルでは--checkで差分を確認し、問題なければ通常実行、という流れが安全です。
manifest.jsonのwarnings/skippedFilesに、次の固定タグが付いた行がないか毎回確認してください（自動検索・レビュー用）。
- [symlink-outside-repo] … シンボリックリンクがリポジトリ外に解決した、または解決不能
- [path-outside-repo] … 解決先がリポジトリ外（通常ファイルパス）
- [dest-outside-outDir] … 出力パスがoutDir外にならないよう拒否された
- [unsafe-relative-path] … エクスポート相対パスに..セグメントが含まれる
- [realpath-failed] …realpath/statに失敗（壊れたリンクなど）

出力先

.ai-context/playwright-gemini/
  ... サニタイズ済みのコピー ...
  manifest.json
  README_FOR_AI.md   # 生成が有効な場合
  _pack/             # `npm run export:gemini -- --pack` 実行時のみ

サニタイズ済みツリーに加え、Packを付けた場合は_pack/内のPROJECT_INDEX.mdやbundles/をNotebookLMやGeminiチャットに渡す運用が可能です。

推奨設定

まずはsourceDirではなくsourcePathsを使う（sourceDirは非対応）。

例（モノレポルートで実行する場合）:

{
  "sourcePaths": [
    "playwright/tests",
    "playwright/pages",
    "playwright/helpers",
    "playwright/fixtures/sandbox",
    "playwright/playwright.config.ts",
    "playwright/AI_CONTEXT.md"
  ]
}

AI向け説明ファイル

playwright/AI_CONTEXT.md:人間がメンテするプロジェクト固有知識（テスト流儀・禁則・環境前提など）
README_FOR_AI.md:ツールが生成する「この出力物の説明」

templates/AI_CONTEXT.example.mdを起点に、対象リポジトリ側でplaywright/AI_CONTEXT.mdを用意する運用を推奨。

重要な注意

redactionは補助。漏洩防止の本体はallowlist（sourcePaths）
fixtures/real / fixtures/private / auth / storageStateなどはexportしない（設定ミスはwarning扱い）
manifest.jsonは毎回人間が確認する
warningが出たら無視しない（必要ならfailOnWarnings: true）
実行時にNOTICEが標準出力されるので、内容を確認する
fixtureに実データを入れない（sandbox/realを分離する）

推奨運用

AI_CONTEXT.mdを人間が管理する
fixtureはsandbox/realを分離する
実際にGeminiに渡す前に出力物をレビューする

今後の拡張の検討項目は docs/roadmap.md にまとめている。

Navigation Menu

Repository navigation

About

Repository files navigation

Playwright → Gemini Export Tool

目的

特徴

関連ツール

前提

セットアップ

まず置く場所（共通）

実行場所ごとの例（モノレポルート / `playwright/`）

例A: モノレポルートで実行する（`playwright/` が直下にある）

例B: `playwright/` で実行する（設定・出力も `playwright/` 配下に閉じる）

例C: ツールのルートとモノレポのルートを分ける

注意

パターンA: このリポジトリをクローンして使う

パターンB: 既存の別プロジェクト（自前の Playwright リポジトリ）に組み込む

実行

通常実行（書き込みあり）

dry-run（書き込みなし）

Pack（index / chunk / bundle）

CI での推奨

出力先

推奨設定

AI向け説明ファイル

重要な注意

推奨運用

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
docs		docs
playwright-official-docs		playwright-official-docs
templates		templates
test		test
tools		tools
.gemini-export.example.json		.gemini-export.example.json
.gitignore		.gitignore
.markdownlint-cli2.jsonc		.markdownlint-cli2.jsonc
README.md		README.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation

Playwright → Gemini Export Tool

目的

特徴

関連ツール

前提

セットアップ

まず置く場所（共通）

実行場所ごとの例（モノレポルート / playwright/）

例A: モノレポルートで実行する（playwright/ が直下にある）

例B: playwright/ で実行する（設定・出力も playwright/ 配下に閉じる）

例C: ツールのルートとモノレポのルートを分ける

注意

パターンA: このリポジトリをクローンして使う

パターンB: 既存の別プロジェクト（自前の Playwright リポジトリ）に組み込む

実行

通常実行（書き込みあり）

dry-run（書き込みなし）

Pack（index / chunk / bundle）

CI での推奨

出力先

推奨設定

AI向け説明ファイル

重要な注意

推奨運用

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

実行場所ごとの例（モノレポルート / `playwright/`）

例A: モノレポルートで実行する（`playwright/` が直下にある）

例B: `playwright/` で実行する（設定・出力も `playwright/` 配下に閉じる）