playwright-in-sandbox

What this skill does

# Playwright In Sandbox

This is the primary Playwright skill for sandbox browser verification and deterministic end-to-end coverage.

Use it in two explicit modes:

1. **Interactive Sandbox Mode** as final browser verification after a task's implementation is in a plausibly correct state.
2. **Deterministic E2E Mode** before finishing a task when the changed flow should be protected by durable regression coverage.

This skill is intentionally generic. It should work for:

- task-level screenshot-driven verification after an agent has implemented UI work and needs browser proof
- formal Playwright E2E authoring or rewrite work in downstream application repos
- task flows where a final browser verification should happen before the task is considered complete

Do not use this skill for backend-only work, one-off page operations that do not justify browser automation, or broad failure storms before you understand the workflow inventory and root causes.

## Core Workflow

1. Write a brief QA inventory before touching the browser.
2. Decide the mode first: Interactive Sandbox Mode or Deterministic E2E Mode.
3. Start or confirm the app in a persistent session.
4. Implement the change and get the functionality into a plausibly correct state before using Playwright as signoff.
5. Run the changed flow interactively and inspect screenshots as evidence, not just DOM state.
6. Record the contracts you learned:
   - route-ready signals
   - modal open and close signals
   - action-enabled conditions
   - save-complete signals
   - durable `data-testid` or semantic selectors
7. If the flow is bug-fix, workflow, regression-critical, or meaningfully changed, graduate it into deterministic E2E coverage.
8. If interactive proof shows the product behavior is wrong, fix the product code or the data contract. Do not make a bad behavior look green by weakening the test.
9. Before finishing the task, ensure the changed flow has both:
   - successful interactive proof
   - durable E2E coverage or an explicit rationale why it stays interactive-only

## Common Rules

These rules apply to both Interactive Sandbox Mode and Deterministic E2E Mode.

- Interactive verification is a post-change signoff step. Do not treat it as random mid-task poking while the implementation is still half-built.
- If the browser proves the product behavior is wrong, fix the functionality or the underlying data contract. Do not invent clever ways to make the test green around a bug.
- Use the repo's canonical E2E database contract strictly. If the repo standard is `e2e.db`, use `e2e.db`. If `e2e.db` is missing and the repo expects one, create or provision `e2e.db` and keep using that contract. Do not silently fall back to the normal application database.
- Prefer querying the canonical E2E database or seeded business data to derive expected values, statuses, assignments, and aggregates. When the repo uses `better-sqlite3`, it is acceptable to inspect the DB directly to confirm the real expected value before asserting the UI.
- Prefer selectors in this order:
  1. explicit `id`, `data-*`, `data-testid`, or other owned semantic contracts
  2. accessible role plus stable accessible name
  3. label/control association
  4. stable URL, pathname, or query contract
  5. text-only selectors only when the text itself is the product contract
  6. CSS, XPath, or DOM-order selectors only for deliberate structure checks
- Remove stale screenshots, traces, and temporary artifacts from failed or superseded runs before signoff.
- If the repo has a maintained full-suite run, nightly QA run, or automated health check, keep visibility on whether it actually ran and whether it stayed green. Targeted checks do not replace suite health forever.
- Some migrated or one-off client applications may temporarily need broader migration-verification coverage than a typical greenfield app. That is allowed, but the quality bar stays the same: deterministic selectors, owned data, real user contracts, and no fake greens.

## Mode Selection

### Use Interactive Sandbox Mode when

- the implementation is already in a plausibly correct state
- you need final browser proof that the changed flow really works for a user
- you need screenshot evidence to judge whether the UI is actually correct
- you need to learn or confirm readiness gates, modal behavior, or durable selectors before writing or updating automated coverage

### Use Deterministic E2E Mode when

- the change fixes a bug
- the task creates or materially changes a user workflow
- the flow is business-critical or likely to regress
- legacy Playwright coverage is being rewritten, consolidated, or retired
- the task should not be considered complete without regression protection

### Stay in Interactive Mode only when

- the change is exploratory or temporary
- the flow is not durable enough yet to encode as regression coverage
- the task does not meaningfully change a maintained workflow
- a migrated or one-off app needs a temporary verification pass that is not yet stable enough to convert into durable E2E coverage

If you choose not to graduate to committed E2E coverage, be explicit about why.

## Shared Environment Contract

- Prefer `127.0.0.1` over `localhost` unless the repo defines something else explicitly.
- Use the repo's explicit server contract first. If the repo does not define one, `4444` is the common sandbox default.
- In sandbox environments, Playwright browsers may live under `/ms-playwright`; do not assume the default cache path.
- In sandbox environments, launch Chromium explicitly in headless mode: `chromium.launch({ headless: true })`.
- Confirm the Playwright browser path when there is any doubt about the runtime payload:

```bash
echo "$PLAYWRIGHT_BROWSERS_PATH"
ls -al /ms-playwright
```

- Before `page.goto(...)`, verify the target port is actually listening and the app responds.
- For standard runs, use the repo's canonical E2E database contract. If the repo standard is `e2e.db`, always use `e2e.db`.
- If the repo expects `e2e.db` and it is missing, create or provision `e2e.db` before running tests.
- Only use alternate DB names or paths when the repo explicitly supports isolated validation lanes and you are intentionally isolating worker runs.
- Keep interactive artifacts separate from committed regression assets.
  - scratch scripts and screenshots belong in temp or dedicated artifact folders
  - committed regression coverage belongs in `tests/e2e/` or the repo's formal test location
- Remove stale screenshots, traces, and temporary artifacts from failed or superseded runs before signoff.
- When running multiple rewrite or validation lanes in parallel, isolate runtime resources:
  - port
  - database or seed state
  - output folder
  - screenshots and traces

## Interactive Sandbox Mode

Use this mode to prove a changed user flow works right now after the implementation is done enough to verify.

Interactive mode is not permission to poke until something happens to pass once. Use it after implementing the change and after you believe the functionality should work, then use the browser as final visual and functional verification of the real user flow.

### QA Inventory

Build the inventory from three sources:

- the user's requested requirements
- the user-visible behavior you implemented or changed
- the claims you expect to make in the final response

Anything that appears in any of those three sources must map to at least one QA check before signoff.

List:

- the user-visible claims you intend to sign off on
- every meaningful control, mode switch, or implemented interactive behavior
- the state changes or view changes each control can cause
- at least two exploratory or off-happy-path probes

### Desktop Verification Script

Set `TARGET_URL` to the app you are debugging. Prefer `127.0.0.1` over `localhost`.

```javascript
import { chromium } from "playwright";

const TARGET_URL = "http://127.0.0.1:4444";
const browser = await chromium.launch({ h