# Browser Automation

> Interactive browser automation and visual validation using a Playwright MCP server, from Claude Code or Codex. Creates a bridge between the agent and a live browser session (including authenticated user context), with optional scripted Playwright test generation for repeatable checks. Triggers on "browser automation", "interactive browser", "playwright mcp", "test the ui", "ui test", "visual test…

- **Type:** Skill
- **Install:** `agentstack add skill-ryanmakesandbreaksstuff-custom-codex-claude-plugins-and-skills-browser-automation`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [RyanMakesAndBreaksStuff](https://agentstack.voostack.com/s/ryanmakesandbreaksstuff)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [RyanMakesAndBreaksStuff](https://github.com/RyanMakesAndBreaksStuff)
- **Source:** https://github.com/RyanMakesAndBreaksStuff/Custom-Codex-Claude-Plugins-and-Skills/tree/main/power-platform-full-stack-skills-v2(No longer copilot only)/skills/browser-automation

## Install

```sh
agentstack add skill-ryanmakesandbreaksstuff-custom-codex-claude-plugins-and-skills-browser-automation
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.

2. **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

3. **Playwright installed (optional, for repeatable scripts):**

   ```bash
   npm init playwright@latest
   ```

4. **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.
4. **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`.
5. **Never skip the edge case checklist.** After the happy path, run through edge cases.
   Read `resources/edge-cases.md`.
6. **Protect authenticated context.** Avoid unnecessary sign-out/navigation that invalidates user login state.
7. **Review the FULL evidence** — video/screenshots + captions, not just one artifact.
8. **Persist workflow state to disk.** Use the shared `workflow-state` skill (`../workflow-state/SKILL.md`) and keep state synchronized with your todo list.
9. **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.
10. **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.

11. **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 }
    ```

12. **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.

13. **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).

14. **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.

15. **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.

2. **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.

3. **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).

4. **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

5. **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.

6. **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](https://github.com/RyanMakesAndBreaksStuff)
- **Source:** [RyanMakesAndBreaksStuff/Custom-Codex-Claude-Plugins-and-Skills](https://github.com/RyanMakesAndBreaksStuff/Custom-Codex-Claude-Plugins-and-Skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ryanmakesandbreaksstuff-custom-codex-claude-plugins-and-skills-browser-automation
- Seller: https://agentstack.voostack.com/s/ryanmakesandbreaksstuff
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.