shopping-browser-automation

ショッピングブラウザー自動化スキル

このスキルは Playwright MCP ツールをベースとしており、EC サイトの自動化機能を提供します。

基本概念

ショッピングサイトの自動化では、次の 2 種類の操作を区別します。

1. スキル：複数のツール呼び出しを組み合わせた意味のある操作を、独立した Python スクリプトとしてカプセル化したものです
2. 基本ツール：utils.py にある単一の関数呼び出しで、アトミックな操作に使用します。

---

I. スキル

1. 簡易検索 - 入力して送信

ファイル：simple_search.py

使用例：

• メインの検索バーを使って商品を検索する場合
• 検索語を入力し、自動的に Enter キーを押して送信する場合

前提条件：

• まず navigate() を使用してウェブサイトのホームページに移動します
• 検索入力フィールドの ref 値を取得します

使用方法：

# Usage:
#   python simple_search.py <search_term> <search_input_ref>
# Example:
python simple_search.py "gingerbread" e35

---

2. 高度な検索 - 商品名と価格帯で検索

ファイル：advanced_search_by_name.py

使用例：

• すでに高度な検索ページを開いている場合
• 商品名と価格帯を入力して検索する場合

前提条件：

• まず navigate() を使用してウェブサイトのホームページに移動します
• 次に click() を使用して「高度な検索」リンクをクリックします
• フォームフィールドの ref 値を取得します

一般的なタスク例：

• 名前に「Ginger」を含み、価格が $50.00〜$100.00 の商品を検索する
• 名前に「cookie」を含み、価格が $20.00〜$40.00 の商品を検索する

使用方法：

# Usage:
#   python advanced_search_by_name.py <product_name> <price_from> <price_to> <name_ref> <price_from_ref> <price_to_ref> <search_btn_ref>
# Example:
python advanced_search_by_name.py "Ginger" 50.00 100.00 e91 e110 e114 e118

---

3. 高度な検索 - 説明と価格帯で検索

ファイル：advanced_search_by_description.py

使用例：

• すでに高度な検索ページを開いている場合
• 商品名ではなく、商品説明に含まれるキーワードを検索する場合
• 価格帯で絞り込む場合

前提条件：

• まず navigate() を使用してウェブサイトのホームページに移動します
• 次に click() を使用して「高度な検索」リンクをクリックします
• フォームフィールドの ref 値を取得します

一般的なタスク例：

• 説明に「vitamin」を含み、価格が $0.00〜$99.99 の商品を検索する

使用方法：

# Usage:
#   python advanced_search_by_description.py <description> <price_from> <price_to> <desc_ref> <price_from_ref> <price_to_ref> <search_btn_ref>
# Example:
python advanced_search_by_description.py "vitamin" 0.00 99.99 e99 e110 e114 e118

---

4. チェックアウト - 配送情報の入力

ファイル：fill_shipping_info.py

使用例：

• チェックアウトページを開いている場合（「チェックアウトに進む」をクリックした後）
• 配送先住所の情報をすべて入力する場合

一般的なタスク例：

• 顧客の氏名、住所、市区町村、州、郵便番号、電話番号などを入力する

前提条件：

• まず click() を使用して「チェックアウトに進む」ボタンをクリックします
• snapshot() を使用してすべてのフォームフィールドの ref 値を取得します

使用方法：

# Usage:
#   python fill_shipping_info.py <email> <first_name> <last_name> <street> <country> <state> <city> <zipcode> <phone> <email_ref> <fname_ref> <lname_ref> <street_ref> <country_ref> <state_ref> <city_ref> <zip_ref> <phone_ref>
# Example:
python fill_shipping_info.py [email protected] Alice Johnson "456 Oak Avenue" "United States" California "San Francisco" 94102 415-555-0123 e33 e46 e51 e65 e75 e80 e85 e90 e95

---

II. 基本ツール（単一の関数を使う場合）

以下は、utils.py で提供される基本ツール関数とその使用例です。これらは、柔軟に組み合わせて使えるアトミックな操作です。

注：基本ツールは async コンテキストで使用する必要があります。run_browser_ops.py を使うと簡略化できます。コードは改行せずに記述してください。

実行方法

# Standard format (browser persists across calls)
python run_browser_ops.py -c "await browser.navigate('http://localhost:7770')"

ナビゲーションツール

navigate(url: str)

使用例：

• ウェブサイトのホームページを開く
• 特定の商品ページの URL に直接アクセスする
• 特定の URL に移動する

例：

python run_browser_ops.py -c "await browser.navigate('http://localhost:7770')"

---

navigate_back()

使用例：

• 前のページに戻る
• 商品を閲覧した後、検索結果ページに戻る

例：

python run_browser_ops.py -c "await browser.navigate_back()"

---

操作ツール

click(ref: str, element: Optional[str] = None)

使用例（幅広く使えます）：

• ナビゲーションメニュー（カテゴリ、サブカテゴリ）をクリックする
• 商品リンクをクリックする
• 「比較に追加」ボタンをクリックする
• 「カートに追加」ボタンをクリックする
• ページネーションリンク（2 ページ目、3 ページ目など）をクリックする
• 価格フィルターをクリックする
• 並べ替え順の切り替えをクリックする

例：

python run_browser_ops.py -c "await browser.click(ref='e56', element='Health & Household menu item')"

---

type_text(ref: str, text: str, element: Optional[str] = None)

使用例：

• 検索ボックスにキーワードを入力する
• 1 つのフォームフィールドに入力する
• 数量入力欄を変更する

例：

# Enter in search box
python run_browser_ops.py -c "await browser.type_text(ref='e32', text='gingerbread', element='Search input')"
# Press Enter to submit
python run_browser_ops.py -c "await browser.press_key('Enter')"

---

fill_form(fields: List[Dict[str, str]])

使用例：

• 複数のフォームフィールドに入力する（例：高度な検索フォーム）
• フォームデータを一括更新する
• ショッピングカート内の数量を更新する

例：

# Fill advanced search form
python run_browser_ops.py -c "await browser.fill_form(fields=[{'name': 'Product Name', 'ref': 'e111', 'value': 'cookie'}, {'name': 'Price From', 'ref': 'e134', 'value': '20.00'}, {'name': 'Price To', 'ref': 'e138', 'value': '40.00'}])"

# Update cart quantity
python run_browser_ops.py -c "await browser.fill_form(fields=[{'name': 'Qty', 'ref': 'e141', 'value': '3'}])"

---

select_option(ref: str, element_desc: str, value: str)

使用例：

• 並べ替え方法を選択する（並べ替え：価格、関連度など）
• 国／州／県のドロップダウンを選択する
• 商品オプションを選択する（例：フレーバー、サイズなど）

例：

# Sort by price
python run_browser_ops.py -c "await browser.select_option(ref='e114', element_desc='Sort By dropdown', value='Price')"

# Select product flavor
python run_browser_ops.py -c "await browser.select_option(ref='e128', element_desc='Flavor', value='Peanut Butter')"

---

press_key(key: str)

使用例：

• 検索を送信する（Enter キーを押す）
• ダイアログを閉じる（Escape キーを押す）

例：

# Press Enter after typing in search box
python run_browser_ops.py -c "await browser.press_key('Enter')"

---

ページ状態ツール

snapshot()

使用例（非常に重要）：

• 現在のページ状態がわからない場合
• 次の操作を決めるため、ページ全体の内容を確認する必要がある場合
• 操作が成功したか確認する場合
• 特定の要素の ref 参照を見つける場合

例：

python run_browser_ops.py -c "await browser.snapshot()"

ベストプラクティス：

• 重要な操作の前後に snapshot を使用して、状態を確認します
• 検索結果ページで snapshot を使用して、すべての商品を確認します
• ページ遷移後に snapshot を使用して、ページが完全に読み込まれたことを確認します

---

get_console_messages()

使用例：

• JavaScript エラーをデバッグする
• ページ読み込み中のログ情報を確認する

---

get_network_requests()

使用例：

• ネットワークリクエストの問題をデバッグする
• API 呼び出しの状態を確認する

---

待機ツール

wait_for_time(seconds: int)

使用例：

• ページが完全に読み込まれるまで待機する
• アニメーション効果が終了するまで待機する
• 非同期データの読み込みを待つ

例：

python run_browser_ops.py -c "await browser.wait_for_time(3)"

---

タブ管理

list_tabs()

使用例：

• 現在開いているすべてのタブを確認する
• タブ ID を取得する

---

tab_new(url: Optional[str] = None)

使用例：

• 商品詳細ページを新しいタブで開く（検索結果ページは保持する）
• 複数の商品を同時に比較する

例：

python run_browser_ops.py -c "await browser.tab_new(url='http://localhost:7770/product-page.html')"

III. ベストプラクティスの推奨事項

1. snapshot() を有効活用する

次のような状況では snapshot() を使用します：

• 新しいページに移動した直後で、ページ構造がわからない場合
• 操作を実行した後、結果を確認する必要がある場合
• 要素の ref 参照を見つける必要がある場合
• 現在の並べ替え順（降順または昇順）／フィルター状態がわからない場合

---

使用原則

1. 決まったワークフローには、組み合わせ済みのスキルを優先する：例：高度な検索、数量を指定してカートに追加する、フォームに入力する
2. 変化するシナリオには、基本ツールを柔軟に使用する：例：クリック、入力、選択などの個別操作
3. snapshot() を有効活用してページ状態を把握する：重要な手順の前後で状態を確認します