/shopping

name: shopping-browser-automation
description: This skill provides tools and techniques for e-commerce website automation. Includes advanced search, product comparison, cart management, checkout process and other common shopping scenarios. Suitable for tasks requiring complex operations on e-commerce websites.

Shopping Browser Automation Skill

This skill is based on Playwright MCP tools, providing automation capabilities for e-commerce websites.

Core Concepts

In shopping website automation, we distinguish two types of operations:

1. **Skill**: Meaningful combinations of multiple tool calls, encapsulated as independent Python scripts 2. **Basic Tools**: Single function calls in `utils.py`, used for atomic operations.

---

I. Skills

1. Simple Search - Type and Submit

**File**: `simple_search.py`

**Use Cases**:

• Need to search for a product using the main search bar
• Want to type a search term and automatically press Enter to submit

**Prerequisites**:

• First use `navigate()` to navigate to the website homepage
• Get the ref value of the search input field

**Usage**:

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

---

2. Advanced Search - By Product Name and Price Range

**File**: `advanced_search_by_name.py`

**Use Cases**:

• Already on the Advanced Search page
• Need to fill in product name and price range for search

**Prerequisites**:

• First use `navigate()` to navigate to the website homepage
• Then use `click()` to click the "Advanced Search" link
• Get the ref values of form fields

**Typical Task Examples**:

• Search for products with name containing "Ginger", price between $50.00 and $100.00
• Search for products with name containing "cookie", price between $20.00 and $40.00

**Usage**:

# 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 and Price Range

**File**: `advanced_search_by_description.py`

**Use Cases**:

• Already on the Advanced Search page
• Need to search keywords in product description (not product name)
• Need to filter by price range

**Prerequisites**:

• First use `navigate()` to navigate to the website homepage
• Then use `click()` to click the "Advanced Search" link
• Get the ref values of form fields

**Typical Task Examples**:

• Search for products with description containing "vitamin", price $0.00-$99.99

**Usage**:

# 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. Checkout - Fill Shipping Information

**File**: `fill_shipping_info.py`

**Use Cases**:

• Already on the checkout page (after clicking "Proceed to Checkout")
• Need to fill in complete shipping address information

**Typical Task Examples**:

• Fill in customer's name, address, city, state, zip code, phone, etc.

**Prerequisites**:

• First use `click()` to click the "Proceed to Checkout" button
• Use `snapshot()` to get all form field ref values

**Usage**:

# 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 test.buyer@example.com Alice Johnson "456 Oak Avenue" "United States" California "San Francisco" 94102 415-555-0123 e33 e46 e51 e65 e75 e80 e85 e90 e95

---

II. Basic Tools (When to Use Single Functions)

Below are the basic tool functions provided in `utils.py` and their use cases. These are atomic operations for flexible combination.

**Note**: Basic tools need to be used in async context. Can be simplified using `run_browser_ops.py`. Code should be written without line breaks.

How to Run

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

Navigation Tools

`navigate(url: str)`

**Use Cases**:

• Open website homepage
• Directly access specific product page URL
• Jump to specific URL

**Example**:

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

---

`navigate_back()`

**Use Cases**:

• Go back to previous page
• Return to search results page after browsing products

**Example**:

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

---

Interaction Tools

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

**Use Cases** (very broad):

• Click navigation menu (categories, subcategories)
• Click product links
• Click "Add to Compare" button
• Click "Add to Cart" button
• Click pagination links (Page 2, Page 3, etc.)
• Click price filters
• Click sort direction toggle

**Example**:

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)`

**Use Cases**:

• Enter keywords in search box
• Fill single form field
• Modify quantity input box

**Example**:

# 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]])`

**Use Cases**:

• Fill multiple form fields (e.g., advanced search form)
• Batch update form data
• Update quantity in shopping cart

**Example**:

# Fill advanced search form
python run_browser_ops.py -c "await browser.fill_form(fields=[{'name': 'Product Name'