Vscode Browser Test

VS Code Native Browser Test

Why this skill exists

Do NOT install Playwright, Puppeteer, headless Chrome, or any browser-automation npm package in this project. VS Code already ships an integrated browser plus a full set of browser-agent tools that work on Windows, macOS, and Linux with zero install. This skill teaches the agent to use them.

If a user asks for "Playwright tests" or "headless browser tests", interpret the intent (verify a web page) and use the native tools below — do not run npm install -D playwright.

---

When to load this skill

• User says: "test this page", "open it in the browser", "screenshot the dashboard", "click the X button", "fill the form", "verify the layout", "check responsive"
• User points at: file://.../*.html, http://127.0.0.1:3000, http://localhost:3000, any dev server URL
• User wants an accessibility audit, form validation test, responsive layout check, or auth flow test against any web page
• Target surface: any HTML mockup, any local dev server (Next.js, Vite, Astro, plain Express, etc.), or any reachable URL

---

Prerequisites (one-time, per workspace)

Browser agent tools are opt-in. Confirm these before assuming the tools work:

1. VS Code setting workbench.browser.enableChatTools must be true.

• If false, tell the user to set it in settings.json and reload.
• This setting is org-managed in some environments — surface that if it's locked.

1. Chat tools picker must show all browser tools enabled, grouped under Built-in > Browser.

• Chat view → Tools button (chat input area) → Built-in > Browser → all 10 toggled on.

1. Note: Browser agent tools are experimental and may change. Don't hard-code behavior on edge cases.

If prerequisites are not met, do not try to npm install playwright as a fallback. Ask the user to enable the setting or use the tools picker.

Auto-enabling browser tools with @browser

If the tools are present in the runtime but disabled in the chat session, the user can explicitly enable them for a single prompt by adding the @browser reference at the start of their message:

@browser open http://127.0.0.1:3000 and screenshot the dashboard

This injects the browser tools into the current turn without requiring the user to open the tools picker every time. Useful for:

• One-off tests when the user only occasionally runs browser checks.
• Sharing the skill in chat sessions where tools are normally off.
• Avoiding the friction of toggling 10 switches in the tools picker.

> Note: @browser is a per-turn reference. It does not change the user's persistent tools-picker settings. Each new prompt needs @browser again unless the user keeps the tools enabled.

---

The 10 native browser tools

> The agent does not need to "declare" these tools exist — they are already wired into the chat runtime. The skill's job is to teach when and in what order to use them.

| # | Tool | Purpose | When to reach for it | |---|------|---------|----------------------| | 1 | openBrowserPage | Open a URL or local file in the integrated browser | First step for every test session. Pass absolute file:// URL for HTML mockups, http://127.0.0.1: for dev servers. | | 2 | readPage | Get a structured snapshot (DOM, ARIA, headings, links) | Before any interaction — understand the page before clicking anything. | | 3 | screenshotPage | Capture viewport or a specific element (via selector/ref) as PNG | Before AND after each interaction, to prove visual state changed. Pass ref/selector to screenshot just one component. | | 4 | clickElement | Click a button/link/element by ref or selector | User actions: submit, navigate, toggle, open menu. | | 5 | typeInPage | Type into a focused input, or focus+type via ref/selector | Form fields, search boxes, text areas. Supports key parameter for Enter/Tab/etc. | | 6 | hoverElement | Hover over an element | Reveal tooltips, dropdown menus, hover-only states. | | 7 | dragElement | Drag from one element to another | Sortable lists, file drops, sliders, drag-and-drop reordering. | | 8 | handleDialog | Accept/dismiss alert/confirm/prompt | Any modal dialog. For file choosers, pass selectFiles with absolute paths. | | 9 | navigatePage | Go to URL, go back/forward, or reload | SPA route changes (navigatePage type=url), in-app navigation, refresh after code change. | | 10 | runPlaywrightCode | Run arbitrary Playwright code in the page context | Last resort for: complex multi-step assertions, file upload via setInputFiles, evaluating JS, network interception, waiting for custom conditions. Do not use for simple clicks/typing. |

Tool selection priority (cheapest → most powerful)

openBrowserPage → readPage → screenshotPage → clickElement/typeInPage/hoverElement/dragElement → handleDialog → navigatePage → runPlaywrightCode

Reach for runPlaywrightCode only when no higher-level tool can do the job. The native tools give the user a better visual confirmation and are easier to step through.

---

Standard workflow (the build → test → debug loop)

Use this loop whenever the user asks to verify a web page works:

Step 1 — Open the page

• HTML mockup: openBrowserPage url=file:///absolute/path/to/your/mockup.html (must be an absolute file:// URL)
• Dev server: openBrowserPage url=http://127.0.0.1: (verify the port from package.json, terminal output, or framework config)
• External: pass the full https://... URL

Step 2 — Read before acting

• Call readPage to enumerate buttons, inputs, links, headings.
• Identify the element ref or stable selector you'll need for clickElement / typeInPage.

Step 3 — Screenshot the baseline

• screenshotPage to capture the initial visual state.
• Save the mental model: "this is what the page looks like before my action."

Step 4 — Interact

• Use the appropriate tool from the table above.
• One screenshot per action, in this order:

1. Screenshot before
2. Perform the action
3. readPage or screenshotPage after to confirm the change

Step 5 — Verify and report

• State what passed and what failed with concrete evidence (screenshot ref, error message, observed text).
• If a bug is found:

1. Identify the smallest code change that fixes it.
2. Apply the fix in the repo.
3. navigatePage type=reload (or reopen the page) and re-run the failing step.
4. Re-screenshot to prove the fix.

Step 6 — Close out

• Summarize: actions taken, screenshots captured, bugs found, fixes applied, what still needs human review.

---

Session isolation rules (important!)

• Pages opened by the agent run in a private, in-memory, ephemeral session. They do not share cookies, localStorage, or login state with the user's regular browser tabs.
• This is by design — protects the user's browsing data.
• If the test needs the user's logged-in state (e.g., a session cookie), the user must:

1. Open the page themselves in the integrated browser (Command Palette → Browser: Open Integrated Browser).
2. Navigate to the page and log in.
3. Click Share with Agent in the browser toolbar.
4. Tell the agent which shared page to use.

• Shared pages use the user's real session (cookies, login). Agent-opened pages do not. Don't conflate the two.

---

Common scenarios

Use these recipes for the most common browser-verification asks. Adapt the URLs and selectors to the target under test.

1. Screenshot an HTML mockup for review

User: "screenshot the dashboard mockup"
→ openBrowserPage url=file:///absolute/path/to/docs/mockup/dashboard.html
→ screenshotPage
→ report the file path or describe the visual

2. Verify a form (login, signup, contact, etc.)

User: "test the login form"
→ openBrowserPage url=http://127.0.0.1:3000/login   (after the dev server is running)
→ readPage     → identify inputs
→ typeInPage   → fill username
→ typeInPage   → fill password
→ screenshotPage → before submit
→ clickElement  → submit button
→ handleDialog  → if a confirm/alert pops up
→ screenshotPage → after submit
→ verify redirect (or expected success state) on the next page

3. Test a stateful form with validation

• When the form has conditional rules (e.g. "comment required when rating

readPage → verify page loaded navigatePage type=reload → re-test after a code change

If the port is unknown, read the terminal output to find the actual bound port before calling `openBrowserPage`.

---

## When NOT to use this skill

These tools are designed for **interactive, in-editor verification**. Do not use them for:

- **Large E2E test suites:** Not a replacement for Playwright/Cypress in CI. Use for ad-hoc and development-loop testing only.
- **Cross-browser testing:** The integrated browser is Chromium-based. For Firefox/Safari/Edge compatibility, use dedicated tools.
- **Headless CI/CD pipelines:** These tools require the VS Code UI and an agent session. They will **not** work in a headless CI environment (e.g., GitHub Actions without a display).
- **Visual regression testing at scale:** `screenshotPage` is great for manual checks, but lacks automated diffing of specialized visual-regression tools.
- **Performance testing:** No network timing, no performance metrics, no load generation.
- **Parallel test execution:** One agent session, one browser. No multi-page parallel runs.

---

## Troubleshooting

If the agent gets stuck or tools fail, check these common issues:

1. **Tool not found / not executing:**
   - Verify `workbench.browser.enableChatTools` is `true` in VS Code settings.
   - Open the Chat tools picker and ensure the specific tool (e.g., `clickElement`) is toggled on under **Built-in > Browser**.
2. **`ref` not found or stale:**
   - The page may have reloaded or changed dynamically. Call `readPage` again to get a fresh snapshot and new `ref` values.
3. **Action executed but nothing happened:**
   - The element might be covered by an overlay or not interactive. Try `hoverElement` first, or check if a dialog needs handling via `handleDialog`.
4. **Page content is empty or still loading:**
   - Use `runPlaywrightCode` with `await page.waitForLoadState('networkidle')` or `await page.waitForTimeout(2000)` before reading or screenshotting.
5. **"Share with Agent" not working:**
   - The user must open the page in the **VS Code integrated browser** (Command Palette → **Browser: Open Integrated Browser**), not their external browser, before clicking **Share with Agent**.
6. **Dev server returned blank page:**
   - Confirm `npm run dev` is actually running in the background. Read the terminal output to see the real port and any compile errors.
7. **CORS / network error in console:**
   - Expected for `file://` pages that fetch external resources. Not a tool failure. Check the page's own network handling.

---

## Anti-patterns — do NOT do these

| Don't | Why |
|-------|-----|
| `npm install playwright` / `npm install -D @playwright/test` | The native tools do everything Playwright can for an in-editor test loop, with zero install. Save the project the dependency. |
| `npx playwright install` | Downloads ~300MB of browser binaries. Native tools already have a browser. |
| Write a `*.spec.ts` Playwright file for ad-hoc verification | Use the native tools for one-off checks. Reserve Playwright for full E2E suites that need to run in CI. |
| Spawn a child process running Puppeteer | Same reason as Playwright. |
| Use `curl` to "test" a web page | `curl` returns HTML source, not a rendered page. Use the browser tools to see what the user sees. |
| Skip `readPage` and guess selectors | Always read the page first. Refs/selectors change between versions. |
| Skip the before/after screenshot | Without a baseline, you can't prove the action changed anything. |
| Try to share cookies between agent-opened and user-opened pages | Impossible by design. Use the **Share with Agent** flow for shared session state. |

---

## Quick reference: when the user says X, do Y

| User says | Action |
|-----------|--------|
| `"@browser ..."` at start of prompt | Browser tools are force-enabled for this turn. Proceed with `openBrowserPage` / `screenshotPage` / etc. directly. |
| "test this page" / "verify it works" | Open + read + screenshot + interact + verify |
| "screenshot X" | `openBrowserPage` → `screenshotPage` |
| "click the Save button" | `readPage` → find Save ref → `clickElement` → `screenshotPage` to confirm |
| "fill in the form" | `readPage` → list inputs → `typeInPage` each → `screenshotPage` |
| "does it work on mobile?" | Native tools + `runPlaywrightCode` to resize viewport, or instruct user to use DevTools device emulation |
| "check accessibility" | `readPage` + visual screenshot + (optional) `audit` skill for deeper checks |
| "playwright test" | **Do not install Playwright.** Use the 10 native tools above. If they hit a wall, escalate to the user. |
| "test the form submission" | Fill → submit → `handleDialog` if needed → verify redirect/state change |
| "open the mockup" | `openBrowserPage` with `file://` absolute path |

---

## Minimal end-to-end example

User: "open the dashboard mockup and verify the sidebar shows the expected menu items."

1. `openBrowserPage url=file:///absolute/path/to/docs/mockup/dashboard.html`
2. `screenshotPage` — baseline.
3. `readPage` — look for the sidebar nav, list its items.
4. If all expected items present (use `readPage` to enumerate the actual labels) → pass, report what was found.
5. If fewer or extra items → fail, report the exact text observed.
6. Summary in 2-3 lines: ✅ passed / ❌ failed, with the observed data.

---

## Related

- [VS Code browser agent testing guide](https://code.visualstudio.com/docs/copilot/guides/browser-agent-testing-guide) — upstream docs
- [Integrated browser in VS Code](https://code.visualstudio.com/docs/debugtest/integrated-browser)
- [Claude skills documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview) — how this skill is loaded by Claude Code
- [Agent Skills specification](https://agentskills.io) — community spec for portable skill format

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Piyabordee](https://github.com/Piyabordee)
- **Source:** [Piyabordee/vscode-browser-test](https://github.com/Piyabordee/vscode-browser-test)
- **License:** MIT

Install and usage instructions live in the source repository linked above.