はじめに
Playwright のテストや運用スクリプトが増えてくると、処理そのものより入力データの管理で崩れやすくなります。
最初は page.fill() の値や期待文言をスクリプトに直書きしていたのですが、ケースが増えるほどレビューしづらくなりました。
そこで、可変なデータは JSON に分離し、Playwright 側は手続きだけを書く形に寄せました。
この考え方は、実際に運用している個人開発サイト JP Tools でも使っています。
https://jptools.jp
先に結論
- Playwright 本体には遷移や操作の手続きを書く
- 可変な入力値や本文は JSON に逃がす
- TypeScript の interface で JSON の形を固定する
- 実行結果や進捗は別ファイルで管理する
この分離だけで、スクリプトの見通しがかなり良くなります。
こんな構成にした
まずはコンテンツの型を用意します。
export interface ArticleData {
id: string;
title: string;
body: string;
tags: string[];
private: boolean;
}
読み込み側はシンプルです。
function loadContentJson<T>(fileName: string): T {
return JSON.parse(readFileSync(resolve(CONTENT_DIR, fileName), "utf-8")) as T;
}
JSON ファイルには、スクリプトごとに必要な可変データだけを置きます。
{
"id": "playwright-testdata-json",
"title": "Playwright のテストデータを JSON 管理して保守しやすくする",
"tags": ["Playwright", "TypeScript"],
"private": false,
"body": "..."
}
分けて良かったこと
1. スクリプトの責務がはっきりする
Playwright のファイルには、ログイン、遷移、入力、送信などの手続きだけを書けます。データの差分と操作の差分が混ざらないので、レビュー時に追いやすくなりました。
2. データ更新のレビューがしやすい
本文やタイトル、タグの変更だけなら JSON の差分を見るだけで済みます。コードレビューで selector や wait の調整と文章修正が同時に出てくる状態を避けやすいです。
3. AI や非エンジニアの編集とも相性がいい
JSON は必要なキーが明確なので、入力データや記事本文だけを別の人に依頼しやすいです。TypeScript 側で受け口の型を決めておけば、受け渡しも安定します。
4. 進捗ファイルを分けやすい
completed のような実行状態を別 JSON に分けると、元データを汚さずに再実行できます。重複実行を避けたいワークフローでは特に相性がいいです。
注意点
1. 秘密情報は JSON に入れない
トークン、Cookie、メールアドレスのような情報は env や storageState に分離した方が安全です。JSON はあくまで可変データ置き場に留めるのが無難です。
2. JSON の責務を増やしすぎない
title や body のような内容データは JSON に向いていますが、selector や retry 回数まで入れ始めると逆に追いづらくなります。処理フローはコードに残した方が保守しやすいことが多いです。
3. 必要なら schema validation も入れる
運用人数が増えるなら、読み込み前に Zod などで schema validation を入れると事故を減らせます。interface だけでは実行時の JSON 崩れは防げないためです。
まとめ
Playwright の運用が重くなる原因は、自動化そのものよりデータと処理の責務が混ざることにあると感じています。
まずは JSON へ切り出すだけでも、修正のしやすさ、レビューのしやすさ、再利用性がかなり改善します。Playwright のスクリプトが長くなってきたら、最初に見直す価値があるポイントです。