shopping-browser-automation

What this skill does

# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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. 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

```bash
# 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**:
```bash
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**:
```bash
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**:
```bash
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**:
```bash
# 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**:
```bash
# 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)`
**Use Cases**:
- Select sort method (Sort By: Price, Relevance, etc.)
- Select country/state/province dropdown
- Select product options (e.g., Flavor, Size, etc.)

**Example**:
```bash
# 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)`
**Use Cases**:
- Submit search (press Enter key)
- Close dialog (press Escape key)

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

---

### Page State Tools

#### `snapshot()`
**Use Cases** (very important):
- When unsure about current page state
- Need to view complete page content to decide next action
- Verify if operation was successful
- Find ref references for specific elements

**Example**:
```bash
python run_browser_ops.py -c "await browser.snapshot()"
```

**Best Practices**:
- Use snapshot before and after critical operations to confirm state
- Use snapshot on search results page to view all products
- Use snapshot after page navigation to confirm page loaded completely

---

#### `get_console_messages()`
**Use Cases**:
- Debug JavaScript errors
- View log information during page loading

---

#### `get_network_requests()`
**Use Cases**:
- Debug network request issues
- View API call status

---

### Wait Tools

#### `wait_for_time(seconds: int)`
**Use Cases**:
- Wait for page to load completely
- Wait for animation effects to finish
- Wait for async data loading

**Example**:
```bash
python run_browser_ops.py -c "await browser.wait_for_time(3)"
```
---

### Tab Management

#### `list_tabs()`
**Use Cases**:
- View all currently open tabs
- Get tab ID

---

#### `tab_new(url: Optional[str] = None)`
**Use Cases**:
- Open product detail page in new ta