@puberty-labs/clits/docs/AI_EXAMPLES.md

CLiTS (Chrome Logging and Inspection Tool Suite) is a powerful Node.js library for AI-controlled Chrome browser automation, testing, and inspection. Features enhanced CSS selector support (:contains(), XPath), dry-run mode, element discovery tools, and co

# 🤖 CLITS AI Examples - Copy-Pasteable Commands

## Quick Reference for AI Assistants

This document provides ready-to-use CLITS command sequences for common automation scenarios. All examples assume Chrome is running with remote debugging on port 9222.

## 🚀 **Environment Setup Commands**

### **Chrome Debug Setup**
```bash
# macOS - Start Chrome with debugging
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Verify connection  
curl http://localhost:9222/json/version

# Test CLITS connection
clits inspect --list-tabs
```

### **Quick Status Check**
```bash
# Check CLITS version
clits --version

# List all browser tabs
clits inspect --tabs --json

# Take current page screenshot
clits vision --screenshot
```

## 📋 **Form Interaction Examples**

### **Basic Form Filling**
```bash
# Navigate to form page
clits navigate --url "https://example.com/contact"
clits wait --timeout 3000

# Fill text inputs
clits interact --type "[data-testid='name']" --text "John Doe"
clits interact --type "[data-testid='email']" --text "john@example.com"
clits interact --type "[data-testid='message']" --text "Hello world"

# Submit form
clits interact --click "[data-testid='submit-button']"
clits wait --timeout 5000

# Verify success
clits vision --screenshot
clits extract --text ".success-message"
```

### **Multi-Step Form with Validation**
```bash
# Navigate and wait
clits navigate --url "https://app.example.com/signup"
clits wait --timeout 3000

# Step 1: Basic Info
clits interact --type "[data-testid='username']" --text "johndoe123"
clits interact --click "[data-testid='next-step']"
clits wait --element "[data-testid='password-section']" --timeout 5000

# Step 2: Password
clits interact --type "[data-testid='password']" --text "SecurePass123!"
clits interact --type "[data-testid='confirm-password']" --text "SecurePass123!"
clits interact --click "[data-testid='create-account']"

# Verify completion
clits wait --timeout 10000
clits vision --screenshot
clits extract --text ".confirmation-message"
```

### **Dynamic Form with Dropdown**
```bash
# Open dropdown
clits interact --click "[data-testid='country-select']"
clits wait --element "[data-testid='country-options']" --timeout 3000

# Select option by text
clits interact --click-text "United States"

# Alternative: Select by value
clits interact --click "[data-value='US']"

# Verify selection
clits extract --text "[data-testid='country-select'] .selected-value"
```

## 🛒 **E-commerce Examples**

### **Product Search & Purchase**
```bash
# Navigate to store
clits navigate --url "https://store.example.com"
clits wait --timeout 3000

# Search for product
clits interact --type "[data-testid='search-input']" --text "wireless headphones"
clits interact --click "[data-testid='search-button']"
clits wait --timeout 5000

# Select first product
clits interact --click "[data-testid='product-card']:first-child"
clits wait --timeout 3000

# Add to cart
clits interact --click "[data-testid='add-to-cart']"
clits wait --element "[data-testid='cart-notification']" --timeout 5000

# Verify cart update
clits extract --text "[data-testid='cart-count']"
```

### **Shopping Cart Management**
```bash
# View cart
clits interact --click "[data-testid='cart-icon']"
clits wait --element "[data-testid='cart-items']" --timeout 3000

# Update quantity
clits interact --clear "[data-testid='quantity-input']"
clits interact --type "[data-testid='quantity-input']" --text "2"
clits interact --click "[data-testid='update-quantity']"

# Remove item
clits interact --click "[data-testid='remove-item']"
clits wait --timeout 3000

# Verify changes
clits extract --text "[data-testid='cart-total']"
clits vision --screenshot
```

## 📊 **Data Extraction Examples**

### **Table Data Extraction**
```bash
# Navigate to data page
clits navigate --url "https://dashboard.example.com/reports"
clits wait --timeout 5000

# Extract table headers
clits extract --text "table thead th" --json

# Extract all table rows
clits extract --text "table tbody tr" --json

# Extract specific columns
clits extract --text "table tbody td:nth-child(2)" --json

# Export to file
clits extract --text "table tbody tr" --json > data-export.json
```

### **Dynamic Content Extraction**
```bash
# Wait for dynamic content to load
clits wait --element "[data-testid='dynamic-content']" --timeout 10000

# Extract loaded data
clits extract --text "[data-testid='content-item']" --json

# Extract attributes
clits extract --attributes "[data-testid='content-item']" --attr "data-id" --json

# Extract nested content
clits extract --text "[data-testid='content-item'] .title, [data-testid='content-item'] .description" --json
```

### **API Response Monitoring**
```bash
# Start network monitoring
clits extract --network --filter-requests "api/v1/data"

# Trigger action that calls API
clits interact --click "[data-testid='refresh-data']"

# Wait for API response
clits wait --timeout 5000

# Extract network logs
clits extract --network --json > api-responses.json
```

## 🗂 **Tab Management Examples**

### **Multi-Tab Workflow**
```bash
# List current tabs
clits inspect --tabs --json

# Open new tab with URL
clits navigate --url "https://site1.example.com" --new-tab
clits wait --timeout 3000

# Switch between tabs
clits tab --switch-tab 0  # First tab
clits vision --screenshot
clits tab --switch-tab 1  # Second tab
clits vision --screenshot

# Navigate tabs sequentially
clits tab --tab-next
clits tab --tab-prev
```

### **Cross-Tab Data Comparison**
```bash
# Tab 1: Extract data
clits tab --switch-tab 0
clits extract --text "[data-testid='price']" > tab1-data.txt

# Tab 2: Extract data  
clits tab --switch-tab 1
clits extract --text "[data-testid='price']" > tab2-data.txt

# Compare screenshots
clits tab --switch-tab 0
clits vision --screenshot --filename "tab1-screenshot.png"
clits tab --switch-tab 1
clits vision --screenshot --filename "tab2-screenshot.png"
```

## ⌨️ **Keyboard Shortcuts Examples**

### **Developer Tools & Debug**
```bash
# Open developer tools
clits key --key "F12"
clits wait --timeout 2000

# Open console specifically
clits key --key "ctrl+shift+j"  # Windows/Linux
clits key --key "cmd+option+j"  # macOS

# Refresh page
clits key --key "F5"

# Hard refresh
clits key --key "ctrl+F5"       # Windows/Linux  
clits key --key "cmd+shift+r"   # macOS
```

### **Page Navigation**
```bash
# Back/forward navigation
clits key --key "alt+left"      # Back
clits key --key "alt+right"     # Forward

# Page up/down
clits key --key "PageUp"
clits key --key "PageDown"

# Home/end of page  
clits key --key "ctrl+Home"     # Top of page
clits key --key "ctrl+End"      # Bottom of page
```

### **Window Management**
```bash
# New tab/window
clits key --key "ctrl+t"        # New tab
clits key --key "ctrl+n"        # New window

# Close tab/window
clits key --key "ctrl+w"        # Close tab
clits key --key "ctrl+shift+w"  # Close window

# Switch tabs
clits key --key "ctrl+Tab"      # Next tab
clits key --key "ctrl+shift+Tab" # Previous tab
```

## 🔍 **Debugging & Troubleshooting Examples**

### **Element Discovery**
```bash
# Find all clickable elements
clits inspect --find-clickable --json

# Find elements by text content
clits inspect --find-by-text "Submit" --json

# Find form elements
clits inspect --find-forms --json

# Take diagnostic screenshot
clits vision --screenshot --filename "debug-state.png"
```

### **Error Investigation**
```bash
# Check console for errors
clits extract --console --log-levels error --json

# Monitor network errors
clits extract --network --filter-errors --json

# Check page performance
clits extract --performance --json

# Full diagnostic capture
clits extract --console --log-levels error,warning --json > console-errors.json
clits extract --network --filter-errors --json > network-errors.json
clits vision --screenshot --filename "error-state.png"
```

### **Wait Strategy Examples**
```bash
# Wait for specific element
clits wait --element "[data-testid='submit-button']" --timeout 10000

# Wait for element to disappear (loading indicator)
clits wait --element-gone "[data-testid='loading-spinner']" --timeout 15000

# Wait for network to be idle
clits wait --network-idle --timeout 8000

# Wait for page to be fully loaded
clits wait --page-load --timeout 10000

# Combined wait strategy
clits wait --timeout 3000
clits wait --element "[data-testid='content']" --timeout 10000
clits wait --network-idle --timeout 5000
```

## 🎯 **Material-UI / React Examples**

### **Material-UI Components**
```bash
# Click Material-UI button by text (OnDeck preferred)
clits interact --by-text "Save Changes"

# Select from Material-UI dropdown
clits interact --click "[data-testid='select-field']"
clits wait --element ".MuiSelect-menu" --timeout 3000
clits interact --click-text "Option 1"

# Handle Material-UI autocomplete
clits interact --type "[data-testid='autocomplete']" --text "New York"
clits wait --element ".MuiAutocomplete-popper" --timeout 3000
clits interact --click-text "New York, NY"

# Toggle Material-UI checkbox
clits interact --click "[data-testid='checkbox'] input[type='checkbox']"
```

### **React State Monitoring**
```bash
# Monitor React component updates
clits extract --react-hooks --include-prop-changes --json

# Monitor Redux state changes
clits extract --redux-monitoring --include-state-changes --json

# Monitor component lifecycle
clits extract --include-component-lifecycle --json

# Trigger action and monitor state
clits interact --click "[data-testid='update-button']"
clits extract --react-hooks --json > react-state.json
```

## 🔄 **Automation Script Examples**

### **Complete Workflow JSON**
```json
{
  "name": "User Registration Flow",
  "steps": [
    {
      "action": "navigate",
      "url": "https://app.example.com/signup",
      "waitAfter": 3000
    },
    {
      "action": "screenshot",
      "filename": "signup-page.png"
    },
    {
      "action": "type",
      "selector": "[data-testid='email']",
      "text": "user@example.com",
      "waitAfter": 1000
    },
    {
      "action": "type", 
      "selector": "[data-testid='password']",
      "text": "SecurePass123!",
      "waitAfter": 1000
    },
    {
      "action": "click",
      "selector": "[data-testid='signup-button']",
      "waitAfter": 5000
    },
    {
      "action": "screenshot",
      "filename": "signup-result.png"
    },
    {
      "action": "extract",
      "type": "text",
      "selector": ".success-message"
    }
  ]
}
```

### **Run Automation Script**
```bash
# Execute automation file
clits automate --file registration-flow.json

# Execute with custom screenshots
clits automate --file workflow.json --screenshots-dir ./screenshots

# Execute with error handling
clits automate --file workflow.json --continue-on-error --json
```

## 📝 **Common Command Combinations**

### **Safe Interaction Pattern**
```bash
# Standard safe interaction sequence
clits vision --screenshot --filename "before-action.png"
clits wait --element "[data-testid='target']" --timeout 10000
clits interact --click "[data-testid='target']"
clits wait --timeout 3000
clits vision --screenshot --filename "after-action.png"
```

### **Data Verification Pattern**
```bash
# Extract and verify data pattern
clits extract --text "[data-testid='result']" > result.txt
clits vision --screenshot --filename "verification.png"
# [AI processes result.txt to verify expected outcome]
```

### **Error Recovery Pattern**
```bash
# If element not found, try alternatives
clits interact --click "[data-testid='primary-button']" || \
clits interact --click-text "Submit" || \
clits interact --click ".btn-primary"

# With visual verification
clits vision --screenshot --filename "error-state.png"
clits inspect --find-clickable --json > available-elements.json
```

---

**💡 Tip for AI Assistants:** Always combine actions with screenshots and wait commands for reliable automation. Use the semantic targeting strategies (data-testid, aria-label) before falling back to CSS selectors.