トレースビューアを毎回開くの、地味に面倒じゃないですか
CIでテストが落ちると、まずtraceファイルをダウンロードして、ブラウザでトレースビューアを開いて、タイムラインをクリックして原因を探る。この一連の流れ、私はもう何百回とやってきました。正直、開くまでの数クリックが地味に面倒です。
特に困るのが「とりあえず何が起きたか一言で知りたいだけ」の時です。ブラウザUIを開くほどではないのに、開かないと何も分からない。この記事では、CLIだけでtraceの中身を追えるnpx playwright traceと、AIエージェントに任せた作業を動画で検証できるVideo Receiptsを試してみます。
まず私の環境で確認したこと
バージョンの話をする前に、一番確実なところから始めます。手元にどのバージョンが入っているかは、これで確認できます。
npx playwright --version
この記事で紹介する機能は出典によって「1.59」「1.60」と表記が揺れています。以前Test Agentsの初出バージョンを調べた記事でも同じことがあったのですが、機能ごとにバージョンが分散しているのが実態でした。今回も断定できるところと、揺れているところを分けて書きます。
従来の「traceを見る」はshow-traceしかなかった
これまでtraceファイルを見る方法は、基本的に1つでした。
npx playwright show-trace trace.zip
これを叩くとブラウザが立ち上がり、トレースビューアが開きます。タイムライン・ネットワーク・コンソール・スクリーンショットが全部見られて便利なのですが、「開く」という行為自体が前提になっています。CI環境やエージェントがコマンドラインだけで動いている状況では、この「ブラウザを開く」が地味にハードルです。
npx playwright traceでCLIだけで追えるようになった
複数の情報源を照らし合わせると、npx playwright traceというサブコマンド群が追加されており、open・merge・infoの3つで役割が分かれています。
# 従来通りビューアを開く
npx playwright trace open trace.zip
# 複数のshard(分割実行)のtraceを1つにまとめる
npx playwright trace merge shard-1.zip shard-2.zip -o merged.zip
# ブラウザを開かず、traceの中身をテキストで要約する
npx playwright trace info trace.zip
trace openはshow-traceと同じくビューアを開く動きですが、コマンド体系がtrace配下に整理されたようです。trace mergeは、CIをshard分割している場合に複数のtraceファイルを1本にまとめてから見られるので、shardごとに何個もファイルを開き直す手間がなくなります。
一番使うのはおそらくtrace infoです。ブラウザを一切開かず、traceに何が記録されているかをターミナルにそのまま出してくれます。「まず何が起きたか一言で知りたい」がこれで叶います。CIのログにそのまま流し込んでおけば、失敗の一次情報をブラウザなしで確認できるので、これ、意外と使えます。
これがエージェントにとって効いてくる
このtrace infoが地味に効いてくるのが、AIエージェントに落ちたテストの調査をさせる場面です。以前Healerで壊れたテストを自動修復させる記事を書きましたが、エージェントが「なぜ落ちたか」を理解するには、結局traceの中身を読む必要があります。
人間ならブラウザでトレースビューアを開いて目で追えますが、エージェントはターミナル越しにコマンドを叩いて結果のテキストを読む方が扱いやすい場面が多いです。trace infoでテキストとして要約が返ってくれば、エージェントはそれをそのまま読んで「このステップでタイムアウトしている」と判断材料にできます。ブラウザを操作させるより、よほど素直な連携です。
「AIに直させた結果」を人間が検証する側の悩み
ここまではエージェント側が原因を追う話でしたが、逆に人間側にも悩みがあります。Healerが自動でテストを直した後、その修復が本当に正しかったのか、人間はどう確認すればいいのかという問題です。
diffだけ見ても、実際にブラウザ上で何が起きたのかは分かりません。かといって毎回自分でテストを再実行して目視するのでは、自動修復のありがたみが半減してしまいます。
Video Receiptsで動画の証跡が残る
この「人間がどう検証するか」に応えるのが、Video Receiptsと呼ばれている機能です。複数の情報源を確認すると、これはpage.screencastという新しいAPIの上に成り立っていて、録画の開始・停止を細かく制御できるほか、操作した要素をハイライトする注釈（アクションアノテーション）付きで録画できる点が従来のvideoオプションとの違いのようです。
// 従来のvideoオプションは「テスト全体を録る/録らない」の粗い制御だった
// screencastは開始・停止のタイミングを自分でコントロールできる
await page.screencast.start();
// ...エージェントが操作する範囲...
await page.screencast.stop();
この仕組みを使うと、エージェントが自分の作業内容を動画として残せます。章立てのタイトルとアクションの注釈が付いた動画は、テキストログを1行ずつ追うよりずっと早く「何をしたか」を把握できます。エージェントが「直しました」と報告してきた時、この動画を早送りで眺めるだけで大枠の妥当性を判断できるのは、地味に安心感があります。
バージョン表記について正直に書いておきます
ここまで紹介した機能について、出典によってバージョン表記に揺れがあります。私が複数の情報源を照らし合わせた限りでは、npx playwright traceのCLIサブコマンド（open/merge/info）は1.60、Video Receiptsの土台になっているpage.screencastは1.59あたりで触れられている記事が多いという傾向でした。ただし別の記事では両方まとめて1.60寄りに書いてあるものもあり、私の手元では両方を完全に切り分けて再現検証できたわけではありません（正直に言うと、ここは自信を持って断定できません）。
実際に使う際は、まずnpx playwright --versionで手元のバージョンを確認したうえで、公式リリースノートで該当バージョンの項目を見るのが一番確実です。存在しないオプションを叩いて時間を溶かすよりは、ここは素直に公式を見に行くべきところだと思います。
まとめ
traceの確認はブラウザを開くのが当たり前だと思っていましたが、trace infoでCLIだけで一次情報が取れると分かったのは地味に収穫でした。CIのログに流し込んでおけば、落ちたテストの原因を追うまでの往復が1回減ります。
Video Receiptsについては、エージェントに任せる作業が増えるほど「本当にやったことを信じていいのか」という不安も比例して増えるので、動画という形で証跡が残る発想自体は素直にありがたいと感じました。まだ触り始めたばかりなので、実際の案件でどこまで使い倒せるかはこれから見ていきたいと思います。
AIにブラウザを触らせる基本はPlaywright MCP入門の記事、自動修復の仕組みはHealerの記事で書いているので、合わせて読んでみてください。
コメント