feeler-e2e

Claude AI を利用した E2E テスト自動化ライブラリ。 テストケースを 自然言語（YAML） で書くだけで、Claude がブラウザ（Playwright/Chromium）を 操作してテストを実行し、HTML / Markdown / JSON の結果報告書 を出力します。

セレクタやテストスクリプトの記述・保守は不要です。設計の詳細は DESIGN.md を参照。

必要なもの

• Node.js 20 以上
• Anthropic API キー（環境変数 ANTHROPIC_API_KEY）

セットアップ（対象プロジェクトへの組み込み）

# 1. 本ライブラリをインストール（npm レジストリから）
npm i -D feeler-e2e

# 2. ブラウザ本体をインストール（初回のみ）
npx playwright install chromium

# 3. 設定と雛形テストを生成（e2e/ ディレクトリが作られる）
npx feeler-e2e init

npm を使わず Git リポジトリから直接インストールすることもできます （prepare スクリプトによりインストール時に自動ビルドされます）:

npm i -D "git+https://github.com/FeelerSystemZ/feeler-e2e.git#v0.1.0"

e2e/feeler-e2e.config.json の baseUrl をテスト対象アプリの URL に変更してください。

認証情報の管理（.env ファイル）

テストアカウントなどの認証情報は YAML に直接書かず、e2e/.env（Git管理外）に保持します。 feeler-e2e init が .env.example を生成し、.gitignore に e2e/.env を自動追加します。

# e2e/.env（コミット禁止）
E2E_USER=test_user
E2E_PASS=secret123
BASIC_USER=admin
BASIC_PASS=basicpw

認証方式の設定（feeler-e2e.config.json）

ID/パスワード方式（フォームログイン）と Basic 認証を、それぞれ・または併用で設定できます。 値は ${変数名} で .env（または環境変数）から参照します。

{
  "baseUrl": "http://localhost:3000",
  "auth": {
    "form":  { "username": "${E2E_USER}", "password": "${E2E_PASS}", "loginPath": "/login" },
    "basic": { "username": "${BASIC_USER}", "password": "${BASIC_PASS}" }
  }
}

• auth.form（ID/パスワード方式） — 実行AIにログイン方法として自動で伝わります。 テストケースには認証情報を書かず、手順に「テストアカウントでログインする」と書くだけで ログインが実行されます（loginPath は省略可）。抽出・生成されるテストケースにも 認証情報は埋め込まれません。
• auth.basic（Basic認証方式） — ブラウザの全リクエストに自動で適用されます。 ステージング環境全体に Basic 認証が掛かっている場合などは、これを設定するだけで テストケース側の対応は不要です。

YAML 内での変数参照

任意の値を ${変数名} で埋め込むこともできます（実行時に展開。未定義ならエラーで停止）:

steps:
  - メールアドレス欄に "${E2E_USER}" を入力する
  - パスワード欄に "${E2E_PASS}" を入力する

SSO環境でのテスト（セッション保存・再利用）

Google / Microsoft 等の SSO ログインが必要なアプリでは、ログインだけ人間が1回行い、 セッションを保存してテストで再利用します（IdP のログイン画面は bot 検知や 2FA が あるため毎回の自動ログインは行いません）。

# 1回だけ: 表示付きブラウザが開くので、手動でSSOログイン（2FA含む）→ ターミナルで Enter
npx feeler-e2e login
# → e2e/.auth/state.json にセッションが保存される（.gitignore 対象）

設定に保存先を指定すると、以降のテスト・生成はすべてログイン済み状態で開始されます：

"auth": { "storageState": ".auth/state.json" }

• テストケースにログイン手順は不要です（AIにも「ログイン済みで開始される」と伝わります）
• セッションが切れたら npx feeler-e2e login を再実行するだけです。 実行時にセッション切れを検知した場合、テストは「保存セッションの期限切れ」として失敗報告されます
• --url /login で最初に開くページを指定できます。form / basic 認証との併用も可能です

ログのマスキング

パスワード類（変数名に pass / secret / token 等を含むもの、および auth の password）は、 進捗ログ・報告書上で自動的に *** にマスクされます。 CI では .env を置かず、シークレット機能から同名の環境変数を注入すれば同じように動きます。

テストケースの書き方

e2e/tests/*.yaml に 1 ファイル = 1 テストケースで記述します。

name: ログイン成功
description: 正しい認証情報でログインできること
tags: [auth, smoke]
steps:                                  # 実行手順（自然言語で自由に書く）
  - ログインページ (/login) を開く
  - メールアドレス欄に "[email protected]" を入力する
  - ログインボタンをクリックする
expect:                                 # 期待結果（1件ずつ合否判定される）
  - ダッシュボードに遷移していること
  - ヘッダーにユーザー名が表示されていること

Web UI（ダッシュボード）

CLI を使わずブラウザ画面から操作できます。

ANTHROPIC_API_KEY=sk-ant-... npx feeler-e2e ui
# → http://127.0.0.1:8765 が自動で開く（--port で変更、--no-open で自動オープン抑止）

画面上でできること:

• テストケースの一覧表示・YAML 編集・新規作成・削除（保存時にバリデーション）
• テスト実行（全件 / 絞り込み / ブラウザ表示のON・OFF）と進捗ログのライブ表示
• ソース解析によるテストケース抽出・ブラウザ探索による生成（ヒント・最大件数を画面で指定）
• 結果報告書の閲覧（画面内プレビュー＋別タブ表示）

サーバーは 127.0.0.1 のみにバインドされ、外部からはアクセスできません。

テストケースの自動抽出（ソースコード解析）

テストケースは手書きせず、AI にソースコードを俯瞰させて抽出できます。 抽出エージェントが srcDir のソースコード（ルーティング・画面・フォーム・バリデーション等）を 読み解き、コードが実装している振る舞いに基づいたテストケースを YAML として書き出します。

# ソースコードを解析してテストケースを抽出（srcDir は設定ファイルで指定）
ANTHROPIC_API_KEY=sk-ant-... npx feeler-e2e extract

# 抽出 → そのまま実行 → OK/NG・実施日時つき報告書出力 まで一括
npx feeler-e2e extract --run

# 解析対象やヒントの指定、書き込まずに内容確認
npx feeler-e2e extract --src ../app --hint "テストアカウント: user1 / pass123" --dry-run

抽出されたケースは testDir に src-01-<ケース名>.yaml として保存されます （既存ファイルは上書きしません）。抽出 → run の流れが基本ですが、--run で一括実行できます。

テストケースの自動生成（実ブラウザ探索）

もう一つの方法として、起動中のアプリを AI が実ブラウザで探索し、 実際に動作確認できたフローだけをテストケースとして提案する generate もあります。

# アプリを起動しておき、探索して最大5件のテストケースを生成
ANTHROPIC_API_KEY=sk-ant-... npx feeler-e2e generate

# テストアカウントや重点領域をヒントとして渡す
npx feeler-e2e generate --hint "テストアカウント: user1 / pass123。決済フローは対象外"

# ファイルを書かずに提案内容だけ確認
npx feeler-e2e generate --dry-run

# その他: --start /admin  --max-cases 8  --headed

生成結果は testDir に gen-01-<ケース名>.yaml として保存されます（既存ファイルは 上書きしません）。生成されたケースは必ず人間がレビューしてから 運用に載せてください。 探索中はデータ削除・購入などの破壊的操作を行わないようプロンプトで制約していますが、 念のためテスト環境に対して実行することを推奨します。

実行

# アプリを起動しておく（例: npm run dev）
ANTHROPIC_API_KEY=sk-ant-... npx feeler-e2e run

# よく使うオプション
npx feeler-e2e run --headed              # ブラウザを表示して実行
npx feeler-e2e run --filter smoke        # 名前/ファイル名/タグで絞り込み
npx feeler-e2e run --base-url http://localhost:8080

実行後、e2e/report/ に以下が出力されます。

| ファイル | 用途 | |---|---| | report.html | 人間向け報告書（サマリ・判定根拠・実行ログ・スクリーンショット） | | report.md | PR コメント等への貼り付け用サマリ | | report.json | CI・機械処理用の全データ | | screenshots/ | 実行中に撮影した画面 |

失敗があると exit code 1 で終了するため、CI にそのまま組み込めます。

プログラマブル API

import { runE2E } from 'feeler-e2e';

const report = await runE2E({
  configPath: 'e2e/feeler-e2e.config.json',
  onProgress: (msg) => console.log(msg),
});

console.log(report.summary); // { total, passed, failed, error, skipped }

テストケースの抽出・生成も同様に呼び出せます。

import { extractE2E, generateE2E } from 'feeler-e2e';

// ソースコード解析による抽出（run: true で抽出→実行→報告書まで一括）
const ext = await extractE2E({
  configPath: 'e2e/feeler-e2e.config.json',
  maxCases: 8,
  hint: 'テストアカウント: user1 / pass123',
  run: true,
});
console.log(ext.writtenFiles);          // 抽出された YAML のパス
console.log(ext.runReport?.summary);    // 実行結果 { total, passed, failed, ... }

// 実ブラウザ探索による生成
const gen = await generateE2E({ configPath: 'e2e/feeler-e2e.config.json', maxCases: 5 });
console.log(gen.writtenFiles);

動作確認用サンプル

examples/ に、公開デモサイト saucedemo.com を対象にした サンプル一式があります。

cd examples
ANTHROPIC_API_KEY=sk-ant-... node ../dist/cli.js run
open report/report.html

設定リファレンス（feeler-e2e.config.json）

| キー | 既定値 | 説明 | |---|---|---| | baseUrl | http://localhost:3000 | テスト対象のベース URL | | testDir | e2e/tests | テストケース YAML の置き場所（設定ファイル基準） | | srcDir | . | extract が解析するソースコードのルート（設定ファイル基準。init 生成時は ..） | | reportDir | e2e/report | 報告書の出力先 | | model | claude-sonnet-5 | 使用する Claude モデル | | headless | true | ヘッドレス実行 | | maxIterationsPerCase | 40 | 1ケースあたりの AI 思考回数上限（暴走防止） | | caseTimeoutMs | 300000 | 1ケースあたりのタイムアウト | | language | ja | AI の判定理由・報告書の言語 | | viewport | 1280x800 | ブラウザのウィンドウサイズ |

リリース手順（ツール管理者向け）

npm レジストリに公開してバージョン配布します。

# 初回のみ: npmjs.com のアカウントでログイン
npm login

# 更新をリリースするとき
#  1. package.json と src/runner.ts の TOOL_VERSION のバージョンを上げる
#     （npm version patch で package.json 更新＋コミット＋タグまで自動）
npm version patch          # 0.1.0 → 0.1.1（minor / major も可）
#  2. 公開（prepare スクリプトで自動ビルドされる）
npm publish
#  3. Git にも反映
git push && git push --tags

利用側プロジェクトは npm update feeler-e2e（または package.json のバージョン指定を 上げて npm install）で更新されます。

注意事項

• API コスト: 1 ケースごとに Claude API を複数回呼び出します（目安: 1ケースあたり数万トークン）。 maxIterationsPerCase と --filter でコストを制御してください。
• 副作用: テストは実ブラウザで実際に操作を行います。本番環境ではなく、 テスト用環境・テスト用アカウントに対して実行してください。
• 非決定性: AI の判断に基づくため、同じテストでも操作経路が変わることがあります。 判定根拠は報告書の「実行ログ」と「根拠」欄で必ず確認できます。