Browser Automation

Browser Automation — Interactive Bridge + Visual Validation Skill

You perform interactive browser automation using Playwright MCP tools. This skill focuses on creating a live bridge between the agent and a running browser session so you can test authenticated flows with the current signed-in user, inspect UI behavior in context, and capture evidence. When needed, you then convert validated interactive flows into repeatable Playwright test scripts.

Prerequisites

1. A Playwright MCP server configured for your host tool:

• Claude Code: add it as an MCP server (claude mcp add or in .mcp.json/settings.json).

Its tools appear with an mcp____ prefix, e.g. mcp__playwright__browser_navigate.

• Codex: add it under [mcp_servers] in config.toml (or codex mcp add). Its tools

are namespaced as :, e.g. playwright:browser_navigate.

• Whatever the exact prefix turns out to be in your session, the underlying actions are the

same: navigate, click, type, snapshot, screenshot. Substitute your host's actual tool names everywhere this skill says browser_.

• MCP tools will be available for live browser interaction once the server is connected.

1. Interactive browser session available:

• The Playwright MCP browser starts as a fresh session with no cookies or stored credentials
• For protected apps (Dynamics 365, Power Apps, Azure Portal, etc.), you must run Phase 0 (Authentication) first
• Navigate to the base domain to trigger the login redirect, let the user complete sign-in, then proceed
• Once authenticated, the session persists for the browser lifetime — reuse it for all subsequent navigation

1. Playwright installed (optional, for repeatable scripts):

``bash npm init playwright@latest ``

1. Playwright configured for visual testing in playwright.config.ts (optional):

``typescript use: { video: 'retain-on-failure', // Record videos of failed tests screenshot: 'on', // Screenshot on every action trace: 'retain-on-failure', // Detailed traces for debugging } ``

Quick Start

Ask your assistant:

"Use browser-automation on [your app URL] to walk through [specific flow]
in the live authenticated browser session, capture before/after screenshots,
log structured captions, and then generate a Playwright test from the validated steps."

Example:

"Use browser-automation for https://contoso.crm.dynamics.com and:
1. Creates a new Account record
2. Fills in required fields
3. Saves and verifies success
4. Captures screenshots and captions for review
5. Produces a repeatable Playwright spec from the interactive run"

Copilot will drive the live browser flow first, then produce automation artifacts for repeatable testing.

CRITICAL RULES

1. Authenticate first (Phase 0). For protected apps, navigate to the base domain first, let the user sign in, then navigate to the full target URL. Never type passwords or interact with MFA prompts.
2. Take a screenshot BEFORE and AFTER every action. This creates the visual evidence chain.
3. Visually inspect screenshots for layout correctness — don't just check functional outcomes.

After taking a screenshot, actually LOOK at it. Check for:

• Alignment issues — elements not lining up, inconsistent spacing, off-center content
• Overflow/clipping — text or components cut off, hidden behind other elements, horizontal scrollbars appearing unexpectedly
• Empty gaps — large blank areas where content should be, collapsed containers
• Overlapping elements — headers over content, modals not properly layered, sticky elements covering interactive areas
• Responsive breakage — columns not wrapping, cards squishing to unreadable widths, nav menus overflowing
• Visual hierarchy — headings that look like body text, actions that don't look clickable, missing borders/separators
• Data presentation — columns too narrow for their content, truncated text without tooltips, numbers/dates misaligned

Do NOT treat screenshots as mere evidence artifacts to collect. They are your primary tool for catching visual bugs that functional tests miss. If something looks wrong in a screenshot, it IS wrong — investigate and report it.

Accessibility snapshots (DOM snapshots) are NOT a substitute for screenshots. DOM snapshots show correct data and structure but completely miss layout issues:

• Grid misalignment from null CSS Grid cells — DOM shows correct data but columns are shifted
• Missing sort indicators — DOM shows columnheader but no button inside (no sort arrows)
• Slots/cards not rendering in the right position — DOM shows all data loaded, grid appears empty
• Overlapping elements, broken flex layouts, invisible overflow

Always take a screenshot after any visual change and actually inspect it before claiming something works. A DOM snapshot saying "12 records loaded" means nothing if the screenshot shows an empty grid.

1. Log every action with the structured caption format. Every click, type, scroll, and

wait must have an ACTION, INTENT, and EXPECT block. Read resources/caption-format.md.

1. Never skip the edge case checklist. After the happy path, run through edge cases.

Read resources/edge-cases.md.

1. Protect authenticated context. Avoid unnecessary sign-out/navigation that invalidates user login state.
2. Review the FULL evidence — video/screenshots + captions, not just one artifact.
3. Persist workflow state to disk. Use the shared workflow-state skill (../workflow-state/SKILL.md) and keep state synchronized with your todo list.
4. MSAL.js popup flows are incompatible with Playwright MCP. MSAL.js uses popup windows for authentication, but the Playwright MCP browser cannot interact with popups (it only sees the main page). If the app under test uses MSAL.js popup auth, you must either: (a) switch to MSAL redirect flow before testing, or (b) use a non-MSAL auth approach (e.g., Power Pages v1 implicit grant). Never attempt to automate MSAL popup login — it will hang indefinitely.
5. Clean up session state between test runs. If a prior test or auth flow left stale state (e.g., MSAL's interaction_in_progress flag in sessionStorage, leftover cookies, or cached tokens), clear it before starting a new flow. Use browser_evaluate to run sessionStorage.clear() or target specific keys. Stale interaction_in_progress flags are a common cause of "interaction already in progress" errors that block subsequent auth attempts.

1. Viewport testing is mandatory. Every browser testing session MUST include at least one test at a reduced viewport:

`` browser_resize: { width: 800, height: 600 } ``

Test for:

• Content not collapsing (flexShrink issues)
• Horizontal scroll where needed (DataGrid columns)
• Pagination footer visible
• Headers/toolbars not overlapping content

Then reset to standard viewport:

`` browser_resize: { width: 1280, height: 768 } ``

1. Keyboard navigation verification. For pages with scrollable content, verify keyboard navigation works:

1. Click inside the scrollable container
2. Press Tab to focus the scroll container
3. Press arrow keys / Page Down to scroll
4. Verify content scrolls as expected

If the scroll container is not keyboard-focusable, add tabIndex={0} to it.

1. Power Platform admin UI verification. After setting up permissions, web roles, or site settings via API, verify the result in the admin UI using browser automation:

1. Navigate to Power Pages admin center
2. Check table permissions have correct web role associations
3. Check site settings values match expectations
4. Navigate to the actual site and test an API call

This catches "silent failures" where the API returns 200 but the configuration is actually broken (e.g., associations cleared by deployment).

1. Final validation must include a full screenshot layout review. At the end of

every browser testing session (whether milestone or final), take a full-page screenshot of every key screen and visually inspect each one for layout correctness. This is NOT optional — it is the final gate before declaring the test pass clean.

For each screenshot, check and report:

• Page fills the viewport correctly (no excessive whitespace, no unexpected scroll)
• Grid/list headers are aligned with their columns
• Pagination is visible without scrolling (sibling of scroll container, not inside it)
• Forms have consistent field widths and label alignment
• Command bars / action buttons are positioned correctly (above content, not floating)
• Navigation (left nav or top nav) renders at the correct width/height
• No content is hidden behind overlapping elements
• At 800×600: layout adapts without horizontal overflow or content loss

If ANY screenshot shows a layout issue, report it as a finding — do not silently pass it.

1. Always test locally before testing deployed. Browser automation follows a

local-first approach. Test against the local dev server first, iterate until stable, deploy, then re-test against the deployed URL as a smoke test.

Local testing catches most issues — layout, logic, data flow, navigation. Deployed smoke testing catches environment-specific issues — auth redirects, CORS, asset paths, permission configuration.

Do NOT skip local testing and go straight to deployed testing. If a bug is found in the deployed environment, fix it locally, test locally, then redeploy.

Workflow

Before Phase 1, load ../workflow-state/SKILL.md, initialize workflow state, and update it at each phase transition and todo update.

Phase 0 — Authentication

Protected apps (Dynamics 365, Power Apps, Power Pages with auth, Azure Portal, etc.) require the user to sign in before the agent can interact with the application. The Playwright MCP browser is a fresh session with no stored cookies, so authentication must be handled as the very first step.

Authentication Flow

┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│ 1. Navigate to   │───▶│ 2. Detect login  │───▶│ 3. User completes│───▶│ 4. Navigate to   │
│    base domain   │    │    page & pick   │    │    password/MFA  │    │    target URL    │
│                  │    │    account        │    │                  │    │                  │
└──────────────────┘    └──────────────────┘    └──────────────────┘    └──────────────────┘
  e.g. org.crm.         Snapshot shows           Agent WAITS for        Once authenticated,
  dynamics.com          "Pick an account"        user confirmation      navigate to full URL

Step-by-Step

1. Navigate to the base domain (not the full app URL):

`` browser_navigate → https://org.crm.dynamics.com ``

Use only the base domain URL. The server will redirect to the identity provider login page (e.g., login.microsoftonline.com). Do NOT navigate to the full app URL yet — the login redirect can lose query parameters or fail with long URLs.

1. Take a snapshot to detect the login page state. The snapshot will show one of:

• "Pick an account" — Multiple accounts are available. Identify the correct account

from the list and click it using browser_click. Look for the account that matches the target org's tenant (e.g., user@contoso.onmicrosoft.com).

• "Enter password" — A single account was auto-selected. The user needs to enter their

password manually.

• "Sign in" — No cached accounts. The user needs to enter email + password.
• Already authenticated — The app loaded directly (session/cookies were still valid).

Skip to step 5.

1. If "Pick an account" is shown, click the correct account button:

`` browser_click → ref for the matching account button ``

After clicking, the page will transition to "Enter password" or directly authenticate (if SSO/Windows integrated auth is configured).

1. Ask the user to complete authentication. Tell the user:

> "The browser is showing the login page. Please enter your password (and complete MFA > if prompted) in the browser window. Let me know once you're logged in."

Then STOP and WAIT for the user to confirm they have logged in. Do NOT attempt to type passwords or interact with MFA prompts. Never ask the user for their password.

After the user confirms, take a snapshot to verify:

• The page URL has changed away from login.microsoftonline.com
• The page title or content shows the authenticated app or app picker

1. Navigate to the full target URL:

`` browser_navigate → https://org.crm.dynamics.com/main.aspx?appid={guid}&pagetype=entitylist&etn=... ``

The authenticated session cookies are now set, so the full URL will load directly into the app without another login redirect.

1. Wait for the app to fully load. Dynamics 365 apps show a "Loading..." alert initially.

Use browser_wait_for or take repeated snapshots until the main content (grid, form, dashboard) is visible. Then take an initial screenshot for evidence.

Authentication Tips

• Protect the session. Once authenticated, avoid navigating to external domains or

clearing cookies. The session persists for the lifetime of the browser instance.

• If authentication fails (redirect loop, error page), take a screenshot, report the

error to the user, and ask them to check their credentials or network.

• Multi-tenant scenarios. If the user has accounts in multiple tenants, the "Pick an

account" page will list all of them. Match the account to the target org's domain.

• SSO (Windows Integrated Auth). In some enterprise environments, clicking the account

may complete authentication automatically without a password prompt. Always take a snapshot after clicking to detect whether the user needs to act.

• Session expiry. Long-running test sessions may hit token expiry (typically 1 hour for

Dynamics 365). If you encounter a surprise login redirect mid-test, repeat Phase 0.

Phase 1 — Plan the Test Run

Before generating code, define the test plan with the user:

Questions to ask:

1. What app? Get the URL (e.g., https://org.crm.dynamics.com/main.aspx?appid={guid})
2. What flows? List user journeys (e.g., "Create account → Add contact → Link opportunity")
3. What to check? Define expected visual states for each step
4. What deployment/config checks? Identify smoke checks (auth, routing, env-specific endpoints, static assets, key pages)
5. What edge cases? Which items from the checklist apply to this app?

Output: A test plan document with:

• Test scenarios (happy path + edge cases)
• Deployment/config smoke scenarios
• Expected behavior for each step (ACTION, INTENT, EXPECT_VISUAL)
• Screenshots to capture
• Assertions to make

Example Ask:

"Create a browser automation test plan for the Dynamics 365 Accounts app that tests:
- Creating a new account with required fields
- Saving and verifying the record appears in the view
- Editing the account name and phone
- Testing validation on empty required fields
Include edge cases for long text, special characters, and narrow browser width."

Phase 2 — Generate Playwright Test with Captions

Use your assistant with the Playwright MCP server to generate the test script:

Ask Copilot:

"Create a Playwright browser automation test for [app URL] that:
1. Tests the [specific user flow]
2. Takes screenshots before/after each action
3. Generates structured captions with ACTION, INTENT, EXPECT_VISUAL
4. Saves captions to JSON for evidence review"

Example Test Pattern (skeleton):

`

…

Source & license

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

• Author: RyanMakesAndBreaksStuff
• Source: RyanMakesAndBreaksStuff/Custom-Codex-Claude-Plugins-and-Skills
• License: MIT

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