Back to Details

shopping-browser-automation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Shopping Browser Automation Skill

购物浏览器自动化Skill

This skill is based on Playwright MCP tools, providing automation capabilities for e-commerce websites.
本Skill基于Playwright MCP工具开发，为电商网站提供自动化能力。

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.
在电商网站自动化中，我们将操作分为两类：
  1. Skill：多个工具调用的有意义组合，封装为独立的Python脚本
  2. 基础工具：
    utils.py
    中的单个函数调用，用于执行原子操作。

I. Skills

I. Skills

1. Simple Search - Type and Submit

1. 简单搜索 - 输入并提交

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
undefined
文件：
simple_search.py
适用场景:
  • 需要通过主搜索栏搜索商品
  • 希望输入搜索关键词后自动按回车键提交
前置条件:
  • 先使用
    navigate()
    导航至网站首页
  • 获取搜索输入框的ref值
使用方法:
bash
undefined

Usage:

Usage:

python simple_search.py <search_term> <search_input_ref>

python simple_search.py <search_term> <search_input_ref>

Example:

Example:

python simple_search.py "gingerbread" e35

---
python simple_search.py "gingerbread" e35

---

2. Advanced Search - By Product Name and Price Range

2. 高级搜索 - 按商品名称与价格区间

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
undefined
文件：
advanced_search_by_name.py
适用场景:
  • 已进入高级搜索页面
  • 需要填写商品名称与价格区间进行搜索
前置条件:
  • 先使用
    navigate()
    导航至网站首页
  • 再使用
    click()
    点击“Advanced Search”链接
  • 获取表单字段的ref值
典型任务示例:
  • 搜索名称包含“Ginger”、价格在50.00美元至100.00美元之间的商品
  • 搜索名称包含“cookie”、价格在20.00美元至40.00美元之间的商品
使用方法:
bash
undefined

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>

python advanced_search_by_name.py <product_name> <price_from> <price_to> <name_ref> <price_from_ref> <price_to_ref> <search_btn_ref>

Example:

Example:

python advanced_search_by_name.py "Ginger" 50.00 100.00 e91 e110 e114 e118

---
python advanced_search_by_name.py "Ginger" 50.00 100.00 e91 e110 e114 e118

---

3. Advanced Search - By Description and Price Range

3. 高级搜索 - 按商品描述与价格区间

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
undefined
文件：
advanced_search_by_description.py
适用场景:
  • 已进入高级搜索页面
  • 需要在商品描述中搜索关键词（而非商品名称）
  • 需要按价格区间筛选商品
前置条件:
  • 先使用
    navigate()
    导航至网站首页
  • 再使用
    click()
    点击“Advanced Search”链接
  • 获取表单字段的ref值
典型任务示例:
  • 搜索描述包含“vitamin”、价格在0.00美元至99.99美元之间的商品
使用方法:
bash
undefined

Usage:

Usage:

python advanced_search_by_description.py <description> <price_from> <price_to> <desc_ref> <price_from_ref> <price_to_ref> <search_btn_ref>

python advanced_search_by_description.py <description> <price_from> <price_to> <desc_ref> <price_from_ref> <price_to_ref> <search_btn_ref>

Example:

Example:

python advanced_search_by_description.py "vitamin" 0.00 99.99 e99 e110 e114 e118

---
python advanced_search_by_description.py "vitamin" 0.00 99.99 e99 e110 e114 e118

---

4. Checkout - Fill Shipping Information

4. 结账 - 填写配送信息

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
undefined
文件：
fill_shipping_info.py
适用场景:
  • 已进入结账页面（点击“Proceed to Checkout”后）
  • 需要填写完整的配送地址信息
典型任务示例:
  • 填写客户姓名、地址、城市、州、邮政编码、电话等信息
前置条件:
  • 先使用
    click()
    点击“Proceed to Checkout”按钮
  • 使用
    snapshot()
    获取所有表单字段的ref值
使用方法:
bash
undefined

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>

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:

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

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

II. 基础工具（何时使用单个函数）

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.
以下是
utils.py
中提供的基础工具函数及其适用场景，这些是可灵活组合的原子操作。
注意：基础工具需要在异步上下文环境中使用，可通过
run_browser_ops.py
简化操作。代码应无换行编写。

How to Run

运行方式

bash
undefined
bash
undefined

Standard format (browser persists across calls)

Standard format (browser persists across calls)

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

Navigation Tools

导航工具

navigate(url: str)

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')"
适用场景:
  • 打开网站首页
  • 直接访问特定商品页面URL
  • 跳转到指定URL
示例:
bash
python run_browser_ops.py -c "await browser.navigate('http://localhost:7770')"

navigate_back()

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()"
适用场景:
  • 返回上一页
  • 浏览商品后回到搜索结果页
示例:
bash
python run_browser_ops.py -c "await browser.navigate_back()"

Interaction Tools

交互工具

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

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')"
适用场景（非常广泛）:
  • 点击导航菜单（分类、子分类）
  • 点击商品链接
  • 点击“Add to Compare”按钮
  • 点击“Add to Cart”按钮
  • 点击分页链接（第2页、第3页等）
  • 点击价格筛选器
  • 点击排序方向切换按钮
示例:
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)

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
undefined
适用场景:
  • 在搜索框中输入关键词
  • 填写单个表单字段
  • 修改数量输入框的值
示例:
bash
undefined

Enter in search box

Enter in search box

python run_browser_ops.py -c "await browser.type_text(ref='e32', text='gingerbread', element='Search input')"
python run_browser_ops.py -c "await browser.type_text(ref='e32', text='gingerbread', element='Search input')"

Press Enter to submit

Press Enter to submit

python run_browser_ops.py -c "await browser.press_key('Enter')"

---
python run_browser_ops.py -c "await browser.press_key('Enter')"

---

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

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
undefined
适用场景:
  • 填写多个表单字段（如高级搜索表单）
  • 批量更新表单数据
  • 更新购物车中的商品数量
示例:
bash
undefined

Fill advanced search form

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

Update cart quantity

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

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

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
undefined
适用场景:
  • 选择排序方式（按价格、相关性等排序）
  • 选择国家/州/省下拉选项
  • 选择商品选项（如口味、尺寸等）
示例:
bash
undefined

Sort by price

Sort by price

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

Select product flavor

Select product flavor

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

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

---

press_key(key: str)

press_key(key: str)

Use Cases:
  • Submit search (press Enter key)
  • Close dialog (press Escape key)
Example:
bash
undefined
适用场景:
  • 提交搜索（按回车键）
  • 关闭对话框（按Esc键）
示例:
bash
undefined

Press Enter after typing in search box

Press Enter after typing in search box

python run_browser_ops.py -c "await browser.press_key('Enter')"

---
python run_browser_ops.py -c "await browser.press_key('Enter')"

---

Page State Tools

页面状态工具

snapshot()

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
适用场景（非常重要）:
  • 不确定当前页面状态时
  • 需要查看完整页面内容以决定下一步操作
  • 验证操作是否成功
  • 查找特定元素的ref引用
示例:
bash
python run_browser_ops.py -c "await browser.snapshot()"
最佳实践:
  • 在关键操作前后使用snapshot确认状态
  • 在搜索结果页使用snapshot查看所有商品
  • 页面导航后使用snapshot确认页面已完全加载

get_console_messages()

get_console_messages()

Use Cases:
  • Debug JavaScript errors
  • View log information during page loading
适用场景:
  • 调试JavaScript错误
  • 查看页面加载过程中的日志信息

get_network_requests()

get_network_requests()

Use Cases:
  • Debug network request issues
  • View API call status
适用场景:
  • 调试网络请求问题
  • 查看API调用状态

Wait Tools

等待工具

wait_for_time(seconds: int)

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)"
适用场景:
  • 等待页面完全加载
  • 等待动画效果结束
  • 等待异步数据加载完成
示例:
bash
python run_browser_ops.py -c "await browser.wait_for_time(3)"

Tab Management

标签页管理

list_tabs()

list_tabs()

Use Cases:
  • View all currently open tabs
  • Get tab ID
适用场景:
  • 查看当前所有打开的标签页
  • 获取标签页ID

tab_new(url: Optional[str] = None)

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')"
适用场景:
  • 在新标签页打开商品详情页（保留搜索结果页）
  • 同时对比多个商品
示例:
bash
python run_browser_ops.py -c "await browser.tab_new(url='http://localhost:7770/product-page.html')"

III. Best Practice Recommendations

III. 最佳实践建议

1. Make Good Use of snapshot()

1. 充分利用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
在以下场景使用
snapshot()
:
  • 刚进入新页面，不确定页面结构时
  • 执行操作后，需要验证结果时
  • 需要查找元素的ref引用时
  • 不确定当前排序顺序（升序/降序）或筛选状态时

Usage Principles

使用原则

  1. Prefer combined skills for fixed workflows: e.g., advanced search, add quantity to cart, fill forms
  2. Use basic tools flexibly for changing scenarios: e.g., click, input, select and other atomic operations
  3. Make good use of 
    snapshot()
    to understand page state    : confirm state before and after critical steps
  1. 固定工作流优先使用组合Skill：如高级搜索、购物车修改数量、表单填写等
  2. 变化场景灵活使用基础工具：如点击、输入、选择等原子操作
  3. 充分利用
    snapshot()
    了解页面状态    ：在关键步骤前后确认页面状态