テストケースをコードで書かないE2Eテスト ── Claude CodeとPlaywright CLIで実現する自然言語テスト自動化

はじめに

こんにちは、カート決済部カート決済サービスAブロックの道場です。ZOZOTOWN内のカート機能や決済機能の開発、保守運用を担当しています。

現在、ZOZOTOWNのカート決済画面はリプレイスが進行中です。既存システムとリプレイス後のシステムが並行して開発される中、既存システムへのさまざまな機能改修を、リプレイス側にも取り込む必要があります。その際、条件の組み合わせが膨大になるテストを手動で網羅的に実施することが現実的でなく、特に注文金額の計算結果の正確性を人間が1件ずつ確認するには大きなコストがかかっていました。

本記事では、Claude CodeとPlaywright CLIを組み合わせて、自然言語によるE2Eテストを自動化した仕組みをご紹介します。Confluence（Atlassian社が提供するナレッジ共有ツール）に自然言語でテスト手順を記述することでAIが自律的にブラウザを操作し、計算検証も含めてE2Eテストを完結させています。コードを書かずにテストを作成・実行できるため、テスト自動化の属人化解消にもつながりました。

目次

背景・課題

リプレイスに伴う二重開発とテストの課題

冒頭の通り、ZOZOTOWNのカート決済画面ではリプレイスが進行中です。既存システムとリプレイス後のシステムが並行して動作する期間中、既存システムに対するさまざまな機能改修をリプレイス側へ取り込む必要があります。

これらの改修をすべて取り込み、条件の組み合わせが爆発的に増加するテストケースを検証する工数が大きな課題となりました。

たとえば、ある案件の機能を取り込む場合、以下のような因子が絡み合います。

• ユーザーの属性（性別・年齢 等）
• 購入商品の種類・金額
• 割引・クーポンの有無
• ポイント利用の有無
• キャンペーン期間の内外

これらを組み合わせると、1つの案件だけで100件以上のテストケースが発生することもありました。さらに、各テストケースでは注文フローの複数画面（配送・支払い選択、注文の確認 等）で表示値の確認が必要です。そして、PC用の画面とスマートフォン（以下、SPと表記します）用の画面がそれぞれ存在するため、検証量は実質的にさらに倍になります。

カート決済画面では、注文金額の計算ロジックにさまざまな要素が関わっており、前述の通り案件ごとに条件の組み合わせが大きくなりがちでした。さらに、期待値は複雑な計算式で決まるため、人間が1件ずつ手計算したうえで画面の表示と照合するには多くの時間がかかっていました。

なぜ従来のE2E自動化では足りなかったのか

ZOZOTOWNでは、手動テストに加えて品質管理部によるコードベースのE2E自動テストも活用しています。しかし、そのような従来のコード記述型の自動テストを使ったアプローチでは以下の課題がありました。

• プログラミングスキルへの依存：CSSセレクタやロールを使った要素特定のコードを書く必要があるため、開発者でなければ作成・保守が難しい
• UI変更への追従コスト：UIの変更に応じて、要素特定の方法やテスト内容のメンテナンスが必要になる
• テストコードの属人化：記述・保守できる人が限られるため、特定の開発者への依存が生じる

実現したかったのは、テスト手順を自然言語で書くだけで、AIが要素を自動で見つけて操作し、計算検証まで完結する仕組みです。そのためのアプローチとして、Claude CodeのAgent SkillsとPlaywright CLIを組み合わせた自動化システムを構築しました。

AIエージェント駆動のE2Eテストシステム

全体アーキテクチャ

構築したシステムの全体像は以下の通りです。

各コンポーネントの役割は次の通りです。

Claude CodeのエージェントがConfluenceからテストケースを読み取ります。Agent Skillsを参照しながらPlaywright CLIでブラウザを操作し、結果をConfluenceに書き戻します。

Playwright CLIによるブラウザ操作

Playwright CLIは、ブラウザ操作をコマンドで実行できるCLIツールです。テストコードを書く代わりに、コマンド1つでブラウザを操作できます。Playwright MCPもありますが、CLIの方がトークン使用量を節約できるため選択しています。

特徴的なのはスナップショット機能です。ページを開くと、Playwright CLIはページの構造をYAML形式で取得します。このとき各要素にはref番号が付与されています。AIはこのスナップショットを読んで要素を特定し、ref番号を使って操作します。

# ref番号を使って要素をクリック
playwright-cli click e42 --session=pc

# テキストを入力
playwright-cli fill e15 "test@example.com" --session=pc

# スクリーンショットを取得
playwright-cli screenshot --output screenshots/cart-top.png --session=pc

CSSセレクタやロールを明示的に指定しなくても、AIがスナップショットを解釈して要素を特定できます。そのため、セレクタベースの実装に比べると、軽微なUI変更には追従しやすくなります。

PCとSPの切り替えは設定ファイルで行います。

// playwright-cli.json（PC用）
{
  "browser": {
    "launchOptions": { "headless": false },
    "isolated": false,
    "contextOptions": {
      "viewport": { "width": 1400, "height": 1080 }
    }
  }
}

// playwright-cli-sp.json（SP用）
{
  "browser": {
    "launchOptions": { "headless": false },
    "isolated": false,
    "contextOptions": {
      "viewport": { "width": 430, "height": 932 },
      "userAgent": "Mozilla/5.0 (iPhone; ...) Safari/604.1",
      "isMobile": true,
      "hasTouch": true
    }
  }
}

PCテストとSPテストは別セッションで同時に実行できるため、テスト時間の短縮にも貢献します。

Agent Skillsによる操作手順の定義

Agent Skillsでは、Claude CodeのSkill機能を活用してZOZOTOWN固有の操作手順を定義しています。コードベースのPlaywrightにおけるPage Object Modelに相当する役割を、Markdownによる自然言語の手順書で担うイメージです。

操作手順は次のように自然言語で記述します。

# ログイン手順リファレンス

## 手順

1. 以下のページを開く
  - PC: \`/_member/login.html\`
  - SP: \`/sp/_member/login.html\`
2. \`メールアドレス\` 入力欄にメールアドレスを入力する。
3. \`パスワード\` 入力欄にパスワードを入力する。
4. \`ログイン\` ボタンをクリックする。

テストケースに「テストユーザーAのアカウントでログインする」と書けば、エージェントがこのリファレンスを参照して手順を実行します。操作をリファレンスとして標準化しておくことで、誰が書いたテストケースでも同じ操作が再現できます。

今回定義した主要なリファレンスは次の通りです。

• login-flow.md：ログイン手順（PC / SP対応）
• add-to-cart-flow.md：商品をカートへ投入する手順
• order-flow.md：注文フロー（カートTOP → 配送・支払い選択 → 注文確認 → 注文完了）
• sql-execution-flow.md：SQL Serverへのクエリ実行手順

テストケースの設計と期待値の保証

Confluenceベースのテストケース管理

テストケースはConfluenceページで管理しています。ページの構成は次の通りです。

テスト実行後は、Claude Codeがこのページに結果（OK / NG）とスクリーンショットを自動で書き込みます。

実際に実施したテストケースの例を紹介します。

注文金額に関わる計算ロジックの検証テスト：注文の確認画面に表示される金額が、計算サービスの算出結果と一致することを検証します。前述の因子を組み合わせた数十件のパターンを定義しています。

テストの手順は、Confluenceページに次のように自然言語で記述されています。

1. カートを空にする
2. パラメータ（商品）に記載されている商品をカートに入れる
3. 注文へ進み、パラメータ（支払い方法）の支払い方法を選択して注文確認画面を表示する
4. 表示されている計算結果の値が
   OrderAmountCalculationService.getの値と
   一致していることを確認する
5. viewportのスクリーンショットを取得する
6. パラメータ（ポイント利用）に記載のポイントを利用する
7. 表示されている計算結果の値が上記計算サービスの値と一致していることを確認する
...

この手順をClaude Codeが読み取り、Agent Skillsを参照しながらブラウザを操作します。

計算が必要なテストの期待値保証

計算結果の検証は、今回の取り組みで最も重要なポイントです。

課題：注文金額に関わる複雑な計算結果を、人間が手計算して期待値と照合するには大きな工数が必要です。特に、割引・クーポン・ポイント利用・税率が絡み合う計算は、ミスが発生しやすく時間もかかっていました。

解決策：Playwrightテスト用リポジトリにTypeScriptで計算サービスを実装し、あらかじめ期待値を算出しておきます。Claude Codeはテスト計画の作成時に計算サービスを呼び出し、期待値をプランに出力してから、ブラウザの表示値と照合します。

// ZOZOCARD還元ポイントを計算するクラス
export class ZozocardRewardPointCalculationService {
  private static readonly POINT_RETURN_RATE = 0.05;

  public get(
      goodsPriceWithoutTax: number,
      quantity: number,
      taxRate: number
  ): number {
    // ZOZOCARD 還元ポイントの計算処理...
  }
}

この計算処理は、システムと同じ仕様をもとにClaude Codeで生成した独立した実装になっています。システム側の実装コードをそのまま流用すると、同じバグを共有してしまいます。仕様を別実装することで、システム側とテスト側の独立性を保っています。これにより、期待値とシステムの表示値を照合したときに、単なる一貫性チェックではなく、システム側の実装が仕様どおりかを検証できます。実際に、このテストを通じてシステム側の実装が仕様を正しく考慮できていないケースを検知できた事例もありました。

期待値の検証フローは次の通りです。

Claude Codeはテスト計画を作成する段階で計算サービスを実行し、全テストケースの期待値を事前に算出します。テスト実行時には、ブラウザで取得した表示値と事前に算出した期待値を照合します。

テスト実行の6つのStep

エージェント定義ファイル（zozotown-qa-tester.md）では、テスト実行を次の6つのStepで定義しています。

---
name: zozotown-qa-tester
description: ZOZOTOWN の QA テストを実行するエージェント
skills:
    - playwright-cli
    - zozotown-operations
    - confluence-page-operations
    - atlassian-cli
    - zozo-sql-server-cli
---

## テスト実行フロー

### 1. テストケースの確認
Confluenceページからテストケースを取得し、
対象の開発環境・前提条件・手順・期待結果を読み取る。

### 2. テストケースプランの作成
テストデータ・期待値（計算サービスの実行結果）・実行手順を整理し、
\`test-plans/\` ディレクトリにMarkdownファイルとして出力する。
**ユーザーの承認を得てからテスト実行に進む。**

### 3. テスト準備
ブラウザを起動し、ログインや初期データのセットアップを行う。

### 4. テスト実行
各ステップを\`zozotown-operations\`のリファレンスに従って実行する。
手順が定義されていない操作は、実際にブラウザで確認して新しいリファレンスを作成する。

### 5. 結果の記録
実行結果（OK / NG）を判定し、スクリーンショットを撮影して
Confluenceページに結果とエビデンスを書き込む。

### 6. 結果の報告
ユーザーに実行結果のサマリを報告する。

特に重要なのはStep 2のテストケースプランの作成とユーザー承認です。AIは非決定的に動作するため、テストケースの解釈が意図と異なる可能性があります。実行前に計画を提示してユーザーに確認することで、解釈のズレを事前に検出できます。

また、Step 4の「リファレンスに手順がない操作は自ら作成する」という仕組みにより、エージェントが新しい操作手順を発見するたびにリファレンスファイルが自動的に追加されていきます。使うほどにリファレンスが充実し、テスト作成が楽になっていく仕組みです。

実際のテスト実行では、テスト計画の確認とPC / SPセッションの並列実行をターミナル上で確認できます。

テスト支援ツールの構築

atlassian-cli：Confluence操作のCLI

Confluenceのテストケースページを詳細に処理するため、atlassian-cliを作成しました。Atlassian MCPもありますが、スクリーンショットを添付できないため、REST APIをラップしたCLIです。

テスト実行フローでの使用例を示します。

# Confluence のテストケースページを取得
atlassian-cli confluence get-page 348678105 --body-format atlas_doc_format

# テスト結果のスクリーンショットをアップロード
atlassian-cli confluence upload-attachment 348678105 \
  --file ./screenshots/confirm-pc.png

# テスト結果をページに追記
atlassian-cli confluence update-page 348678105 \
  --body-file ./test-results/result.json \
  --page-version 41

zozo-sql-server-cli：SQL Serverクエリ実行CLI

注文完了後のDBデータを検証するため、zozo-sql-server-cliも作成しました。注文データが正しく保存されているかをSQLで確認し、結果をHTMLテーブルとして描画してPuppeteerでスクリーンショット化する機能が特徴です。

# SQL クエリを実行してテーブル形式で表示
zozo-sql-server-cli \
  "SELECT total_amount, discount_amount FROM orders WHERE order_id = 12345"

# クエリ結果をスクリーンショット（HTMLテーブルとして描画）として保存
zozo-sql-server-cli \
  "SELECT total_amount, discount_amount FROM orders WHERE order_id = 12345" \
  --screenshot ./screenshots/order-db.png

このスクリーンショットをそのままConfluenceのエビデンスとして添付することで、DB検証の証跡も自動的に記録できます。

AIエージェントが必要なツールを自ら作る

atlassian-cliとzozo-sql-server-cliは、いずれもClaude Codeを活用して作成しました。

テスト自動化を進める中で「Confluenceにスクリーンショットを添付したい」「DBの検証結果を画像として保存したい」といったニーズが生まれました。これらをCLIとしてClaude Codeに実装してもらい、短期間で必要な機能を揃えることができました。

AIエージェントに必要なツールをAI自身が作れるという点は、自動化のエコシステムを大幅に加速させます。

従来のテスト自動化との比較

従来のコードベースのE2E自動テストと、今回構築したClaude Code + Playwright CLIのアプローチを比較します。

最も大きな違いは、テストコードの記述・保守スキルがなくてもE2Eテストを作成・実行できる点です。

Confluenceでテスト手順を書く際には「テストユーザーAでログインする」「XXXの商品をカートに入れる」といった日常的な言葉で記述できます。Agent Skillsのリファレンスにログインやカート投入の手順が定義されているため、この自然言語の指示だけでAIが正確に操作を再現します。

また、計算検証の自動化により、人手では高コストだった期待値照合をAIが実行できるようになりました。開発者は別の案件の開発を進めながら、Claude Codeにテストを並行して実行させることができます。

実践から得られた知見

テストケースの実績

実際に実施したテストの実績は次の通りです。

手動でのフローと、今回構築したAIエージェント活用後のフローを比較すると次のようになります。

人が行うのは、テスト計画のレビューのみです。数十件のテストケース × 複数ページ × PC / SPの全テストをClaude Codeに任せられました。案件Aでは詳細な計算結果を、案件Bでは肥大化する条件の組み合わせを検証でき、人手による手計算や確認にかかる工数を大きく減らせました。

実践を通じた気づき

Agent Skillsの粒度設計：ログインやカート投入、注文フローというような1つの手順として指示する粒度がちょうどよく、再利用しやすいです。細かすぎるとリファレンスが増えすぎて管理が難しくなり、粗すぎると他のテストケースで使いにくくなります。

テスト計画承認フローの効果：「2. テストケースプランの作成」でAIが作成した計画をレビューすることで、テストケースの解釈ミスを事前に検出できた事例がありました。コーディング時もそうですが、私はClaude Codeのプランモードをよく利用します。何をするかを綿密に考えさせたものを自分が確認することで、あとはそれを実行するだけになり、質が高くなると感じています。

自己改善するリファレンス：未定義の操作に遭遇した際、エージェントが実際にブラウザで操作して手順を確認し、新しいリファレンスファイルを自動作成する仕組みは実用的でした。テストを重ねるほどリファレンスが充実し、環境を育てていくことで後のテスト作成が楽になっていきます。

まとめ

本記事では、Claude CodeとPlaywright CLIを組み合わせた自然言語E2Eテストの構築と実践をご紹介しました。Confluenceに自然言語でテスト手順を記述するだけでAIが自律的にブラウザを操作し、計算検証も含めてE2Eテストを完結させることができました。

膨大な組み合わせテストの自動化・計算検証の正確性担保・テスト自動化の属人化解消という課題を同時に解決し、開発者が別の案件を進めながらテストを並行完了できる体制が実現しました。今後は他の画面への展開や、定期的な実行によるリグレッションの検知などを検討していきたいと考えています。

ZOZOでは、一緒にサービスを作り上げてくださる方を募集中です。ご興味のある方は、ぜひ採用ページをご覧ください。

corp.zozo.com