/frontend-testing-debugging

name: frontend-testing-debugging
description: "Use when testing, debugging, or making targeted improvements to rendered frontend apps through the Frontend Design Skills or web dev plugin: local dev servers, UI regressions, interaction bugs, console errors, responsive layout, and visual QA. Check whether the Browser plugin is available and use it first when it is; otherwise use regular Playwright with the recorded reason."

Frontend Testing Debugging

Invocation Contract

This skill should work from normal user prompts. Do not require the user to spell out Browser routing, screenshots, report shape, or fallback policy.

Use this skill when the user asks to use the Frontend Design Skills plugin, web dev plugin, frontend dev plugin, or frontend testing/debugging skill for a rendered frontend change, test, or bug investigation.

Examples that should trigger this full workflow:

• `please make an improvement to the web dashboard transaction search area and use the web dev plugin`
• `use the frontend dev plugin to polish this dashboard`
• `debug this UI with the Frontend Design Skills plugin`
• `test this localhost app and fix the broken interaction`

From a brief prompt, infer the target surface from the repo, currently open app/browser URL, nearby files, or running dev server. If the target URL is unclear, inspect the repo scripts and running local ports before asking the user.

For any code change to a rendered frontend surface, do the validation loop by default:

1. Identify the target flow. 2. Choose the Browser path below. 3. Make the smallest useful edit. 4. Validate the rendered behavior. 5. Reply with the QA final response report.

Choose The Browser Path

First classify Browser availability:

• **Available**: the Browser plugin and its `browser` skill are listed in the session. Read and follow that skill before any browser action.
• **Absent**: the Browser plugin or `browser` skill is not listed. Use regular Playwright and record `Browser plugin not available`.
• **Invocation failed**: Browser appears available, but the skill/runtime, Node REPL JavaScript setup, tab acquisition, or navigation fails. Treat this as a Browser-path blocker.

Do not use regular Playwright, external Chrome, or shell `open` first when Browser is available.

Only switch from a failed Browser invocation to regular Playwright if the user already allowed fallback or the task explicitly permits non-Browser validation. In that case, report the exact Browser failure and the fallback decision.

Target Flow

Before browser validation, define the target flow in one sentence:

`The flow under test is: [entry route] -> [user action or state] -> [expected rendered result].`

If the user asked for general smoke testing, use:

`The flow under test is: app loads -> first meaningful screen renders -> primary visible controls respond without runtime errors.`

Browser Plugin Loop

Run Browser commands through the Node REPL JavaScript tool described by the Browser skill. Do not invent a separate browser setup path. Keep using the same tab binding unless the Browser skill says otherwise.

Required sequence:

1. Load the Browser runtime exactly as the Browser skill instructs. 2. Name the session with `agent.browser.nameSession("...")`. 3. Acquire a tab with `agent.browser.tabs.selected()` or `agent.browser.tabs.new()`. 4. Navigate with `tab.goto(url)`. 5. Run the required checks below. 6. Interact with scoped `tab.playwright` locators or Browser skill interaction APIs. 7. After edits, call `await tab.reload()`, then repeat the checks and the failing interaction.

For each UI-changing action, collect the cheapest proof that the next state is correct: fresh DOM snapshot, visible text/state, URL change, focused control, toast, modal, screenshot, or console log.

Required Browser Checks

Run these checks before claiming the rendered app works:

1. **Page identity**: `await tab.url()` and `await tab.title()` match the intended page. 2. **Not blank**: `await tab.playwright.domSnapshot()` contains meaningful app content, not an empty shell. 3. **No framework overlay**: the snapshot or screenshot does not show a Next.js, Vite, Webpack, or framework error overlay. 4. **Console health**: `await tab.dev.logs({ levels: ["error", "warn"], limit: 50 })` has no relevant app errors, or each relevant error is explained. 5. **Screenshot evidence**: `await display(await tab.playwright.screenshot({ fullPage: false }))` supports visual claims. 6. **Interaction proof**: at least one target-flow interaction is exercised and followed by a state check.

For visual work, add desktop plus one mobile-sized viewport when practical. For reference-driven work, keep a short mismatch ledger: reference evidence, rendered evidence, fix or intentional deviation.

Playwright Loop

Use this branch when Browser is not available, or when the user has allowed fallback after a Browser invocation failure.

Use this order:

1. Find scripts in `package.json`. 2. Start the app with the repo's package manager and keep the requested host exact. 3. Prefer the repo's e2e script if present. 4. Otherwise run `pnpm exec playwright test` or the package-manager equivalent when Playwright is configured. 5. If there is no project Playwright workflow, verify Playwright with `pnpm exec playwright --version`, then capture a screenshot with `pnpm exec playwright screenshot <url> /tmp/frontend-check.png`. 6. For deeper debugging, create a small temporary Playwright script outside committed source that opens the URL, captures console errors, screenshots, and runs the target interaction. 7. After edits, rerun the same command or script.

Do not install new browser dependencies unless the task requires it and the user has allowed dependency changes.

Validation Checklist

• Keep the requested host exact.
• Verify controls update real UI state.
• Check the first viewport before scrolling, plus desktop and one mobile-sized viewport when practical.
• Look for clip