vasu-playwright-utils 1.24.2 → 1.25.0

package/README.md

@@ -123,6 +123,12 @@ To update after upgrading the library, run the command again with `--force`:
 npx vasu-pw-setup --force
 ```
 
+`--force` overwrites skills, agents, and cursor rules. To also overwrite `CLAUDE.md` (which is normally preserved), add `--force-claude`:
+
+```bash
+npx vasu-pw-setup --force --force-claude
+```
+
 ### How skills and agents are invoked
 
 - **Claude Code** auto-discovers `.claude/skills/` and `.claude/agents/`. `CLAUDE.md` instructs the agent to use `playwright-cli` and `vasu-playwright-utils` skills when writing tests, and to follow agent workflows (Planner / Generator / Healer) when asked to plan, generate, or fix tests.
@@ -132,17 +138,27 @@ To test: ask the agent to "write a test case to login for https://example.com" (
 
 ### For contributors
 
-Skills, agents, and cursor rules are pre-installed via symlinks — edit the source directories and changes are reflected everywhere:
+All distributable assets live under `templates/`. Symlinks make them available to Claude Code and Cursor during local development — edit the source in `templates/` and changes are reflected everywhere:
 
-| Symlink                                   | Source of truth                          |
-| ----------------------------------------- | ---------------------------------------- |
-| `.claude/skills/vasu-playwright-utils`    | `skills/vasu-playwright-utils/`          |
-| `.claude/agents`                          | `agents/`                                |
-| `.cursor/rules/playwright-agents.mdc`     | `cursor-rules/playwright-agents.mdc`     |
-| `.cursor/rules/vasu-playwright-utils.mdc` | `cursor-rules/vasu-playwright-utils.mdc` |
+| Symlink                                   | Source of truth                                    |
+| ----------------------------------------- | -------------------------------------------------- |
+| `.claude/skills/vasu-playwright-utils`    | `templates/skills/vasu-playwright-utils/`          |
+| `.claude/skills/playwright-cli`           | `templates/skills/playwright-cli/`                 |
+| `.claude/agents`                          | `templates/agents/`                                |
+| `.cursor/rules/playwright-agents.mdc`     | `templates/cursor-rules/playwright-agents.mdc`     |
+| `.cursor/rules/vasu-playwright-utils.mdc` | `templates/cursor-rules/vasu-playwright-utils.mdc` |
+| `.cursor/rules/project.mdc`               | `templates/cursor-rules/project.mdc`               |
 
 `.cursor/rules/project.mdc` loads `CLAUDE.md` into Cursor so both Claude Code and Cursor share the same project instructions.
 
+#### Syncing `playwright-cli` skill into `templates/`
+
+After refreshing the skill locally (e.g. `npx skills update microsoft/playwright-cli --skill playwright-cli -a claude-code` so `.claude/skills/playwright-cli` is current), sync it into templates and commit:
+
+```bash
+npm run sync:playwright-cli-skill
+```
+
 ## Issues and Feedback
 
 If you encounter any issues or have feedback, please [Raise an Issue](https://github.com/vasu31dev/playwright-ts-lib/issues) on GitHub.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vasu-playwright-utils",
-  "version": "1.24.2",
+  "version": "1.25.0",
   "description": "Playwright Typescript Library with reusable utilities",
   "main": "./dist/src/vasu-playwright-lib/index.js",
   "types": "./dist/src/vasu-playwright-lib/index.d.ts",
@@ -40,16 +40,13 @@
     "access": "public"
   },
   "bin": {
-    "vasu-pw-setup": "./bin/setup.js"
+    "vasu-pw-setup": "scripts/setup.js"
   },
   "files": [
     "dist",
     "src",
     "eslint.config.base.mjs",
-    "skills",
-    "agents",
-    "cursor-rules",
-    "bin",
+    "scripts",
     "templates"
   ],
   "engines": {
@@ -57,10 +54,9 @@
   },
   "dependencies": {
     "@eslint/js": "^9.39.4",
-    "@playwright/cli": "^0.1.1",
     "@types/node": "^25.5.0",
-    "@typescript-eslint/eslint-plugin": "^8.57.1",
-    "@typescript-eslint/parser": "^8.57.1",
+    "@typescript-eslint/eslint-plugin": "^8.57.2",
+    "@typescript-eslint/parser": "^8.57.2",
     "cross-env": "^10.1.0",
     "dotenv": "^17.3.1",
     "eslint": "^9.39.4",
@@ -81,12 +77,9 @@
   "peerDependencies": {
     "@playwright/test": ">=1.58.2"
   },
-  "overrides": {
-    "playwright": "^1.58.2"
-  },
   "scripts": {
-    "ncu:check": "npx npm-check-updates --reject \"eslint,@eslint/js\" --dep prod,dev,optional,peer && npx npm-check-updates \"eslint,@eslint/js\" --target minor --deep peer",
-    "ncu:update": "npx npm-check-updates --reject \"eslint,@eslint/js\" --dep prod,dev,optional,peer -u && npx npm-check-updates \"eslint,@eslint/js\" --target minor --deep peer -u",
+    "ncu:check": "npx npm-check-updates --reject \"eslint,@eslint/js,typescript\" --dep prod,dev,optional,peer && npx npm-check-updates \"eslint,@eslint/js\" --target minor --deep peer && npx npm-check-updates typescript --target minor",
+    "ncu:update": "npx npm-check-updates --reject \"eslint,@eslint/js,typescript\" --dep prod,dev,optional,peer -u && npx npm-check-updates \"eslint,@eslint/js\" --target minor --deep peer -u && npx npm-check-updates typescript --target minor -u",
     "clean": "rimraf dist",
     "prebuild": "npm run clean",
     "build": "tsc -p tsconfig.build.json",
@@ -110,7 +103,8 @@
     "prepare": "husky",
     "format": "cross-env prettier --write 'src/**/*.ts' 'tests/**/*.ts' 'test-setup/**/*.ts' 'playwright.config.ts' '**/*.json' '**/*.md' '!package-lock.json' '!dist/**/*' '!build/**/*'",
     "postinstall": "playwright install chromium",
-    "setup": "node bin/setup.js"
+    "setup": "node scripts/setup.js",
+    "sync:playwright-cli-skill": "rm -rf templates/skills/playwright-cli && cp -r .claude/skills/playwright-cli templates/skills/playwright-cli"
   },
   "husky": {
     "hooks": {

package/scripts/setup.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const args = process.argv.slice(2);
+const FORCE = args.includes('--force');
+const FORCE_CLAUDE = args.includes('--force-claude');
+const skillsFlag = args.includes('--skills');
+const agentsFlag = args.includes('--agents');
+// No flags → full install. One flag → that part only. Both flags → full install (same as neither).
+const noScopeFlags = !skillsFlag && !agentsFlag;
+const INSTALL_SKILLS = noScopeFlags || skillsFlag;
+const INSTALL_AGENTS = noScopeFlags || agentsFlag;
+
+/**
+ * Resolve the consumer project root.
+ * - INIT_CWD is set by npm/yarn when running lifecycle scripts or npx.
+ * - Falls back to walking up from cwd looking for package.json.
+ */
+function resolveProjectRoot() {
+  if (process.env.INIT_CWD) {
+    return process.env.INIT_CWD;
+  }
+  let dir = process.cwd();
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return process.cwd();
+}
+
+/**
+ * Recursively copy a directory, skipping existing files unless force is true.
+ */
+function copyDirSync(src, dest, force) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirSync(srcPath, destPath, force);
+    } else {
+      if (!force && fs.existsSync(destPath)) {
+        console.log(`  [skip] ${path.relative(projectRoot, destPath)} (exists, use --force to overwrite)`);
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+        console.log(`  [copy] ${path.relative(projectRoot, destPath)}`);
+      }
+    }
+  }
+}
+
+/**
+ * Install a directory component by copying from package templates to consumer project.
+ */
+function installDir(name, src, dest, force) {
+  if (!fs.existsSync(src)) {
+    console.error(`\nError: ${name} source not found at`, src);
+    process.exit(1);
+  }
+  console.log(`\n${step++}. Installing ${name}:`);
+  copyDirSync(src, dest, force);
+  installed.push(path.relative(projectRoot, dest));
+}
+
+/**
+ * Install a single file, skipping if it exists and force is false.
+ */
+function installFile(src, dest, force) {
+  const rel = path.relative(projectRoot, dest);
+  if (!force && fs.existsSync(dest)) {
+    console.log(`  [skip] ${rel} (exists, use --force to overwrite)`);
+    return;
+  }
+  if (!fs.existsSync(src)) {
+    console.log(`  [skip] ${rel} (source not found)`);
+    return;
+  }
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+  console.log(`  [copy] ${rel}`);
+}
+
+// --- Main ---
+
+const projectRoot = resolveProjectRoot();
+const pkgDir = path.resolve(__dirname, '..');
+const templatesDir = path.join(pkgDir, 'templates');
+const installed = [];
+let step = 1;
+
+console.log('vasu-playwright-utils: Setting up AI skills and agents...\n');
+console.log(`Project root: ${projectRoot}`);
+
+if (INSTALL_SKILLS) {
+  installDir(
+    'vasu-playwright-utils skills',
+    path.join(templatesDir, 'skills', 'vasu-playwright-utils'),
+    path.join(projectRoot, '.claude', 'skills', 'vasu-playwright-utils'),
+    FORCE,
+  );
+
+  installDir(
+    'playwright-cli skills',
+    path.join(templatesDir, 'skills', 'playwright-cli'),
+    path.join(projectRoot, '.claude', 'skills', 'playwright-cli'),
+    FORCE,
+  );
+
+  console.log(`\n${step++}. Installing Cursor rules (skills):`);
+  installFile(
+    path.join(templatesDir, 'cursor-rules', 'vasu-playwright-utils.mdc'),
+    path.join(projectRoot, '.cursor', 'rules', 'vasu-playwright-utils.mdc'),
+    FORCE,
+  );
+  installFile(
+    path.join(templatesDir, 'cursor-rules', 'project.mdc'),
+    path.join(projectRoot, '.cursor', 'rules', 'project.mdc'),
+    FORCE,
+  );
+
+  console.log(`\n${step++}. Installing CLAUDE.md template:`);
+  installFile(path.join(templatesDir, 'CLAUDE.md'), path.join(projectRoot, 'CLAUDE.md'), FORCE_CLAUDE);
+}
+
+if (INSTALL_AGENTS) {
+  installDir(
+    'playwright agents',
+    path.join(templatesDir, 'agents'),
+    path.join(projectRoot, '.claude', 'agents'),
+    FORCE,
+  );
+
+  console.log(`\n${step++}. Installing Cursor rules (agents):`);
+  installFile(
+    path.join(templatesDir, 'cursor-rules', 'playwright-agents.mdc'),
+    path.join(projectRoot, '.cursor', 'rules', 'playwright-agents.mdc'),
+    FORCE,
+  );
+}
+
+// Summary
+console.log('\nDone! Installed to:');
+for (const p of installed) {
+  console.log(`  ${p}`);
+}
+console.log('\nBoth Claude Code and Cursor will auto-discover:');
+console.log('  .claude/skills/   — API skills (Claude Code & Cursor via .cursor/rules/)');
+console.log('  .claude/agents/   — Agent workflows (Claude Code)');
+console.log('  .cursor/rules/    — Cursor rules referencing .claude/ skills and agents\n');

package/{cursor-rules → templates/cursor-rules}/playwright-agents.mdc

@@ -8,7 +8,7 @@ globs: ["**/*.spec.ts", "**/*.test.ts", "specs/**", "tests/**"]
 When working on Playwright tests you **must**:
 
 1. **Use `playwright-cli`** to verify flows — run `playwright-cli open <url>`, `playwright-cli snapshot`, then interact (click, fill) to capture real selectors. Never guess selectors.
-2. **Follow the locator strategy** in `skills/vasu-playwright-utils/references/locators.md` when writing selectors.
+2. **Follow the locator strategy** in `.claude/skills/vasu-playwright-utils/references/locators.md` when writing selectors.
 3. **Use the right agent workflow** when the user asks to:
    - Create a test plan or explore an app → **Test Planner**
    - Generate a test from a plan or scenario → **Test Generator**
@@ -25,6 +25,6 @@ When working on Playwright tests you **must**:
 
 ## Agent Details
 
-@file agents/playwright-test-planner.md
-@file agents/playwright-test-generator.md
-@file agents/playwright-test-healer.md
+@file .claude/agents/playwright-test-planner.md
+@file .claude/agents/playwright-test-generator.md
+@file .claude/agents/playwright-test-healer.md

package/{cursor-rules → templates/cursor-rules}/vasu-playwright-utils.mdc

@@ -20,7 +20,7 @@ Playwright TypeScript utility library with simplified helper functions for brows
 
 ## Full API Documentation
 
-@file skills/vasu-playwright-utils/SKILL.md
-@file skills/vasu-playwright-utils/references/actions.md
-@file skills/vasu-playwright-utils/references/assertions.md
-@file skills/vasu-playwright-utils/references/locators.md
+@file .claude/skills/vasu-playwright-utils/SKILL.md
+@file .claude/skills/vasu-playwright-utils/references/actions.md
+@file .claude/skills/vasu-playwright-utils/references/assertions.md
+@file .claude/skills/vasu-playwright-utils/references/locators.md

package/templates/skills/playwright-cli/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: playwright-cli
+description: Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages.
+allowed-tools: Bash(playwright-cli:*)
+---
+
+# Browser Automation with playwright-cli
+
+## Quick start
+
+```bash
+# open new browser
+playwright-cli open
+# navigate to a page
+playwright-cli goto https://playwright.dev
+# interact with the page using refs from the snapshot
+playwright-cli click e15
+playwright-cli type "page.click"
+playwright-cli press Enter
+# take a screenshot (rarely used, as snapshot is more common)
+playwright-cli screenshot
+# close the browser
+playwright-cli close
+```
+
+## Commands
+
+### Core
+
+```bash
+playwright-cli open
+# open and navigate right away
+playwright-cli open https://example.com/
+playwright-cli goto https://playwright.dev
+playwright-cli type "search query"
+playwright-cli click e3
+playwright-cli dblclick e7
+playwright-cli fill e5 "user@example.com"
+playwright-cli drag e2 e8
+playwright-cli hover e4
+playwright-cli select e9 "option-value"
+playwright-cli upload ./document.pdf
+playwright-cli check e12
+playwright-cli uncheck e12
+playwright-cli snapshot
+playwright-cli snapshot --filename=after-click.yaml
+playwright-cli eval "document.title"
+playwright-cli eval "el => el.textContent" e5
+playwright-cli dialog-accept
+playwright-cli dialog-accept "confirmation text"
+playwright-cli dialog-dismiss
+playwright-cli resize 1920 1080
+playwright-cli close
+```
+
+### Navigation
+
+```bash
+playwright-cli go-back
+playwright-cli go-forward
+playwright-cli reload
+```
+
+### Keyboard
+
+```bash
+playwright-cli press Enter
+playwright-cli press ArrowDown
+playwright-cli keydown Shift
+playwright-cli keyup Shift
+```
+
+### Mouse
+
+```bash
+playwright-cli mousemove 150 300
+playwright-cli mousedown
+playwright-cli mousedown right
+playwright-cli mouseup
+playwright-cli mouseup right
+playwright-cli mousewheel 0 100
+```
+
+### Save as
+
+```bash
+playwright-cli screenshot
+playwright-cli screenshot e5
+playwright-cli screenshot --filename=page.png
+playwright-cli pdf --filename=page.pdf
+```
+
+### Tabs
+
+```bash
+playwright-cli tab-list
+playwright-cli tab-new
+playwright-cli tab-new https://example.com/page
+playwright-cli tab-close
+playwright-cli tab-close 2
+playwright-cli tab-select 0
+```
+
+### Storage
+
+```bash
+playwright-cli state-save
+playwright-cli state-save auth.json
+playwright-cli state-load auth.json
+
+# Cookies
+playwright-cli cookie-list
+playwright-cli cookie-list --domain=example.com
+playwright-cli cookie-get session_id
+playwright-cli cookie-set session_id abc123
+playwright-cli cookie-set session_id abc123 --domain=example.com --httpOnly --secure
+playwright-cli cookie-delete session_id
+playwright-cli cookie-clear
+
+# LocalStorage
+playwright-cli localstorage-list
+playwright-cli localstorage-get theme
+playwright-cli localstorage-set theme dark
+playwright-cli localstorage-delete theme
+playwright-cli localstorage-clear
+
+# SessionStorage
+playwright-cli sessionstorage-list
+playwright-cli sessionstorage-get step
+playwright-cli sessionstorage-set step 3
+playwright-cli sessionstorage-delete step
+playwright-cli sessionstorage-clear
+```
+
+### Network
+
+```bash
+playwright-cli route "**/*.jpg" --status=404
+playwright-cli route "https://api.example.com/**" --body='{"mock": true}'
+playwright-cli route-list
+playwright-cli unroute "**/*.jpg"
+playwright-cli unroute
+```
+
+### DevTools
+
+```bash
+playwright-cli console
+playwright-cli console warning
+playwright-cli network
+playwright-cli run-code "async page => await page.context().grantPermissions(['geolocation'])"
+playwright-cli tracing-start
+playwright-cli tracing-stop
+playwright-cli video-start
+playwright-cli video-stop video.webm
+```
+
+## Open parameters
+
+```bash
+# Use specific browser when creating session
+playwright-cli open --browser=chrome
+playwright-cli open --browser=firefox
+playwright-cli open --browser=webkit
+playwright-cli open --browser=msedge
+# Connect to browser via extension
+playwright-cli open --extension
+
+# Use persistent profile (by default profile is in-memory)
+playwright-cli open --persistent
+# Use persistent profile with custom directory
+playwright-cli open --profile=/path/to/profile
+
+# Start with config file
+playwright-cli open --config=my-config.json
+
+# Close the browser
+playwright-cli close
+# Delete user data for the default session
+playwright-cli delete-data
+```
+
+## Snapshots
+
+After each command, playwright-cli provides a snapshot of the current browser state.
+
+```bash
+> playwright-cli goto https://example.com
+### Page
+- Page URL: https://example.com/
+- Page Title: Example Domain
+### Snapshot
+[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)
+```
+
+You can also take a snapshot on demand using `playwright-cli snapshot` command.
+
+If `--filename` is not provided, a new snapshot file is created with a timestamp. Default to automatic file naming, use `--filename=` when artifact is a part of the workflow result.
+
+## Browser Sessions
+
+```bash
+# create new browser session named "mysession" with persistent profile
+playwright-cli -s=mysession open example.com --persistent
+# same with manually specified profile directory (use when requested explicitly)
+playwright-cli -s=mysession open example.com --profile=/path/to/profile
+playwright-cli -s=mysession click e6
+playwright-cli -s=mysession close  # stop a named browser
+playwright-cli -s=mysession delete-data  # delete user data for persistent session
+
+playwright-cli list
+# Close all browsers
+playwright-cli close-all
+# Forcefully kill all browser processes
+playwright-cli kill-all
+```
+
+## Local installation
+
+In some cases user might want to install playwright-cli locally. If running globally available `playwright-cli` binary fails, use `npx playwright-cli` to run the commands. For example:
+
+```bash
+npx playwright-cli open https://example.com
+npx playwright-cli click e1
+```
+
+## Example: Form submission
+
+```bash
+playwright-cli open https://example.com/form
+playwright-cli snapshot
+
+playwright-cli fill e1 "user@example.com"
+playwright-cli fill e2 "password123"
+playwright-cli click e3
+playwright-cli snapshot
+playwright-cli close
+```
+
+## Example: Multi-tab workflow
+
+```bash
+playwright-cli open https://example.com
+playwright-cli tab-new https://example.com/other
+playwright-cli tab-list
+playwright-cli tab-select 0
+playwright-cli snapshot
+playwright-cli close
+```
+
+## Example: Debugging with DevTools
+
+```bash
+playwright-cli open https://example.com
+playwright-cli click e4
+playwright-cli fill e7 "test"
+playwright-cli console
+playwright-cli network
+playwright-cli close
+```
+
+```bash
+playwright-cli open https://example.com
+playwright-cli tracing-start
+playwright-cli click e4
+playwright-cli fill e7 "test"
+playwright-cli tracing-stop
+playwright-cli close
+```
+
+## Specific tasks
+
+- **Request mocking** [references/request-mocking.md](references/request-mocking.md)
+- **Running Playwright code** [references/running-code.md](references/running-code.md)
+- **Browser session management** [references/session-management.md](references/session-management.md)
+- **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
+- **Test generation** [references/test-generation.md](references/test-generation.md)
+- **Tracing** [references/tracing.md](references/tracing.md)
+- **Video recording** [references/video-recording.md](references/video-recording.md)

package/templates/skills/playwright-cli/references/request-mocking.md

@@ -0,0 +1,87 @@
+# Request Mocking
+
+Intercept, mock, modify, and block network requests.
+
+## CLI Route Commands
+
+```bash
+# Mock with custom status
+playwright-cli route "**/*.jpg" --status=404
+
+# Mock with JSON body
+playwright-cli route "**/api/users" --body='[{"id":1,"name":"Alice"}]' --content-type=application/json
+
+# Mock with custom headers
+playwright-cli route "**/api/data" --body='{"ok":true}' --header="X-Custom: value"
+
+# Remove headers from requests
+playwright-cli route "**/*" --remove-header=cookie,authorization
+
+# List active routes
+playwright-cli route-list
+
+# Remove a route or all routes
+playwright-cli unroute "**/*.jpg"
+playwright-cli unroute
+```
+
+## URL Patterns
+
+```
+**/api/users           - Exact path match
+**/api/*/details       - Wildcard in path
+**/*.{png,jpg,jpeg}    - Match file extensions
+**/search?q=*          - Match query parameters
+```
+
+## Advanced Mocking with run-code
+
+For conditional responses, request body inspection, response modification, or delays:
+
+### Conditional Response Based on Request
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/login', route => {
+    const body = route.request().postDataJSON();
+    if (body.username === 'admin') {
+      route.fulfill({ body: JSON.stringify({ token: 'mock-token' }) });
+    } else {
+      route.fulfill({ status: 401, body: JSON.stringify({ error: 'Invalid' }) });
+    }
+  });
+}"
+```
+
+### Modify Real Response
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/user', async route => {
+    const response = await route.fetch();
+    const json = await response.json();
+    json.isPremium = true;
+    await route.fulfill({ response, json });
+  });
+}"
+```
+
+### Simulate Network Failures
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/offline', route => route.abort('internetdisconnected'));
+}"
+# Options: connectionrefused, timedout, connectionreset, internetdisconnected
+```
+
+### Delayed Response
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/slow', async route => {
+    await new Promise(r => setTimeout(r, 3000));
+    route.fulfill({ body: JSON.stringify({ data: 'loaded' }) });
+  });
+}"
+```