woocommerce-browser-interaction

name: woocommerce-browser-interaction description: Use when needing to interact with WooCommerce in a browser - debugging UI issues, verifying changes, testing flows, taking screenshots, or exploring admin and frontend pages (shop, cart, checkout, my account). Requires a browser automation MCP server (chrome-devtools or playwright).

WooCommerce Browser Interaction

Browser automation for WooCommerce debugging, verification, and testing.

REQUIRED: First read and follow the pirategoat-tools:browser-interaction skill for MCP detection, tool mapping, RULE 0, error handling, and browser closing. This skill adds WooCommerce-specific patterns.

Complete the browser task requested. Do not add extra checks or improvements beyond what is explicitly asked.

Required Setup Before Browser Use

Get site URL first. Use AskUserQuestion:

Question: "What is the WordPress site URL?"
Header: "Site URL"
Options:
  - "http://localhost:8888" (wp-env default)
  - "http://localhost:8080" (alternate local)
  - "http://localhost:8082" (custom port)

Also gather admin credentials (username/password) if authentication is needed.

Verify site is running: curl -s -o /dev/null -w "%{http_code}" {base_url} → expect 200/301/302.

Login and Navigate Workflow

1. Navigate → {base_url}/wp-admin/
2. If wp-login.php → fill #user_login, #user_pass → click #wp-submit
3. Navigate directly to target URL via address bar
4. Take snapshot → Interact → Verify

Use direct URL navigation. Menu clicking is slow and unreliable. URLs are in the Navigation Reference below.

Authentication Errors

Login selector fallbacks:

Primary:    #user_login, #user_pass, #wp-submit
Fallback:   input[name="log"], input[name="pwd"], input[type="submit"]

Session persistence: After successful login, verify by checking for #wpadminbar or .wp-admin body class.

URL Reference for Direct Navigation

Navigate via URL. Use snapshot to discover current selectors.

WC Admin (React SPA)

Wait for .woocommerce-layout after navigation.

WC Settings (Classic + Hybrid)

Wait for #mainform after navigation.

WooPayments Onboarding: ?page=wc-settings&tab=checkout&path=%2Fwoopayments%2Fonboarding

WC Status

Dynamic URLs

Frontend Pages

Permalink Fallback: Try pretty URL first. If 404, switch to query string URLs for the session.

Get page IDs from ?page=wc-status → "WooCommerce pages" section.

Identify Page Type Before Interacting

Detect page type from URL or body class:

• WC Admin (React): URL contains page=wc-admin → wait for .woocommerce-layout
• WC Settings: URL contains page=wc-settings → wait for #mainform
• WC Status: URL contains page=wc-status → wait for .nav-tab-wrapper
• Frontend: Body has .woocommerce-cart, .woocommerce-checkout, etc.

Block vs Classic Cart/Checkout:

// Block-based (modern default)
!!document.querySelector('.wp-block-woocommerce-cart')
!!document.querySelector('.wp-block-woocommerce-checkout')

// Classic shortcode
!!document.querySelector('.woocommerce-cart-form')
!!document.querySelector('form.checkout')

WooCommerce-Specific Errors

Navigation Errors

React SPA Errors (WC Admin)

Wait strategy for React:

1. Wait for .woocommerce-layout to appear
2. Wait for .woocommerce-spinner to disappear
3. Then interact with content

Debug, Fix, and Verify Workflow

Debug → Fix → Verify Loop

1. IDENTIFY: Find error via console/network/DOM
2. LOCATE: Map error to source file (stack trace, grep for message)
3. FIX: Edit the source file
4. REBUILD: (localhost only) See build workflow below
5. REFRESH: Navigate to same URL
6. VERIFY: Confirm error gone, no regressions

Build Workflow (Localhost Only)

Skip this section if URL is not localhost (e.g., localhost:*, 127.0.0.1:*).

1. DETECT REPO: Check if current working directory is a WooCommerce-related repo
   - Run: git rev-parse --show-toplevel
   - Read README.md at repo root and check if it mentions WooCommerce
   - Applies to: core repo, WooPayments, extensions, themes, any WooCommerce-related project
2. CONFIRM: If CWD is not WooCommerce-related, use AskUserQuestion:
   - Question: "What is the path to your local WooCommerce-related repository?"
   - Header: "Repo Path"
   - Do NOT guess or search filesystem
3. READ AI DOCS: Look for build instructions in repo's AI documentation:
   - CLAUDE.md (root or .claude/ directory)
   - AGENTS.md, CONTRIBUTING.md
   - package.json scripts section
4. BUILD: Run the documented build command
5. WAIT: Ensure build completes before refreshing browser

If no build docs found: Ask user for build command via AskUserQuestion.

WooCommerce-Specific Autonomous Recovery

In addition to general error recovery from browser-interaction skill:

Common Selectors by Page Type

Use snapshot to find current selectors. Common patterns:

WC Admin (React):

• App root: .woocommerce-layout
• Tables: .woocommerce-table
• Loading: .woocommerce-spinner
• Notices: .components-notice

WC Settings (Classic):

• Form: #mainform
• Tabs: .nav-tab-wrapper, .nav-tab-active
• Save: .woocommerce-save-button

WooPayments Onboarding Modal:

• Overlay: .components-modal__screen-overlay
• Frame: .settings-payments-onboarding-modal

Frontend Cart (Block):

• Container: .wp-block-woocommerce-cart
• Empty state: .wp-block-woocommerce-empty-cart-block
• Checkout button: .wc-block-cart__submit-button

Frontend Checkout (Block):

• Container: .wp-block-woocommerce-checkout
• Place order: .wc-block-components-checkout-place-order-button

My Account:

• Navigation: .woocommerce-MyAccount-navigation
• Content: .woocommerce-MyAccount-content

For complete selector reference, see SELECTORS.md in this skill directory.