ClaudeCodeのテスト実行方法を今日から迷わず動かす実践手順

ClaudeCodeでテストを動かしたいのに、「何を準備すればいいのか」「どこまで任せていいのか」「失敗した結果をどう直せばいいのか」で手が止まりやすいです。特にPlaywrightや既存のテストコマンドが絡むと、AIに頼んだはずなのに、結局エラー文を眺めて終わってしまうことがあります。大事なのは、ClaudeCodeに丸投げすることではなく、実行条件、成功判定、安全な権限、記録方法を先に渡すことです。そこまで整えると、テスト作成、実行、失敗原因の切り分け、再実行まで一気に進められます。

最初に決めるべきテスト実行のゴール

「テストして」だけでは失敗しやすい理由

ClaudeCodeに「テストして」とだけ頼むと、ClaudeCodeはプロジェクト内の設定を読んで、それらしいテストを探して実行しようとします。小さなプロジェクトならうまくいくこともありますが、実務のリポジトリでは、単体テスト、統合テスト、E2Eテスト、リンター、型チェックが混ざっています。その状態で曖昧に頼むと、今確認したい範囲とは違うテストが走ることがあります。

最初の一文で決めるべきことは、対象ファイル、使うテスト種別、成功条件です。たとえば、ログイン画面の変更を確認したいなら、「ログイン画面のE2Eテストを作成し、正常ログイン、認証失敗、未入力の3ケースを確認し、失敗時はスクリーンショットを残す」と伝えると、ClaudeCodeは作業範囲を絞れます。

初心者は既存コマンドの確認から始める

プロジェクトのルートでClaudeCodeを起動したら、まず「このプロジェクトで使えるテストコマンドを調べて、実行前に一覧で説明して」と入力します。すると、package.json、pyproject.toml、Makefile、READMEなどからテスト関連のコマンドを探し、実行候補を出してくれます。

ここでいきなり全テストを走らせる必要はありません。最初は変更した場所に近い最小テストを選びます。画面部品を直したなら該当コンポーネントのテスト、APIを直したなら対象エンドポイントのテスト、画面遷移を確認したいならPlaywrightの対象specだけを動かします。最小で通してから範囲を広げると、失敗したときに原因を見失いません。

ClaudeCodeでテストを実行する基本手順

初心者が迷わない順番は、環境確認、計画確認、小さく実行、結果確認、修正、再実行です。この順番を守るだけで、AIが勝手に大きな変更を入れて混乱する失敗をかなり減らせます。

この流れで進めると、テストが落ちたときも「環境が悪いのか」「テストコードが悪いのか」「本当に実装が壊れているのか」を分けて考えられます。特にE2Eテストでは、画面の読み込み待ち、セレクタの取り方、権限の違いで落ちることが多いため、最初から全自動で完璧に通そうとしないほうが安定します。

Playwrightで画面テストを動かすときの実践ポイント

画面を見ずにセレクタを書かせない

Playwrightで失敗しやすいのは、ボタン名や入力欄をClaudeCodeが推測してしまう場面です。実際の画面には同じようなボタンが複数あったり、表示条件によって要素が変わったりします。そこで、テスト作成前に「対象画面のDOM構造、表示テキスト、操作対象のroleを確認してからspecを作る」と指示します。

この一手間で、存在しない要素をクリックするテストや、別の入力欄を操作して成功扱いにする偽陽性を防ぎやすくなります。テストの目的が「金額入力欄を編集できること」なら、別のtextareaに入力できても成功ではありません。ClaudeCodeには、指定した要素が見つからない場合は代替操作せず失敗にすると明記します。

ログイン情報は.envで分ける

管理者、一般ユーザー、承認者など、権限で画面が変わるテストでは、アカウント情報の扱いが重要です。テストごとにメールアドレスやパスワードを直接書くと、漏えいや変更漏れの原因になります。環境変数ファイルに権限ごとのアカウントを定義し、テストコード側では「管理者でログイン」「一般ユーザーでログイン」のように呼び出す形にします。

この形にしておくと、アカウントを変更したいときも設定ファイルだけを直せば済みます。ClaudeCodeへ依頼するときも、「権限は環境変数のロール名から選び、テストケースにない権限を勝手に使わない」と伝えると、権限違いによる誤判定を減らせます。

単体テストと統合テストを作らせる方法

単体テストは正常系より境界値を重視する

関数やクラスのテストを作る場合は、「正常系だけでなく、空文字、null、最大値、最小値、不正な型、権限なしのケースを含める」と伝えます。ClaudeCodeは既存コードを読んでテストを書けますが、期待値が曖昧だと、実装に合わせた都合のよいテストを書いてしまうことがあります。

たとえば入力チェックの関数なら、「何文字まで許可するか」「全角を許すか」「空欄はエラーか」を具体的に書きます。仕様が決まっていない場合は、いきなり実装させず、「判断が必要な点を質問として列挙して」と依頼します。これで、曖昧なまま通るテストが増える状態を避けられます。

統合テストは外部依存を先に決める

API、データベース、外部サービスをまたぐ統合テストでは、どこを本物で動かし、どこをモックにするかを先に決めます。支払い、メール送信、外部API呼び出しのように実データへ影響する処理は、テスト環境でも慎重に扱う必要があります。

ClaudeCodeには、「データベースはテスト用を使う」「外部メール送信はモックにする」「作成したテストデータは最後に削除する」のように、操作後の状態まで指定します。実行結果だけでなく、テスト後に残るデータも確認すると、あとで別のテストが壊れる原因を減らせます。

安全に自動実行するための権限設計

許可するコマンドを狭くする

ClaudeCodeは便利ですが、テスト実行中にファイル編集やシェルコマンドを扱うため、権限を広げすぎると危険です。初心者ほど、最初は確認付きで使うのが安全です。慣れてきたら、テスト実行、リンター、型チェックなど、繰り返し使う安全なコマンドだけを許可します。

削除、強制push、本番環境への接続、秘密情報の表示は、常に確認が必要な操作として扱います。特に「権限確認が面倒だから全部スキップする」という使い方は、隔離された環境以外では避けるべきです。どうしても非対話で動かす場合は、Hooksでコマンドを検査し、許可リスト外の操作を止める形にします。

最新環境ではSkillsとHooksを使い分ける

ClaudeCodeでは、繰り返し使う作業をSkillsとしてまとめられます。たとえば「テスト準備」「E2E実行」「失敗ログ整理」を別々のSkillにすると、毎回長い指示を書かなくて済みます。さらにHooksを組み合わせると、テスト実行前に危険なコマンドを止めたり、実行後にレポートを整えたりできます。

新しいバージョンでは、Skillsを探しやすくする検索や、MCPツールの読み込み、Hooksの出力制御などが改善されています。実行前にはClaudeCodeのバージョンを確認し、古いままなら更新してから始めると、権限まわりやターミナル挙動の不具合で時間を失いにくくなります。

失敗したテストを直すときの見方

まず失敗を3種類に分ける

テストが落ちたら、すぐにコードを直す前に分類します。環境不備、テスト不備、実装不備のどれかを見ます。環境不備は依存パッケージ、認証、テストデータ、起動していないサーバーが原因です。テスト不備はセレクタ、待機、モック、期待値の間違いです。実装不備は本当に機能が壊れている状態です。

ClaudeCodeには「失敗ログを読んで、環境不備、テスト不備、実装不備に分類し、修正前に根拠を説明して」と頼みます。これを挟むと、AIが場当たり的に待機時間を増やしたり、期待値をゆるくしたりする危険を減らせます。

スクリーンショットと動画は必ず見る

E2Eテストでは、ログだけではわからない失敗が多いです。クリックしたつもりのボタンが画面外にある、モーダルが閉じていない、ローディングが残っている、別ユーザーでログインしている、といった問題はスクリーンショットで一気にわかります。

失敗時にスクリーンショット、トレース、動画を残す設定にしておくと、ClaudeCodeにも具体的な材料を渡せます。「このスクリーンショットの状態から、なぜ次のクリックに進めなかったかを説明して」と依頼すると、待機の問題なのか、権限の問題なのか、表示条件の問題なのかを切り分けやすくなります。

ClaudeCodeでテストを実行する方法に関する疑問解決

ClaudeCodeにテスト作成から実行まで全部任せてもいい？

全部任せるより、最初は人間が目的を決め、ClaudeCodeが実装と実行を担当する形が安全です。何を確認したいか、成功条件は何か、触ってはいけない範囲はどこかを人間が決めます。そのうえで、ClaudeCodeにテストコード作成、実行、ログ整理、失敗原因の候補出しを任せると、実務で使いやすくなります。

テストが通ったのに不安なときはどうする？

あえて失敗するケースを入れます。たとえば、権限がないユーザーには表示されないボタンを「押せるはず」としたテストを一時的に作り、正しく失敗するか確認します。これで、ClaudeCodeが別の要素を代替操作して成功扱いにしていないかを見抜けます。

PlaywrightMCPは必須？

必須ではありません。ただ、ブラウザの状態を確認しながらテストを作りたい場合はかなり役立ちます。ClaudeCodeが画面遷移、クリック、入力、表示確認を実際のブラウザ状態に近い形で扱えるため、セレクタの推測ミスを減らせます。既存のPlaywrightテストがあるなら、まずは通常のPlaywright実行から始め、必要に応じてMCPを追加すると無理がありません。

初心者が最初につまずく落とし穴

ターミナルでclaudeと入力したのに何も始まらない

最初にかなり多いのが、ターミナル（パソコンに文字で命令を出す画面）で

と入力したのに、「commandnotfound」や「認識されません」と表示される場面です。記事を読んで「よし、ClaudeCodeを開こう」と思った瞬間に止まるので、ここで一気にやる気が削られます。

原因はだいたい2つです。1つ目はClaudeCodeがまだインストールされていないこと。2つ目は、インストールした場所をターミナルが見つけられないことです。アプリのアイコンをクリックして開くタイプではなく、コマンドで呼び出す道具なので、最初だけ少し戸惑います。

こうすれば一発で解決します。まずターミナルを開き、

と入力してEnterを押します。バージョン番号が表示されればNode.js（ClaudeCodeなどの開発ツールを動かす土台）が入っています。何も出ない場合は、先にNode.jsを入れます。次にClaudeCodeのインストールコマンドを実行します。インストールが終わったら、ターミナルを一度閉じて、もう一度開きます。そのあと

と入力します。ログイン案内やClaudeCodeの画面が表示されたらOKです。

ここで大事なのは、同じターミナル画面で何度も連打しないことです。インストール直後はパソコン側が新しいコマンドの場所をまだ読み込んでいないことがあります。一度閉じて開き直すだけで直るケースがかなり多いです。

プロジェクトの場所がわからず違う場所で起動してしまう

次につまずくのが、ClaudeCodeは開いたものの、何を聞いても「テスト設定が見つかりません」「対象ファイルがありません」と言われる場面です。初心者は「ClaudeCodeが壊れているのかな？」と思いがちですが、ほとんどの場合、原因は作業するフォルダを間違えているだけです。

ClaudeCodeは、今ターミナルで開いているフォルダの中を見て動きます。つまり、デスクトップで起動すればデスクトップを見ますし、プロジェクトフォルダで起動すればプロジェクトを見ます。テストを実行したいなら、package.jsonやsrcフォルダがある場所で起動する必要があります。

解決手順はこの順番です。まずエディタ（VSCodeなど、コードを書くアプリ）で対象プロジェクトを開きます。左側のファイル一覧にpackage.json、src、tests、playwright.configなどが見えているか確認します。次にVSCodeのメニューから「ターミナルを開く」を選びます。このターミナルは、最初からプロジェクトの場所で開いていることが多いです。そこで

、Windowsなら

と入力して、今いる場所を確認します。プロジェクト名が表示されていれば、そのまま

を入力します。

ClaudeCodeが起動したら、「このフォルダで使えるテストコマンドを確認して。実行はまだしないで」と入力します。package.jsonなどを読んで、npmtestやnpmruntestなどが表示されたら正しい場所です。ここまでできれば、もう半分勝ちです。

テストを実行したら大量の赤いエラーで固まる

ClaudeCodeにテスト実行を頼んだあと、ターミナルに赤い文字がずらっと出て、どこを見ればいいかわからなくなる場面もよくあります。初心者ほど「全部ダメなんだ」と感じますが、実際は最初の1個の失敗が連鎖しているだけのことも多いです。

たとえば、必要なパッケージが入っていないだけで100行以上のエラーが出ます。ログイン用の環境変数（パスワードなどをコード外に置く設定）がないだけで、画面テストが全部落ちることもあります。赤い文字の量と問題の大きさは比例しません。

一発で落ち着く手順は、ClaudeCodeに「最後のエラーではなく、最初に発生したエラーを1つだけ特定して。原因を環境、テスト、実装の3つに分類して」と頼むことです。次に、表示された最初の原因だけを直します。依存パッケージ不足なら

を実行します。環境変数不足なら.envファイルを確認します。サーバー未起動なら開発サーバーを起動します。そのあと同じテストをもう1回だけ実行します。

ここでのコツは、同時に3つ直そうとしないことです。初心者が一番混乱するのは、エラーを見て焦り、設定ファイル、テストコード、実装コードを一気に触ってしまうパターンです。1回の修正で触る場所は1か所だけにすると、結果が追いやすくなります。

「知っている」と「できる」の差を埋める実践ロードマップ

最初の7日間は、完璧な自動テスト環境を作ろうとしなくて大丈夫です。ぶっちゃけ、最初からSkillsやHooksまで整えようとすると疲れます。まずは「1つのテストを見つける」「1つ実行する」「1つ失敗を読む」「1つ直す」の順番で十分です。

この7日間で狙うのは、テスト自動化マスターになることではありません。赤いエラーを見ても逃げない状態になることです。1週間で1つのテストを動かせれば十分です。2週目から、Playwrightの画面テストや権限別ログインに進むと、理解がかなり安定します。

現実でよくある「あるある失敗」と専門家の対処法

失敗1いきなり全テストを実行して1時間溶かす

初心者がやりがちなのが、ClaudeCodeに「テスト全部実行して」と頼んでしまうことです。すると、単体テスト、統合テスト、E2Eテスト、古い失敗テストまで全部走り、10分以上待ったあとに大量の失敗が出ます。しかも、自分が確認したい変更と関係ない失敗が混ざるので、何を直せばいいのかわからなくなります。

根本原因は、テストには範囲があるという感覚がまだないことです。初心者は「全部通れば安心」と考えますが、最初の確認で全体を走らせるのは、風邪かどうか知りたいだけなのに全身精密検査を受けるようなものです。時間も気力も使います。

専門家なら、まず変更したファイルを確認します。次に、そのファイルに一番近いテストを探します。ClaudeCodeには「変更したファイルに最も関係が深いテストを1つだけ選んで。全体テストはまだ実行しないで」と頼みます。そのテストが通ったら、関連ディレクトリのテストに広げます。最後に必要があれば全体テストを走らせます。

予防策はシンプルです。テスト実行前に必ず「今回の目的は何か」を1文で書きます。たとえば「ログイン失敗時のエラーメッセージだけ確認する」と書きます。この場面で、対象を1文にすると、ClaudeCodeが余計な範囲まで動かしにくくなり、結果として調査時間が30分から5分に縮みます。

失敗2通ったテストを信じすぎて画面を確認しない

もう1つのあるあるは、PlaywrightのテストがPASSになっただけで安心してしまうことです。あとで画面を見ると、本当は別のボタンを押していた、別の入力欄に文字を入れていた、表示されるべき文言が確認されていなかった、ということがあります。これはかなり怖いです。

根本原因は、テストの成功条件がゆるいことです。たとえば「入力できること」だけを見るテストだと、目的の金額欄ではなく備考欄に入力しても通る場合があります。AIはうまく進めようとするので、指定が曖昧だと代替できそうな要素を選んでしまうことがあります。

専門家なら、操作前、操作中、操作後の3点を見ます。ClaudeCodeには「対象要素が見つからない場合、別要素で代替せず失敗にして。操作前後のスクリーンショットを残して」と頼みます。さらに、ボタンや入力欄は見た目の位置ではなく、ラベル名やrole（画面読み上げにも使われる部品の役割）で特定します。この場面で、roleと表示テキストを使うと、似た見た目の別部品を押す事故が減ります。

予防策として、最初のうちは成功したテストでもスクリーンショットを1回見ます。毎回見る必要はありませんが、新しく作ったテストの初回だけは見たほうがいいです。画面に期待した要素が映っていて、操作後に期待した表示へ変わっていればOKです。

失敗3ClaudeCodeの提案差分を読まずに承認する

初心者が一番やってしまいやすいのが、ClaudeCodeが出した差分をよく読まずに承認することです。テストを直してもらったつもりが、実は期待値を甘くしていただけ、失敗する処理をスキップしていただけ、ということがあります。これだとテストは通りますが、品質はむしろ下がります。

根本原因は、差分を見る習慣がまだないことです。コードの細かい意味がわからないと、赤と緑の表示を見るだけで疲れてしまいます。でも、初心者でも見るべきポイントは限られています。

専門家なら、差分を見るときに3つだけ確認します。1つ目は、実装コードではなくテストの期待値だけが変わっていないか。2つ目は、失敗していた確認処理が削除されていないか。3つ目は、待機時間だけが雑に増えていないかです。ClaudeCodeには「この差分で期待値を甘くしている箇所、確認を削っている箇所、待機時間だけ増やしている箇所があれば指摘して」と入力します。この場面で、差分レビューを先にさせると、危ない修正を承認する前に止められます。

予防策は、承認前に必ず「この変更で何が保証されるようになったのか」をClaudeCodeに1文で説明させることです。説明がふわっとしている場合は、まだ承認しないほうがいいです。「ログイン失敗時にエラー文が表示されることを確認します」のように具体的なら進めて大丈夫です。

ぶっちゃけこうした方がいい！

ぶっちゃけ、完全初心者が最短で結果を出したいなら、最初から完璧なテスト自動化を目指さなくていいです。Skills、Hooks、CI、MCP、権限設計、カバレッジ改善。どれも大事ですが、最初の3日で全部触ると、ほぼ確実に混乱します。まず集中するべきなのは、自分の手元で1つのテストを動かして、結果を読めるようになることです。

正直、最初はE2Eテスト（ブラウザを実際に動かす画面テスト）から入るより、既存の小さな単体テスト（部品1つだけを確認するテスト）を動かすほうがコスパがいいです。画面テストはログイン、権限、待機、ブラウザ設定、テストデータが絡むので、初心者にはノイズが多すぎます。まずは関数1つ、コンポーネント1つ、APIの軽い確認1つで十分です。

おすすめの最短ルートはこうです。1日目にClaudeCodeを起動してテストコマンドを見つけます。2日目に一番小さいテストを1つ実行します。3日目に失敗ログをClaudeCodeに分類させます。4日目に既存テストを読ませます。5日目に小さなケースを1つ追加します。ここまでできたら、ようやくPlaywrightに進みます。遠回りに見えますが、これが一番速いです。

ぶっちゃけ、初心者が最初に覚えるプロンプトは3つだけでいいです。1つ目は「実行はまだしないで、使えるテストコマンドだけ調べて」。2つ目は「最小範囲で実行できるテストを1つだけ選んで」。3つ目は「失敗原因を環境、テスト、実装に分類して」。この3つを使えるだけで、赤いエラーで固まる時間がかなり減ります。

逆に、最初はやらなくていいこともあります。CIへの組み込みはまだ不要です。全体カバレッジ（テストがコード全体の何％を確認しているか）を上げるのも後でいいです。高度なHooks設定も後回しで大丈夫です。これらは、手元でテストを10回くらい実行してからで十分です。最初から仕組みを作ろうとすると、仕組みのエラーとテストのエラーが混ざって、何を直しているのかわからなくなります。

最短で成果を出す人は、だいたい「小さく動かす」のがうまいです。ログイン全体を自動化する前に、入力欄が1つ見つかるか確認します。購入フロー全体を見る前に、ボタンが1つ押せるか確認します。API連携全体を見る前に、レスポンスが1つ返るか確認します。この場面で、小さい確認を1つずつ積むと、失敗しても原因が1つに絞れます。

最後にかなり本音を言うと、ClaudeCodeは「全部お任せの魔法」ではなく、作業の横にいるかなり優秀な先輩くらいに考えるのが一番うまくいきます。先輩に頼むときも、「なんか全部いい感じにして」では困らせますよね。「このテストを1つ動かしたい」「この赤いエラーの最初の原因を知りたい」「この差分が危なくないか見てほしい」と頼むと、ちゃんと助けてくれます。

今日やるなら、たった1つでいいです。プロジェクトを開いて、ClaudeCodeに「このプロジェクトで使えるテストコマンドを調べて。実行はまだしないで」と入力してください。テストコマンドが1つ表示されたら、その日は成功です。そこから1週間かけて1つ動かせば、もう「わかった気がする人」ではなく、実際に手を動かせる人になっています。

よくある質問

最初にどのテストから動かせばいいですか？

変更した箇所に一番近いテストから動かします。関数を直したなら単体テスト、APIを直したなら統合テスト、画面操作を直したならE2Eテストです。いきなり全体テストを走らせると、関係ない失敗に引っ張られて原因が見えにくくなります。

ClaudeCodeが勝手にテストを書き換えたらどうすればいいですか？

差分を確認し、期待値をゆるくする変更が入っていないか見ます。失敗を通すために期待値を変更していた場合は、その変更を戻し、「実装を直すべきか、テストの前提が間違っているのかを先に説明して」と指示します。テストは品質のものさしなので、簡単に甘くしないことが大切です。

CIでもClaudeCodeを使えますか？

使えます。ただし、CIでは人間の確認が入らないため、読み取り専用レビュー、限定されたテスト実行、レポート生成のように役割を絞るのが安全です。実行できるコマンドを限定し、秘密情報をログに出さず、生成された修正は人間がレビューしてから取り込む流れにします。

料金や実行時間が心配なときは？

大きなリポジトリ全体を毎回読ませると、時間もコストも増えます。対象ファイル、関連ディレクトリ、失敗ログ、直近の差分に絞って渡すと効率が上がります。長いセッションで精度が落ちてきたら、必要な結論だけを残して会話を整理し、次の作業へ移ると安定します。

まとめ

ClaudeCodeでテストを実行するコツは、AIに自由に考えさせることではなく、迷わない材料を先に渡すことです。対象、テスト種別、期待結果、失敗時の証跡、安全な権限を決めてから動かすと、初心者でもテスト作成から再実行まで進められます。

今日始めるなら、まずプロジェクトのテストコマンドをClaudeCodeに確認させ、変更した箇所に一番近い小さなテストをひとつ実行します。失敗したらログを分類し、スクリーンショットや差分を見ながら原因を絞ります。そこで得たルールをCLAUDE.mdやSkillsに残せば、次回から同じ説明を繰り返さずに済みます。

最初の成功体験は、小さなテストがひとつ通るだけで十分です。その一歩を積み重ねると、ClaudeCodeは単なるコード生成ツールではなく、テストの準備、実行、記録、改善を支える実務の相棒になります。