Shopping Browser Automation

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')"