playwright-interactive

Files (5)

• NOTICE.txt
• SKILL.md
• openai.yaml · agents/
• playwright-small.svg · assets/
• playwright.png · assets/

SKILL.md (first lines)

# Playwright Interactive Skill

Use a persistent Playwright `js_repl` session to debug local web or Electron apps, keep the same handles between iterations, and run functional and visual QA without restarting the entire toolchain unless process ownership has actually changed.

## Prerequisites

- `js_repl` must be enabled for this skill.
- If `js_repl` is missing, enable it in `~/.codex/config.toml`:

```toml
[features]
js_repl = true
```

- You can also start a new session with `--enable js_repl` (equivalent to `-c features.js_repl=true`).
- After enabling `js_repl`, start a new Codex session so the tool list refreshes.
- For now, run this workflow with the sandbox disabled: launch Codex with `--sandbox danger-full-access` (or the equivalent configuration for `sandbox_mode=danger-full-access`). This is a temporary requirement while `js_repl` + Playwright support inside the sandbox is still being finalized.
- Run setup from the same project directory you intend to debug.
- Treat `js_repl_reset` as a recovery tool, not routine cleanup. Resetting the kernel destroys your Playwright handles.

## One-time setup

```bash
test -f package.json || npm init -y
npm install playwright
# Web-only, for headed Chromium or mobile emulation:
# npx playwright install chromium
# Electron-only, and only if the target workspace is the app itself:
# npm install --save-dev electron
node -e "import('playwright').then(() => console.log('playwright import ok')).catch((error) => { console.error(error); process.exit(1); })"
```

If you later switch to a different workspace, repeat setup there.

## Main workflow

1. Before testing, build a brief QA inventory:
   - Build the inventory from three sources: user-requested requirements, user-facing functionality or behavior actually implemented, and claims you plan to make in the final response.
   - Anything that appears in any of these three sources must map to at least one QA check before signoff.
   - List the user-facing claims you intend to sign off on.
   - List every meaningful user-facing control, mode toggle, or implemented interactive behavior.
   - List the state or view changes each control or implemented behavior can produce.
   - Use this as the shared coverage list for both functional QA and visual QA.
   - For each "claim or control state" pair, note the intended functional check, the specific state in which the visual check should occur, and the evidence you plan to capture.
   - If a requirement is visually central but subjective, convert it into an observable QA check rather than leaving it implicit.
   - Add at least 2 exploratory or off-happy-path scenarios that could reveal brittle behavior.
2. Run the bootstrap cell once.
3. Start or confirm the necessary dev server in a persistent TTY session.
4. Launch the desired runtime and continue reusing the same Playwright handles.
5. After each code change, reload for renderer-only changes or relaunch for main-process / startup changes.
6. Run functional QA with normal user input.
7. Run a separate visual QA pass.
8. Verify viewport conformance and capture the screenshots needed to support your claims.
9. Clean up the Playwright session only when the task is genuinely complete.

## Bootstrap (run once)

```javascript
var chromium;
var electronLauncher;
var browser;
var context;
var page;
var mobileContext;
var mobilePage;
var electronApp;
var appWindow;

try {
  ({ chromium, _electron: electronLauncher } = await import("playwright"));
  console.log("Playwright loaded");
} catch (error) {
  throw new Error(
    `Could not load playwright from the current js_repl cwd. Run the setup commands from this workspace first. Original error: ${error}`
  );
}
```

Binding rules:

- Use `var` for shared top-level Playwright handles, because subsequent `js_repl` cells reuse them.
- The setup cells below intentionally describe a short happy path. If a handle looks stale, set that binding to `undefined` and re-run the cell rather than scattering recovery logic everywhere.
- Prefer one named handle per surface of interest (`page`, `mobilePage`, `appWindow`) rather than re-discovering pages from a context.

Shared web helpers:

```javascript
var resetWebHandles = function () {
  context = undefined;
  page = undefined;
  mobileContext = undefined;
  mobilePage = undefined;
};

var ensureWebBrowser = async function () {
  if (browser && !browser.isConnected()) {
    browser = undefined;
    resetWebHandles();
  }

  browser ??= await chromium.launch({ headless: false });
  return browser;
};

var reloadWebContexts = async function () {
  for (const currentContext of [context, mobileContext]) {
    if (!currentContext) continue;
    for (const p of currentContext.pages()) {
      await p.reload({ waitUntil: "domcontentloaded" });
    }
  }
  console.log("Reloaded existing web tabs");
};
```

## Choosing a session mode

For web apps, default to an explicit viewport, and treat native window mode as a separate validation pass.

From wachawo/claude-skills, MIT.

More from wachawo/claude-skills