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:

Skill: Meaningful combinations of multiple tool calls, encapsulated as independent Python scripts
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 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

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 tab (keep search results page)
Compare multiple products simultaneously

Example:

bash

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

III. Best Practice Recommendations

1. Make Good Use of snapshot()

Use

snapshot()

in the following situations:

Just entered a new page, unsure about page structure
After executing an operation, need to verify results
Need to find ref references for elements
Unsure about current sort order (descending or ascending) / filter state

Usage Principles

Prefer combined skills for fixed workflows: e.g., advanced search, add quantity to cart, fill forms
Use basic tools flexibly for changing scenarios: e.g., click, input, select and other atomic operations
Make good use of
snapshot()
to understand page state: confirm state before and after critical steps

shopping-browser-automation

NPX Install

Tags

SKILL.md Content

Shopping Browser Automation Skill

Core Concepts

I. Skills

1. Simple Search - Type and Submit

2. Advanced Search - By Product Name and Price Range

3. Advanced Search - By Description and Price Range

4. Checkout - Fill Shipping Information

II. Basic Tools (When to Use Single Functions)

How to Run

Navigation Tools

`navigate(url: str)`

`navigate_back()`

Interaction Tools

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

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

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

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

`press_key(key: str)`

Page State Tools

`snapshot()`

`get_console_messages()`

`get_network_requests()`

Wait Tools

`wait_for_time(seconds: int)`

Tab Management

`list_tabs()`

`tab_new(url: Optional[str] = None)`

III. Best Practice Recommendations

1. Make Good Use of snapshot()

Usage Principles