shopping-admin-browser-automation

What this skill does

# Shopping Admin Browser Automation Skill

This skill is based on Playwright MCP tools, providing automation capabilities for Magento Admin panel.

## Core Concepts

In admin panel 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 used for atomic operations.

---

## I. Skills

### 1. Admin Login

**Use Cases**:
- Login to Magento Admin panel at the start of admin tasks
- Authenticate with admin credentials

**Prerequisites**:
- Get ref values for form fields

**Usage**:
```bash
# Usage:
#   python admin_login.py <admin_url> <username> <password> <username_ref> <password_ref> <signin_ref>
# Example:
python admin_login.py http://localhost:7780/admin admin admin1234 e15 e20 e23
```

---

### 2. Create Customer

**Use Cases**:
- Create a new customer after clicking "Add New Customer" button
- Add customers to specific customer groups


**Usage**:
```bash
# Usage:
#   python create_customer.py <first_name> <last_name> <email> <group> <group_ref> <fname_ref> <lname_ref> <email_ref> <save_btn_ref>
# Example:
python create_customer.py "Isabella" "Romano" "[email protected]" "Premium Europe" e92 e112 e124 e136 e61
```

---

## II. Basic Tools (When to Use Single Functions)

Below are the basic tool functions and their use cases. These are atomic operations for flexible combination.

**Note**: 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:7780/admin')"
```

### Navigation Tools

#### `navigate(url: str)`
**Use Cases**:
- Open admin panel URL
- Navigate to specific admin pages

**Example**:
```bash
python run_browser_ops.py -c "await browser.navigate('http://localhost:7780/admin')"
```

---

#### `navigate_back()`
**Use Cases**:
- Go back to previous page
- Return to list page after viewing details

**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 items (Customers, Marketing, Reports, etc.)
- Click submenu links (All Customers, Customer Groups, Search Terms, etc.)
- Click action buttons (Add New, Save, Search, Reset Filter)
- Click table rows for details

**Example**:
```bash
# Click Customers menu
python run_browser_ops.py -c "await browser.click(ref='e17', element='Customers menu')"

# Click All Customers link
python run_browser_ops.py -c "await browser.click(ref='e182', element='All Customers link')"
```

---

#### `type_text(ref: str, text: str, element: Optional[str] = None)`
**Use Cases**:
- Enter text in form fields
- Fill filter inputs
- Enter search terms

**Example**:
```bash
# Enter username
python run_browser_ops.py -c "await browser.type_text(ref='e15', text='admin', element='Username textbox')"

# Enter filter value
python run_browser_ops.py -c "await browser.type_text(ref='e109', text='tank', element='Search Query filter input')"
```

---

#### `select_option(ref: str, element_desc: str, value: str)`
**Use Cases**:
- Select dropdown values (Customer Group, Status filter, Store View)
- Select options in forms

**Example**:
```bash
# Select customer group
python run_browser_ops.py -c "await browser.select_option(ref='e92', element_desc='Group select', value='Premium Europe')"

# Select status filter
python run_browser_ops.py -c "await browser.select_option(ref='e124', element_desc='Status filter combobox', value='Subscribed')"
```

---

#### `press_key(key: str)`
**Use Cases**:
- Submit forms (press Enter)
- Close dialogs (press Escape)

**Example**:
```bash
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 after navigation to find element refs
- Use snapshot to verify data in tables and grids

---

### Tab Management

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

---

#### `tab_new(url: Optional[str] = None)`
**Use Cases**:
- Open admin section in new tab
- Compare data across multiple pages

**Example**:
```bash
python run_browser_ops.py -c "await browser.tab_new(url='http://localhost:7780/admin/customer/index/')"
```

---

## III. Best Practice Recommendations

### 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 state of filters or grids

## Usage Principles

1. **Start with admin_login.py**: Most admin tasks require authentication first
2. **Use snapshot() liberally**: Admin pages have complex structures, verify state
3. **Use basic tools for dynamic refs**: Element refs may change, use snapshot to find current refs