playground-website-debugging

name: playground-website-debugging description: Debug the WordPress Playground website by running the dev server from source and interacting with it via Playwright MCP. Use when investigating UI bugs, testing website features, checking for JavaScript errors, debugging hanging requests, or verifying WordPress behavior in the browser-based Playground.

Playground Dev Server Debugging with Playwright MCP

Debug the WordPress Playground website by running the dev server from source and interacting with it via Playwright MCP.

Requires: Node.js, Playwright MCP server

Quick Start

# Ensure the correct Node.js version is active as per .nvmrc
nvm use

# Kill any leftover dev server from a previous run
lsof -ti:5400 -ti:5263 -ti:6400 | xargs kill 2>/dev/null; sleep 1

# Start dev server in background
npm run dev > /tmp/playground-dev.log 2>&1 &

# Wait for server to respond (up to ~120s for first build)
until curl -s -o /dev/null http://127.0.0.1:5400/website-server/ 2>/dev/null; do
  sleep 2
done
echo "Ready!"

Then use Playwright MCP to interact:

browser_navigate → http://127.0.0.1:5400/website-server/
browser_snapshot → inspect the page structure
browser_take_screenshot → visual state

Architecture: The Iframe Boundary

The Playground website has a three-layer structure that's critical to understand:

┌───────────────────────────────────────────────────┐
│ Parent page (Playground chrome / React app)       │
│ ┌───────────────────────────────────────────────┐ │
│ │ URL bar │ Save │ Settings │ Site Mgr          │ │
│ ├───────────────────────────────────────────────┤ │
│ │                                               │ │
│ │  <iframe class="playground-viewport">         │ │
│ │    Loads remote.html                          │ │
│ │    (Service Worker, Web Worker, PHP runtime)  │ │
│ │   ┌─────────────────────────────────────────┐ │ │
│ │   │  <iframe id="wp">                       │ │ │
│ │   │    WordPress runs here                  │ │ │
│ │   │    (wp-admin, front-end, editor, etc.)  │ │ │
│ │   └─────────────────────────────────────────┘ │ │
│ │                                               │ │
│ └───────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────┘

Parent page contains: URL bar, Save button, Saved Playgrounds, Site Manager, Settings gear.

Outer iframe (playground-viewport) loads remote.html, which registers the Service Worker, spawns a Web Worker for the PHP runtime, and exposes the Playground API via Comlink.

Inner iframe (#wp, nested inside the outer iframe) contains the actual WordPress site — dashboard, posts, pages, plugins, themes, block editor, front-end.

Playwright's browser_snapshot traverses both iframes automatically, so you'll see all three layers in one snapshot. When clicking elements inside WordPress, Playwright handles the iframe targeting.

Important: WordPress admin CSS positions sidebar submenu items off-screen (e.g. top: -12387px) until their parent menu is hovered. These elements appear in browser_snapshot but browser_click will fail with "element is outside of the viewport." Two workarounds:

1. Hover parent first (preferred — mimics real user behavior):

async (page) => {
    const frame = page.frameLocator('iframe').first().frameLocator('iframe').first();
    await frame.locator('#menu-tools').hover();
    await frame.locator('a[href="site-health.php"]').click();
};

2. JS click (bypasses Playwright's visibility checks):

async (page) => {
    const frame = page.frameLocator('iframe').first().frameLocator('iframe').first();
    await frame.locator('a[href="site-health.php"]').evaluate((el) => el.click());
};

PHP-WASM Request Pipeline

Understanding how HTTP requests flow through Playground is critical for debugging performance and hanging issues:

Browser request (navigation, AJAX, etc.)
    ↓
Service Worker intercepts fetch event
    ↓
broadcastMessageExpectReply() → broadcasts to all window clients
    ↓
remote.html window receives message (filtered by scope) → proxies to Web Worker
    ↓
PHPProcessManager.acquirePHPInstance() → Semaphore (max 2 instances, 30s timeout)
    ↓
PHP-WASM executes the PHP script
    ↓
If PHP calls wp_remote_get(): Wp_Http_Fetch → post_message_to_js() → JS fetch()
    ↓
fetch() for loopback URLs → goes BACK through Service Worker → needs another PHP instance!

Timeout mismatch: The Service Worker times out waiting for a response after 25s (DEFAULT_RESPONSE_TIMEOUT), but the PHP semaphore waits up to 30s. If PHP is stuck, the Service Worker returns ERR_FAILED while the process manager is still waiting — useful to know when diagnosing hanging requests.

Dev Server Details

Note: npm run dev also starts a PHP CORS proxy (php -S 127.0.0.1:5263). If system PHP isn't installed, that subprocess fails — the website still loads but features relying on the CORS proxy (e.g., fetching external resources) won't work.

Workflow

1. Start the Dev Server

npm run dev
# Wait for "Local:   http://127.0.0.1:5400/website-server/" in output

2. Navigate and Inspect

browser_navigate → http://127.0.0.1:5400/website-server/
browser_snapshot → see full page tree including iframe content
browser_take_screenshot → capture visual state

3. Navigate Within WordPress

To visit WordPress pages (e.g., wp-admin), use the Playground URL bar:

browser_click → click the URL bar textbox (labeled "URL to visit in the WordPress site")
browser_type → type "/wp-admin/"
browser_press_key → press "Enter"
browser_snapshot → verify the page loaded

4. Debug Common Scenarios

Check for JavaScript errors:

browser_console_messages (level: "error") → see JS errors and warnings

Check for stuck/failed network requests:

browser_network_requests (includeStatic: false) → see all XHR/fetch requests and their status

Requests showing no status code are still pending. Requests with [FAILED] net::ERR_FAILED typically indicate a service worker timeout (25s) — a sign of PHP-WASM deadlock (see "PHP-WASM Request Pipeline" above).

Time a navigation:

// Use browser_run_code to measure how long a navigation takes
async (page) => {
    const frame = page.frameLocator('iframe').first().frameLocator('iframe').first();
    const start = Date.now();
    await frame.locator('a[href="site-health.php"]').evaluate((el) => el.click());
    await frame.getByRole('heading', { name: 'Site Health', level: 1 }).waitFor({ timeout: 60000 });
    return `Navigation took ${Date.now() - start}ms`;
};

Inspect the block editor:

browser_click → URL bar
browser_type → /wp-admin/post-new.php
browser_press_key → Enter
browser_snapshot → see block editor structure inside iframe

Test plugin/theme UI:

browser_click → URL bar
browser_type → /wp-admin/plugins.php
browser_press_key → Enter
browser_snapshot → verify plugin list

Screenshot a specific state:

browser_take_screenshot → capture current visual state for comparison

5. Stop the Server

Kill the npm run dev process (Ctrl+C in the terminal, or lsof -ti:5400 | xargs kill).