3行まとめ
落ちたlocator、期待name、timeout、再現コマンドをまとめる。
UI文言、accessible name、テスト期待値のどれを正とするか決める。
外部通信、GitHub書き込み、依存更新、secrets参照を承認制に戻す。
成功談ではなく、人間がAIの修正をレビューできる材料をそろえる手順です。
- CursorにPlaywrightの失敗修正を頼む前に、失敗ログ、再現コマンド、期待仕様、変更してよい範囲、合格ゲートを1つの依頼メモにしておくと、AIの修正をレビューしやすくなります。
- 今回はNext.js
16.2.7、React19.2.7、Playwright1.60.0の最小構成で、getByRole('button', { name: '送信する' })がtimeoutする失敗を作り、UIの表示文言とaccessible nameを揃える修正で1 passedまで確認しました。 - Background AgentやCloud系Agentに任せる場合は、GitHub read-write、外部通信、自動コマンド実行、
npm audit fix --force、secrets参照を先に承認制へ戻します。
この記事は「Cursorがこの検証を実行した」という成功談ではありません。Cursor Agentにテスト修正を任せる前に、人間側が渡すべき証拠と止めるべき操作を作るための記事です。2026年6月6日時点で指定Xアカウントの直近72時間にこのテーマの強い公開シグナルは確認できませんでしたが、Cursor AgentやAI coding workflowへの関心は続いているため、実務で使うチェックリストに変換します。
この記事でわかること
長いログから、落ちたテスト名、locator、期待name、timeoutを抜き出す。
テスト側が古いのか、UI側の表示名がずれているのかを分ける。
再現コマンド、期待仕様、禁止操作、合格条件を1枚にまとめる。
Local Gate、AI Change Gate、Human Review Gateで差分を見る。
Background Agent、npm audit、外部通信、secretsの扱いを分ける。
AIへ丸投げしてよいかではなく、どの情報があれば修正を判断できるかを見ます。
- Playwrightの失敗ログから、AIに渡すべき「失敗の核」を抜き出す方法
getByRoleとaccessible nameの不一致を、テスト側とUI側のどちらで直すか判断する基準- Cursor Agentへ渡す依頼文に入れる再現コマンド、期待仕様、禁止操作
- Next.js + Playwrightの修正を、Local Gate、AI Change Gate、Human Review Gateで見る方法
- Foreground AgentとBackground Agentで変えるべき権限境界
npm auditの警告を、AIに自動修正させないためのレビュー観点
Cursor Background AgentsのGitHub権限やremote環境そのものを詳しく確認したい場合は、先にCursor Background Agentsをチームで使う前にを読むと、この記事の権限設計がつながりやすくなります。
前提知識
role/nameの不一致は、単なる待ち時間ではなく仕様のずれを示すことがあります。
Playwrightのrole locatorは、画面上の要素をCSS classやDOM構造だけで探すのではなく、ユーザーや支援技術が認識するroleとnameに近い形で探します。たとえばボタンなら、page.getByRole("button", { name: "送信する" }) のように、roleとaccessible nameを組み合わせます。
この性質は、AIエージェントにとって便利でもあり、危険でもあります。便利なのは、失敗ログに「どんな操作名を期待したか」が残ることです。危険なのは、AIがテストを通すためにlocatorを弱めたり、timeoutを伸ばしたり、data-testid へ逃げたりしても、表面上はテストが通ってしまうことです。
Cursorへ渡す前に決めること
CursorのRulesは、AgentやInline Editに対して再利用できる指示を渡す仕組みです。Project Rulesは .cursor/rules に置き、AGENTS.mdもシンプルなagent instructionsとして使えます。毎回チャットで「テストを弱めないでください」と書くより、プロジェクト側に残すほうが運用しやすくなります。
一方、CursorのAgent SecurityやBackground Agentsの公式情報では、read系操作、ファイル編集、terminal command、外部MCP、Background Agentのremote環境やGitHub権限など、実行面の前提が分かれます。特にBackground Agentはremote環境で作業し、GitHub連携やterminal commandの自動実行が関わるため、foregroundで人間が見ながら進める修正と同じ扱いにしないほうが安全です。
今回の検証で使った材料
手元では、/Users/mogir/workspace/wp/ai-dev/.verification/cursor-playwright-nextjs-test-repair に最小のNext.js + Playwrightプロジェクトを作りました。この記事で使うログは次の3つです。
| ファイル | 役割 | 結果 |
|---|---|---|
logs/failing-playwright.log | 修正前の失敗ログ | getByRole('button', { name: '送信する' }) がtimeoutし、1 failed |
logs/page-fix.diff | 修正差分 | ボタンの表示文言と aria-label を 送信する に揃えた |
logs/passing-playwright.log | 修正後の再実行ログ | 1 passed (2.4s) |
依存導入後の npm audit ではmoderate 2件が出ました。ここでは自動で npm audit fix --force を実行せず、AIエージェントへ渡す禁止操作の例として扱います。
CursorにPlaywright修正を頼む前に、渡す情報を5つに分ける
`getByRole('button', { name: '送信する' })` timeoutのように、何が落ちたかを固定する。
`npm run test:e2e` のように、人間とAIが同じ条件で確認できる形にする。
送信ボタンの表示名とaccessible nameをどうそろえるべきかを書く。
該当ページと該当テスト周辺に絞り、関係ない差分を止める。
テスト通過、差分最小、禁止操作なしをmerge前の確認条件にする。
材料が足りない依頼ほど、AIはテストを通すことだけを最短目標にしがちです。
最初に作るべきものは、長いプロンプトではなく、修正依頼の材料です。次の5つが揃っていない状態で「このPlaywrightテストを直して」と渡すと、AIはテストを通すことだけを最短目標にしがちです。
| 渡す情報 | 今回の例 | 目的 |
|---|---|---|
| 失敗ログ | getByRole('button', { name: '送信する' }) timeout | 何が落ちたかを固定する |
| 再現コマンド | npm run test:e2e | AIと人間の確認条件を揃える |
| 期待仕様 | 送信ボタンの表示名とaccessible nameを揃える | テスト側かUI側かを判断する |
| 変更範囲 | 該当ページと該当テスト周辺 | unrelatedな差分を止める |
| 合格ゲート | 1 passed、差分最小、禁止操作なし | merge前レビューを楽にする |
失敗ログは全文ではなく「失敗の核」を抜く
今回の失敗ログで、AIに渡すべき核はこの部分です。
確認項目
Error: locator.click: Test timeout of 30000ms exceeded.
- waiting for getByRole('button', { name: '送信する' })
1 failedログ全文を貼ると、Next.jsの警告、色付き出力、stack trace、環境差のノイズが混ざります。AIが読むべきなのは、落ちたテスト名、locator、期待していたname、timeout、失敗時の画面状態です。
再現コマンドはdev serverとtestを分ける
Playwrightはアプリの起動条件とテスト実行条件がずれると、失敗原因の切り分けが難しくなります。今回の playwright.config.ts では、web server側で npm run dev を起動し、npm run test:e2e でテストを走らせました。
{
"scripts": {
"dev": "next dev --hostname 127.0.0.1 --port 3217",
"test:e2e": "playwright test"
}
}Cursorへ渡す依頼文には、少なくとも「どのコマンドで再現するか」と「どのコマンドが通れば完了か」を分けて書きます。CIだけで落ちる場合は、CIのNode version、環境変数、port、ブラウザ、artifactの場所も足します。
注意点
期待仕様はテストの前に書く
今回の例では、テストが期待していたボタン名は 送信する でした。実装側は、表示文言が 送信、aria-label が 申請内容を確認する でした。
この状態でAIに「テストを通して」とだけ頼むと、次のどれを選ぶかが曖昧です。
評価基準
| 選択肢 | 何が起きるか | 採用条件 |
|---|---|---|
UI側を 送信する に揃える | 利用者が見る文言とテストが一致する | 仕様上の操作名が 送信する |
テスト側を 申請内容を確認する に変える | 既存UIを正としてテストを更新する | 仕様上の操作名が変更済み |
| locatorを弱める | テストは通るが意味の保証が弱くなる | 最後の手段。理由をPRに残す |
| timeoutを伸ばす | 今回の不一致は解決しない | 表示遅延が原因と証明できる場合だけ |
AIに渡す前に、期待仕様を1文だけでも書いておくと、差分レビューの基準ができます。
Playwrightの失敗ログはLocatorとaccessible nameから読む
今回の主因は、ボタンの表示名、aria-label、テスト期待値の不一致です。
Playwright公式Docsでは、role locatorはユーザーや支援技術がページをどう認識するかに近い形で要素を探すと説明されています。つまり getByRole("button", { name: "送信する" }) の失敗は、「ボタンがない」だけではありません。
timeoutが示す原因候補
今回のtimeoutから考えられる候補は、少なくとも4つあります。
原因候補
| 原因候補 | 見る場所 | 今回の判断 |
|---|---|---|
| 対象ボタンが存在しない | DOM、画面、trace | ボタン自体は存在する |
| accessible nameが違う | button text、aria-label | 申請内容を確認する と 送信 で不一致 |
| 表示タイミングが遅い | auto-wait、network、loading state | 主因ではない |
| 画面遷移や条件分岐が違う | URL、route、auth state | 主因ではない |
Playwrightのweb-first assertionは、期待状態になるまで再試行します。assertion timeoutやlocator timeoutが出たときは、単に待ち時間を伸ばす前に、期待しているrole/nameが画面上の意味と合っているかを見ます。
UIとテストのどちらが古いかを分ける
AIエージェントに修正を任せるときに一番危ないのは、「テストが落ちているからテストを直す」という短絡です。Playwrightのrole locatorは仕様の揺れを見つけてくれることがあります。今回のように、表示文言と aria-label とテスト期待値がずれている場合、先に仕様を見ます。
今回の修正差分はこうです。
修正差分
- <button type="submit" aria-label="申請内容を確認する">
- 送信
+ <button type="submit" aria-label="送信する">
+ 送信する
</button>この差分は、locatorを弱めていません。UIの表示文言とaccessible nameを、テストが期待する操作名へ寄せています。もちろん、実プロダクトで「申請内容を確認する」が正しい仕様なら、テスト側を更新すべきです。大事なのは、AIにその判断を丸投げしないことです。
Trace Viewerは証拠を見るために使う
Playwright Trace Viewerは、CIで失敗したテストを後から確認するための道具です。AIにtraceやscreenshotを渡す場合も、丸ごと貼るより「何を見てほしいか」を添えます。
確認したい項目:
- 失敗時点でボタンが画面にあるか
- そのボタンのvisible textやaccessible nameは何か
- action前後でnetworkやconsole errorが出ていないか
- retry中に対象要素が現れたか
- auth stateやrouteが期待と違っていないか
AIエージェントによるブラウザ検証そのものを設計したい場合は、Playwright MCPでAIエージェントにブラウザ検証を任せるも合わせて確認すると、snapshotやprofileの扱いを分けやすくなります。
AIに渡す修正依頼は、禁止事項まで含めて1枚にする
- 1目的
Next.jsの申請フォームで落ちているPlaywrightテスト1件を直す。
- 2失敗
`getByRole('button', { name: '送信する' })` がtimeoutしている。
- 3期待仕様
送信ボタンは利用者にも支援技術にも「送信する」と認識される。
- 4再現
`npm run test:e2e` で失敗と修正後の通過を確認する。
- 5禁止事項
locator弱体化、timeout延長、test skip、依存更新、secrets参照を止める。
- 6合格条件
差分が狭く、仕様を保ち、再実行ログで通過している。
禁止事項は気持ちではなく、承認制に戻す操作として書くと運用しやすくなります。
Cursor Agentへの依頼は、短くても構いません。ただし、短い依頼ほど禁止事項と合格条件が重要です。今回のケースなら、次のような依頼メモで十分です。
依頼文の最小構成
目的:
Next.jsの申請フォームで落ちているPlaywrightテスト1件を直してください。
失敗:
getByRole('button', { name: '送信する' }) が30秒timeoutしています。
期待仕様:
送信ボタンは利用者にも支援技術にも「送信する」と認識されるべきです。
再現:
npm run test:e2e
成功条件:
- 該当テストが 1 passed になる
- locatorを弱めない
- timeout延長だけで解決しない
- unrelatedなファイルを触らない
禁止:
- npm audit fix --force
- 依存更新
- lockfile更新
- test.skip / test.fixme / テスト削除
- .env* やsecrets参照
- 外部APIや本番DBへの接続禁止事項は「やってほしくないこと」ではなく「承認制に戻すこと」
npm audit fix --force は分かりやすい例です。npm公式Docsでは、force は保護を外し、dependency range外やSemVer-major変更を許す場合があると説明されています。今回の npm audit でもmoderate 2件が出ましたが、自動修正候補は別メジャーへ戻る形でした。
このような操作は、AIが勝手に実行してよい修正ではありません。
承認制に戻す操作
| 操作 | 扱い | 理由 |
|---|---|---|
npm run test:e2e | 許可しやすい | 再現と合格確認に必要 |
npm audit | 調査なら許可しやすい | 結果を読むだけなら副作用が小さい |
npm audit fix | 承認制 | lockfileや依存が変わる |
npm audit fix --force | 原則禁止 | major変更や別方向の修正を含み得る |
git push | 承認制 | remoteへ変更を送る |
| secrets参照 | 原則禁止 | ログや外部送信と組み合わさると危険 |
Cursor RulesやAGENTS.mdへ残す
テスト修正を何度も頼むなら、依頼文ではなくルールとして残します。CursorのProject Rulesなら .cursor/rules、ツール横断の単純なルールならAGENTS.mdに置くのが扱いやすいです。
例:
# Playwright test repair rules
- Prefer role locators and user-visible behavior.
- Do not weaken assertions just to make tests pass.
- Do not increase timeout unless the root cause is proven to be timing.
- Do not run npm audit fix --force.
- Do not edit lockfiles or dependencies without explicit approval.
- Always report command, result, changed files, and remaining risks.チーム全体で権限、禁止操作、テスト手順を揃えるなら、チーム向けAGENTS.mdテンプレートのように、ツール別ではなくリポジトリの運用ルールとして書くほうが効きます。
修正差分は「テストを通したか」より「仕様を保ったか」で見る
良い差分は、テストを通すだけでなく、ユーザー向けの意味も保っています。
今回の修正後、npm run test:e2e は 1 passed (2.4s) になりました。ただし、合格ログだけを見て終わりにしません。見るべき順番は、成功結果、差分の狭さ、仕様との一致です。
レビューの順番
今回の差分で見るポイント
今回のUI差分は、次の条件を満たしています。
- テストのlocatorを弱めていない
aria-labelと表示文言を同じ操作名へ揃えている- 該当ページ以外を触っていない
- 依存、lockfile、Playwright設定を変えていない
- timeoutを伸ばしていない
このような差分なら、AIに作らせたとしてもレビューしやすいです。逆に、次のような差分は差し戻します。
差し戻す差分
| 差分 | 差し戻す理由 |
|---|---|
getByRole("button").first() に変える | どのボタンを押すか保証しにくい |
page.locator("button").click() に変える | 利用者向きのnameを見なくなる |
| timeoutを30秒から120秒へ伸ばす | name不一致の根本原因を直していない |
test.skip を入れる | 失敗を隠している |
| lockfileを更新する | テスト修正の範囲を超えている |
テスト側を変えるべきケースもある
今回の記事ではUI側を直しましたが、常にUI側が正しいわけではありません。たとえば、プロダクト仕様としてボタン名を「申請内容を確認する」に変えた直後なら、テストが古い可能性があります。その場合はテスト期待値を更新し、仕様変更としてPR説明に残します。
判断の目安:
- 仕様書、Issue、デザイン、実装が同じ文言を指しているなら、テストを更新する
- UIと
aria-labelがずれているなら、まずUIの意味を揃える - 画面上の文言と支援技術向けnameをあえて変えるなら、その理由を明記する
- locatorを弱める場合は、なぜrole/nameで探せないかをPRに書く
AIは「どちらが仕様か」を、コードだけから決められないことがあります。ここは人間側のレビュー領域です。
Next.js + Playwrightのテストゲートを3段階にする
- 1Local Gate
失敗が再現し、修正後に同じコマンドで通ることを確認する。
- 2AI Change Gate
locator弱体化、timeout延長、unrelated変更がないかを見る。
- 3Human Review Gate
仕様判断、secrets、依存更新、外部通信、コストを人間が確認する。
1つの合格条件だけにすると、通過ログの裏にある危ない差分を見落としやすくなります。
AIに修正を任せるときは、1つの合格条件だけでなく、3段階に分けると失敗が見つけやすくなります。
ゲート一覧
| ゲート | 見るもの | 止める例 |
|---|---|---|
| Local Gate | 再現と通過 | テストが再現しない、dev serverが起動しない |
| AI Change Gate | 差分の狭さ | locator弱体化、timeout延長、unrelated変更 |
| Human Review Gate | 仕様、権限、コスト | 仕様判断、secrets、依存更新、外部通信 |
Local Gateは再現と最小成功だけを見る
Local Gateでは、深い設計判断をしません。まず落ちること、直した後に通ることを確認します。
今回の実行結果:
修正前: 1 failed
修正後: 1 passed (2.4s)この段階で、Next.js側のworkspace root warningや NO_COLOR warningのような周辺警告もログに残りました。ただし、今回の失敗原因はボタンのname不一致なので、警告を主因として扱いません。AIへ渡すときも、「今回直してほしい失敗」と「別途見る警告」を分けます。
AI Change Gateは差分の狭さを見る
AI Change Gateでは、修正が狭いかを見ます。Playwrightの失敗1件に対して、依存更新、CSS全体の整理、設定ファイルの変更、別テストのskipが混ざったら、修正が膨らんでいます。
レビュー観点:
- 変更ファイルは最小か
- テストの意味を弱めていないか
- 失敗したlocatorの根本原因に触れているか
- 依存やlockfileを変えていないか
npm audit警告を勝手に直していないか
AIが「ついでに直しました」と言い始めたら、差分を分けます。テスト修正PRと依存更新PRは、レビュー観点が違います。
Human Review Gateは仕様と権限を見る
Human Review Gateでは、人間が責任を持つ領域を見ます。AIがテストを通せても、次の判断は残ります。
- ボタン名はプロダクト仕様に合っているか
- アクセシビリティ上のnameとして自然か
- 既存ユーザーや翻訳への影響はないか
npm auditのmoderate 2件をどう扱うか- Background AgentにGitHub read-writeを渡す必要があるか
- 外部通信やsecrets参照が起きていないか
この観点をPR本文に残すなら、AIエージェントPRテンプレートの作り方で整理したように、Tests run、Not run、Risksを分けると読みやすくなります。
Cursor AgentとBackground Agentでは権限境界を変える
小さな再現修正はローカルで十分なことが多く、remote実行では権限とコストの上限を先に決めます。
Cursorのforeground Agentにローカルで小さな修正を頼む場合と、Background AgentやCloud Agent系にremote環境で作業させる場合では、同じ「AIに任せる」でもリスクが違います。
| 観点 | Foreground Agent | Background Agent / Cloud系 | 人間レビュー |
|---|---|---|---|
| コマンド実行 | 人間が見ながら進めやすい | 自動実行の前提を確認する | 危険操作を承認制に戻す |
| GitHub権限 | ローカル差分中心 | read-writeやbranch pushが関わる | repo scopeを絞る |
| 外部通信 | 人間が気づきやすい | remote環境とinternet accessを確認する | allowlistや禁止を決める |
| secrets | 読ませない | clone先やログにも注意 | .env*、CI secretsを分ける |
| コスト | 反復回数が見えやすい | model/API pricingやspend limitを確認する | 1タスク単位で上限を見る |
Foreground Agentは小さな再現修正に向く
今回のような失敗1件、差分1箇所、再現コマンド1つの修正は、foregroundで人間が見ながら進めやすいタスクです。ログを渡し、AIが修正候補を出し、人間が差分を見て、npm run test:e2e を再実行する。これで十分なケースは多いです。
このときも、次の操作は承認制にします。
- lockfile更新
- 依存更新
audit fixgit push- 外部API呼び出し
- secretsや
.env*の参照 - テスト削除やskip
Background Agentは権限とコストの上限を先に決める
CursorのBackground Agents公式情報では、remote環境、GitHub連携、依存install、terminal、Privacy Mode、internet access、pricingの確認が必要になります。記事執筆時点の公式Pricingでは、Background Agentsは選択モデルのAPI pricingで課金され、最初にspend limitを設定する案内があります。
この条件では、失敗ログが小さくても、運用リスクは大きくなります。Background Agentに渡すなら、次を先に決めます。
- 作業branch名
- pushしてよいremote
- 実行してよいコマンド
- installしてよいpackage
- secretsや社内URLの扱い
- 外部通信の許可範囲
- spend limit
- 完了時に出す報告形式
料金やプランは変わりやすいので、本文の数字だけで判断しません。Cursor公式Pricingとチーム契約の条件を確認してから使います。
セキュリティ・コスト注意
API token、cookie、session idはログから削る。
社内URL、非公開host、顧客名、メールアドレスをマスクする。
画面とnetwork情報を含むため、保管場所、アクセス権、保存期間を決める。
確認はしても、`npm audit fix` や `npm audit fix –force` は別PRで判断する。
AIの試行回数、外部API、remote実行の上限をタスク単位で見る。
セキュリティとコストは単純な勝敗ではなく、渡す情報と実行環境でリスクが変わります。
Playwright修正は一見小さいタスクですが、AIエージェントにterminal、browser、GitHub、MCP、外部APIを渡すと、権限の範囲が広がります。特にテスト修正では、失敗ログやtraceに社内URL、ユーザー名、token、顧客データが混ざることがあります。
注意点
失敗ログをそのまま渡さない
AIに渡す前に、ログを次の観点で削ります。
マスクする情報
| 確認するもの | 対応 |
|---|---|
| API token、cookie、session id | 削除する |
| 社内URL、非公開host | ダミー値にする |
| 顧客名、メールアドレス、個人情報 | マスクする |
| DB接続文字列 | 渡さない |
| screenshotやtraceのフォーム値 | 必要箇所だけ説明する |
Playwright traceは便利ですが、画面とnetwork情報を含むことがあります。AIに渡すなら、保管場所、アクセス権、保存期間も決めます。
npm audit はAIの自動修正対象にしない
今回の npm audit ではmoderate 2件が出ました。依存関係の脆弱性は重要ですが、Playwrightのlocator修正とは別タスクです。audit fix --force が提示されても、その場で実行すると、依存範囲やmajor versionが動く可能性があります。
分けて扱う理由
実務では、次のように分けます。
- テスト修正PRでは、audit結果を「未対応の別論点」として記録する
- 依存更新PRを別に切る
- changelog、breaking changes、lockfile差分、CI結果を見る
--forceは人間承認なしで実行しない
AIが「security fixもやっておきました」と言ったら、むしろレビューを止めるサインです。
コストは反復回数で増える
テスト修正は、失敗ログを読み、修正し、テストを走らせ、失敗したらまた読む、という反復になりやすいタスクです。Background AgentやMax Mode相当の大きなモデルを使う場合、1回の依頼よりも反復回数がコストに効きます。
最初の1週間は、次の項目だけでも記録します。
- 依頼回数
- 実行したテスト回数
- 変更ファイル数
- 失敗から成功までの時間
- 人間レビューの指摘数
- usageまたは請求上限への到達有無
この記録があると、Cursorだけでなく、Codex、Claude Code、Copilotなど他のAIコーディングツールとの比較にも使えます。
失敗点とハマりどころ
色付き出力、warning、stack traceが混ざり、本筋でない警告に寄りやすくなる。
テストを通す最短手段に見えるが、検証したかった操作名が消える。
GitHub push、外部通信、自動コマンド実行を先に許すとレビュー範囲が広がる。
テスト修正と依存更新を同時に扱うと、原因と責任範囲が分かれにくくなる。
通過結果だけでは、仕様を保った修正かどうかは判断できない。
先に渡すのは、失敗テスト名、locator、expected name、timeout、before/after差分、passing logの6点です。
今回のような小さい検証でも、AIに任せる前に見落としやすい点があります。
ログが長すぎて原因がぼける
Next.jsやPlaywrightのログには、色付き出力、workspace warning、browser warning、stack traceが混ざります。全部を渡すと、AIは本筋でない警告に寄ることがあります。
対策:
- 失敗テスト名
- locator
- expected name
- timeout
- before/after差分
- passing log
この6点を先に渡します。必要なら後から詳細ログを足します。
locatorを弱める修正が一番早く見える
AIにとって、getByRole("button", { name: "送信する" }) を locator("button") に変えるのは簡単です。しかし、それでは「利用者が見ている操作名」を守れません。
レビューでは、次の変更を見つけたら理由を聞きます。
- role locatorからCSS locatorへ変えた
- accessible nameを指定しなくなった
- regexを広くしすぎた
.first()や.nth()で逃げた- timeoutだけ増やした
Background Agentに広い権限を渡しすぎる
remote環境で自動実行できるAgentは便利です。けれど、テスト修正のような小さいタスクに、GitHub read-write、internet access、secrets、外部MCPを広く渡す必要があるとは限りません。
最初はforegroundでログと差分を見ながら進め、Background Agentに移すのは、環境再現が重い、複数ファイルの確認が必要、CI artifactをまとめて読む必要がある、といった理由があるときに絞ります。
結果
大事なのは成功結果そのものより、失敗ログ、差分、passing log、禁止操作がそろったことです。
今回の最小検証では、Playwrightの失敗原因を「ボタンのaccessible nameとテスト期待値の不一致」と判断し、UI側の表示文言と aria-label を 送信する に揃えました。
確認結果
| 項目 | 結果 |
|---|---|
| 修正前 | getByRole('button', { name: '送信する' }) timeout、1 failed |
| 修正 | aria-label と表示文言を 送信する に統一 |
| 修正後 | 1 passed (2.4s) |
| 触らなかったもの | 依存、lockfile、Playwright設定、timeout、テストskip |
| 保留したもの | npm audit moderate 2件 |
成功したことよりも大事なのは、AIに渡す前の材料が揃ったことです。失敗ログ、差分、passing log、禁止操作、レビュー観点が揃っていれば、Cursor Agentに任せた後でも、人間が差分を判断できます。
実務で使うなら
- 1Issueテンプレート
Failure、Expected behavior、Allowed changes、Forbidden changes、Gatesを書く。
- 2PRテンプレート
Summary、Tests、Risk、Not run、AI assistanceを残す。
- 3導入範囲を狭くする
1件の失敗、1つの再現コマンド、1つの画面から始める。
最初から大きな改修を任せず、レビューできる小さな修正単位を作ります。
実務では、今回の検証をそのまま記事のように再現する必要はありません。次の小さな運用に落とすほうが効きます。
Issueテンプレートに入れる
Playwright修正をAIに任せるIssueには、次を入れます。
テンプレート項目
Failure:
- test:
- command:
- error excerpt:
- trace/screenshot:
Expected behavior:
- user-visible behavior:
- accessible name:
Allowed changes:
- files:
- commands:
Do not:
- dependency update
- audit fix --force
- test skip/delete
- secrets or external API
Done when:
- command:
- expected result:
- reviewer checks:GitHub IssueからAIエージェントへ作業を流す場合は、失敗ログだけでなく受け入れ条件も入れます。Test Repairを評価セットにしたいなら、AI Coding Benchmark Kitの考え方へつなげて、Bugfix、Feature Add、Test Repairを同じ条件で測ると比較しやすくなります。
PRテンプレートに残す
AIが修正したPRには、次の情報を残させます。
- Summary
- 失敗ログの抜粋
- 修正した理由
- 変更ファイル
- 実行したコマンド
- 実行していない確認
- 残るリスク
- 人間に見てほしい仕様判断
Tests run に npm run test:e2e、Not run に未実行のlintやbuild、Risks にaudit警告やUI文言判断を残すだけでも、レビューの負担はかなり下がります。
最初の導入範囲を狭くする
チーム導入では、いきなり全E2E修正をBackground Agentに任せるより、次の順で広げます。
- 失敗1件だけをforegroundで直す
- IssueテンプレートとPRテンプレートを整える
- RulesまたはAGENTS.mdに禁止操作を書く
- CI artifactやtraceの渡し方を決める
- Background Agentはrepo、branch、spend limit、外部通信を絞って試す
AIエージェントは、雑な入力でもそれなりの差分を出します。だからこそ、最初に入力と合格条件を狭くします。
FAQ
小さい失敗、再現コマンド、期待仕様、禁止操作、レビューゲートがそろっている。
すぐテストを直さず、UI文言、accessible name、route、auth stateを確認する。
使う場合は、role/nameで探せない理由をPRに残す。
remote環境での再現、長いartifact確認、複数ファイルの反復修正が必要なときに検討する。
テスト修正と依存更新は分け、changelog、breaking changes、lockfile差分、CI結果を見る。
仕様が曖昧なまま任せると、AIは最短で通る差分へ寄りやすくなります。
CursorにPlaywright修正を任せてもよいですか
小さい失敗、再現コマンド、期待仕様、禁止操作、レビューゲートが揃っているなら任せやすいです。反対に、仕様が曖昧、ログに秘密情報が混ざる、依存更新が必要、外部APIや本番データに触れる場合は、人間が先に整理します。
role locatorが落ちたらテストを直せばよいですか
すぐには直しません。role locatorの失敗は、UI文言、accessible name、表示タイミング、route、auth stateの不一致を示すことがあります。まず仕様を確認し、UI側とテスト側のどちらが古いかを分けます。
data-testid は使わないほうがよいですか
常に悪いわけではありません。ただし、ユーザーが認識する操作名を検証したい場面では、role locatorのほうが意図を保ちやすいです。data-testid に逃げるなら、role/nameで探せない理由をPRに残します。
Background Agentに任せる基準は何ですか
ローカルで人間が見ながら進めるより、remote環境での再現、長いCI artifactの確認、複数ファイルの反復修正が必要なときです。GitHub read-write、外部通信、自動コマンド実行、spend limitを先に決めてから使います。
npm audit の警告も一緒に直すべきですか
テスト修正と依存更新は分けるほうが安全です。npm audit の確認はよいですが、npm audit fix や npm audit fix --force は別PRにし、changelog、breaking changes、lockfile差分、CI結果を見て判断します。
次に読むなら
AIコーディングエージェントの検証ログ、権限設計、テスト修正の失敗例は、今後も更新していきます。更新通知を受け取りたい場合は、ニュースレターを確認してください。
参照した主な情報源
- Cursor Background Agents: https://docs.cursor.com/background-agent
- Cursor Agent Security: https://docs.cursor.com/account/agent-security
- Cursor Rules: https://docs.cursor.com/context/rules-for-ai
- Cursor Models & Pricing: https://docs.cursor.com/account/pricing
- Playwright Locators: https://playwright.dev/docs/locators
- Playwright Assertions: https://playwright.dev/docs/test-assertions
- Playwright Trace Viewer: https://playwright.dev/docs/trace-viewer
- Next.js create-next-app CLI: https://nextjs.org/docs/pages/api-reference/cli/create-next-app
- npm audit: https://docs.npmjs.com/cli/v11/commands/npm-audit
更新履歴
- 2026年6月6日
Next.js `16.2.7`、React `19.2.7`、Playwright `1.60.0`、TypeScript `5.9.3`で初版作成。
- 失敗ログ
`getByRole('button', { name: '送信する' })` timeoutから検証を開始。
- 通過ログ
UI側の表示文言と `aria-label` をそろえ、`1 passed (2.4s)` を確認。
バージョンやAgent機能は変わるため、公開後も公式情報と再実行結果を確認します。
- 2026年6月6日: 初版作成。Next.js
16.2.7、React19.2.7、Playwright1.60.0、TypeScript5.9.3の最小構成で、getByRole('button', { name: '送信する' })timeoutから1 passed (2.4s)までを確認。Cursor、Playwright、Next.js、npmの公式情報を同日に確認。