業務の一部をPlaywrightで自動化してから、半年以上が経つ。
最初のうちは「公式ドキュメントを読めば動くだろう」と思っていたが、実際に動き始めるまでに予想外の場所で詰まった。
同じ経験をする人の参考になればと思い、ハマったポイントをまとめておく。
1. ブラウザとPlaywrightのバージョン管理
Playwrightは内部に特定バージョンのChromium/Firefox/WebKitをバンドルしており、npx playwright install で自動取得する設計になっている。
これ自体は便利なのだが、複数の環境（自分のPC、WSL2、将来的なクラウド環境）でスクリプトを動かす可能性がある場合、バージョンの固定方針を最初に決めておかないと後で苦労する。
具体的には：
# package.json でPlaywrightのバージョンを固定する
"dependencies": {
"playwright": "1.47.0"
}
# CIや別環境でも必ず --frozen-lockfile でインストールする
npm ci
npx playwright install chromium # 使うブラウザだけ入れる
latest に依存していると、更新タイミングでブラウザのバージョンが変わり、セレクタが突然効かなくなることがある。これは実際に経験した。
2. WSL2環境での注意点
WSL2（Ubuntu）でPlaywrightを動かす場合、いくつかの追加設定が必要になる。
# ヘッドレスモードでも必要になることがある依存ライブラリ
npx playwright install-deps chromium
特に libatk-bridge2.0-0 や libnss3 が抜けていると、起動時にエラーが出る。Ubuntu環境では上記コマンドで依存を一括インストールするのが確実。
headless: false でデバッグしたいとき、WSL2環境では追加でXサーバー（VcXsrv等）が必要な場合がある。CIや本番はheadlessのみで動く前提にしておく方が管理しやすい。
3. セレクタが壊れやすいケース
Playwrightのドキュメントには「Locatorを使え」と書いてあるが、実際にロールベースのLocatorが使えない場面も多い。
特に問題になるのは：
| ケース | 対策 |
|---|---|
| 動的に生成されたclass名（Webpackのハッシュ等） |
data-testid 属性を使う（あれば）、または構造で絞る |
| 同じテキストの要素が複数ある |
.first() や .nth(0) で明示的に選択する |
| iframe内の要素 |
frameLocator() を使う（通常のセレクタは効かない） |
| SPA（Single Page Application）の遷移待ち |
waitForURL() または waitForLoadState('networkidle')
|
page.$('#id') のような古い書き方はなるべく使わない方が、後からのメンテナンスが楽になる。
4. 認証セッションの維持
ブラウザ自動化でよくあるユースケースが「ログインが必要なページの操作」だ。
Playwrightでは storageState を使うことで、認証済みのセッション情報をファイルに保存・再利用できる。
// 一度ログインしてからセッションを保存
await context.storageState({ path: 'auth.json' });
// 次回からは保存済みセッションを使って起動
const context = await browser.newContext({
storageState: 'auth.json'
});
注意点として、storageState はCookieとlocalStorageを保存するが、セッションの有効期限はサイト側が決める。期限切れのセッションで動かすと無言で処理が止まることがあるため、セッションの鮮度チェックを組み込んでおくと安定する。
まとめ
- ブラウザとPlaywrightのバージョンは最初に固定方針を決める
- WSL2環境では依存ライブラリの不足で詰まることがある
- セレクタは動的class名を避け、属性や構造で絞る
- セッションは有効期限を意識した設計にしておく
Playwrightを実務で使っている方、ハマりポイントや逆に「これが便利だった」というTipsがあればぜひコメントで教えてください。
本業での自動化・AI活用についてはnoteでも書いています：https://note.com/light_tern636/n/n160d94c38ad5
技術的な相談（Copilot・AIエージェント構築、60分のビデオチャット）も受け付けています。ご相談の際は「Qiitaを見た」とお書きください：https://coconala.com/services/4209036