electron-playwright-cli 0.1.0

package/playwright-electron/electron-daemon.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+"use strict";
+
+// electron daemon — launched by playwright-cli.js as a subprocess.
+// assembles a playwright CLI daemon with electron browser support.
+//
+// receives CLI args:
+//   --daemon=<socketPath>     unix socket path to listen on
+//   --config=<configFile>     optional path to config JSON file
+//   --user-data-dir=<path>    optional user data directory
+
+const fs = require("fs");
+const path = require("path");
+
+const playwrightDir = path.dirname(require.resolve("playwright/package.json"));
+
+function resolveInternal(relativePath) {
+  return path.join(playwrightDir, relativePath);
+}
+
+// --- import playwright internals via absolute paths ---
+
+const { BrowserServerBackend } = require(
+  resolveInternal("lib/mcp/browser/browserServerBackend.js"),
+);
+const { resolveConfig } = require(resolveInternal("lib/mcp/browser/config.js"));
+const { startMcpDaemonServer } = require(
+  resolveInternal("lib/mcp/terminal/daemon.js"),
+);
+const { browserTools } = require(resolveInternal("lib/mcp/browser/tools.js"));
+const { commands } = require(resolveInternal("lib/mcp/terminal/commands.js"));
+const { z } = require("playwright-core/lib/mcpBundle");
+
+// --- import our electron extensions ---
+
+const { ElectronContextFactory } = require("./electron-context-factory");
+const electronTools = require("./electron-tools");
+
+// --- parse CLI args ---
+
+const args = require("minimist")(process.argv.slice(2));
+const socketPath = args.daemon;
+if (!socketPath) {
+  console.error("--daemon=<socketPath> is required");
+  process.exit(1);
+}
+
+async function main() {
+  // load config file if provided
+  let userConfig = {};
+  if (args.config && fs.existsSync(args.config)) {
+    userConfig = JSON.parse(fs.readFileSync(args.config, "utf-8"));
+  }
+
+  // set user data dir if provided
+  if (args["user-data-dir"]) {
+    userConfig.browser = userConfig.browser || {};
+    userConfig.browser.userDataDir = args["user-data-dir"];
+  }
+
+  // electron uses file: protocol — without this, Context._setupBrowserContext
+  // calls _setAllowedProtocols which blocks file: URLs
+  userConfig.allowUnrestrictedFileAccess = true;
+
+  // resolve full config by merging with playwright defaults
+  const config = await resolveConfig(userConfig);
+
+  // apply daemon-mode overrides (matches program.js daemon setup)
+  config.outputDir = path.join(process.cwd(), ".playwright-cli");
+  config.outputMode = "file";
+  config.codegen = "none";
+  config.snapshot.mode = "full";
+  config.capabilities = ["core", "internal", "tracing", "pdf", "vision"];
+
+  // register electron tools into the global browserTools array.
+  // BrowserServerBackend's constructor calls filteredTools(config) which
+  // reads from this same array reference, so pushing here ensures
+  // electron tools are included.
+  browserTools.push(...electronTools);
+
+  // register electron CLI commands so the daemon's parseCliCommand can
+  // dispatch them. the commands object is shared by reference with daemon.js.
+  commands["electron_evaluate"] = {
+    name: "electron_evaluate",
+    description: "execute JavaScript in the Electron main process",
+    args: z.object({
+      expression: z
+        .string()
+        .describe('JS expression, e.g. "electron => electron.app.getName()"'),
+    }),
+    toolName: "electron_evaluate",
+    toolParams: ({ expression }) => ({ expression }),
+  };
+  commands["electron_windows"] = {
+    name: "electron_windows",
+    description: "list all open Electron windows",
+    args: z.object({}),
+    toolName: "electron_windows",
+    toolParams: () => ({}),
+  };
+
+  // create the backend factory
+  const factory = new ElectronContextFactory(config);
+  const serverBackendFactory = {
+    create: () => new BrowserServerBackend(config, factory),
+  };
+
+  // start listening on the unix socket
+  const resolvedPath = await startMcpDaemonServer(
+    socketPath,
+    serverBackendFactory,
+  );
+  console.error(`Electron daemon listening on ${resolvedPath}`);
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/playwright-electron/electron-tools.js

@@ -0,0 +1,69 @@
+"use strict";
+
+// electron-specific tools for the playwright CLI daemon.
+// operate on the electron app instance stored on browserContext._electronApp.
+
+const { z } = require("playwright-core/lib/mcpBundle");
+
+const electronEvaluate = {
+  capability: "core",
+  schema: {
+    name: "electron_evaluate",
+    title: "Evaluate in Electron main process",
+    description:
+      "Execute a JavaScript expression in the Electron main process. The function receives the Electron module as its argument.",
+    inputSchema: z.object({
+      expression: z
+        .string()
+        .describe(
+          'JavaScript expression to evaluate in the main process. Receives electron module as argument, e.g. "electron => electron.app.getName()"',
+        ),
+    }),
+    type: "destructive",
+  },
+  handle: async (context, params, response) => {
+    const browserContext = await context.ensureBrowserContext();
+    const electronApp = browserContext._electronApp;
+    if (!electronApp)
+      throw new Error(
+        "Not running in Electron mode. This tool requires an Electron app context.",
+      );
+
+    const result = await electronApp.evaluate(params.expression);
+    const text = JSON.stringify(result, null, 2) ?? "undefined";
+    response.addTextResult(text);
+  },
+};
+
+const electronWindows = {
+  capability: "core",
+  schema: {
+    name: "electron_windows",
+    title: "List Electron windows",
+    description:
+      "List all open Electron windows with their title, URL, and index.",
+    inputSchema: z.object({}),
+    type: "readOnly",
+  },
+  handle: async (context, params, response) => {
+    const browserContext = await context.ensureBrowserContext();
+    const electronApp = browserContext._electronApp;
+    if (!electronApp)
+      throw new Error(
+        "Not running in Electron mode. This tool requires an Electron app context.",
+      );
+
+    const windows = electronApp.windows();
+    const windowInfos = await Promise.all(
+      windows.map(async (page, index) => ({
+        index,
+        title: await page.title(),
+        url: page.url(),
+      })),
+    );
+    const text = JSON.stringify(windowInfos, null, 2);
+    response.addTextResult(text);
+  },
+};
+
+module.exports = [electronEvaluate, electronWindows];

package/skills/playwright-cli/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: electron-playwright-cli
+description: Automates Electron desktop app interactions for testing, screenshots, and data extraction. Use when the user needs to interact with Electron apps, take screenshots, fill forms, click elements, or extract information from desktop applications.
+allowed-tools: Bash(electron-playwright-cli:*)
+---
+
+# Electron App Automation with electron-playwright-cli
+
+## Quick start
+
+```bash
+# take a snapshot of the running electron app (launches via config on first command)
+electron-playwright-cli snapshot
+# interact with the page using refs from the snapshot
+electron-playwright-cli click e15
+electron-playwright-cli type "search query"
+electron-playwright-cli press Enter
+```
+
+## Configuration
+
+Create `.playwright/cli.config.json` in your project root:
+
+```json
+{
+  "browser": {
+    "launchOptions": {
+      "args": ["path/to/your/main.js"]
+    }
+  }
+}
+```
+
+The `args` array is passed to Electron. Point it at your app's main process entry point.
+
+Optional launch options:
+- `executablePath`: path to the Electron binary (defaults to the one in node_modules)
+- `cwd`: working directory for the Electron process
+- `env`: additional environment variables
+- `timeout`: launch timeout in milliseconds
+
+## Commands
+
+### Core
+
+```bash
+electron-playwright-cli type "search query"
+electron-playwright-cli click e3
+electron-playwright-cli dblclick e7
+electron-playwright-cli fill e5 "user@example.com"
+electron-playwright-cli drag e2 e8
+electron-playwright-cli hover e4
+electron-playwright-cli select e9 "option-value"
+electron-playwright-cli upload ./document.pdf
+electron-playwright-cli check e12
+electron-playwright-cli uncheck e12
+electron-playwright-cli snapshot
+electron-playwright-cli snapshot --filename=after-click.yaml
+electron-playwright-cli eval "document.title"
+electron-playwright-cli eval "el => el.textContent" e5
+electron-playwright-cli dialog-accept
+electron-playwright-cli dialog-accept "confirmation text"
+electron-playwright-cli dialog-dismiss
+electron-playwright-cli resize 1920 1080
+electron-playwright-cli close
+```
+
+### Navigation
+
+Navigate within the Electron app's webview:
+
+```bash
+electron-playwright-cli goto https://example.com
+electron-playwright-cli go-back
+electron-playwright-cli go-forward
+electron-playwright-cli reload
+```
+
+### Keyboard
+
+```bash
+electron-playwright-cli press Enter
+electron-playwright-cli press ArrowDown
+electron-playwright-cli keydown Shift
+electron-playwright-cli keyup Shift
+```
+
+### Mouse
+
+```bash
+electron-playwright-cli mousemove 150 300
+electron-playwright-cli mousedown
+electron-playwright-cli mousedown right
+electron-playwright-cli mouseup
+electron-playwright-cli mouseup right
+electron-playwright-cli mousewheel 0 100
+```
+
+### Save as
+
+```bash
+electron-playwright-cli screenshot
+electron-playwright-cli screenshot e5
+electron-playwright-cli screenshot --filename=page.png
+```
+
+### Tabs
+
+```bash
+electron-playwright-cli tab-list
+electron-playwright-cli tab-new
+electron-playwright-cli tab-close
+electron-playwright-cli tab-close 2
+electron-playwright-cli tab-select 0
+```
+
+### Storage
+
+```bash
+electron-playwright-cli state-save
+electron-playwright-cli state-save auth.json
+electron-playwright-cli state-load auth.json
+
+# Cookies
+electron-playwright-cli cookie-list
+electron-playwright-cli cookie-list --domain=example.com
+electron-playwright-cli cookie-get session_id
+electron-playwright-cli cookie-set session_id abc123
+electron-playwright-cli cookie-set session_id abc123 --domain=example.com --httpOnly --secure
+electron-playwright-cli cookie-delete session_id
+electron-playwright-cli cookie-clear
+
+# LocalStorage
+electron-playwright-cli localstorage-list
+electron-playwright-cli localstorage-get theme
+electron-playwright-cli localstorage-set theme dark
+electron-playwright-cli localstorage-delete theme
+electron-playwright-cli localstorage-clear
+
+# SessionStorage
+electron-playwright-cli sessionstorage-list
+electron-playwright-cli sessionstorage-get step
+electron-playwright-cli sessionstorage-set step 3
+electron-playwright-cli sessionstorage-delete step
+electron-playwright-cli sessionstorage-clear
+```
+
+### Network
+
+```bash
+electron-playwright-cli route "**/*.jpg" --status=404
+electron-playwright-cli route "https://api.example.com/**" --body='{"mock": true}'
+electron-playwright-cli route-list
+electron-playwright-cli unroute "**/*.jpg"
+electron-playwright-cli unroute
+```
+
+### DevTools
+
+```bash
+electron-playwright-cli console
+electron-playwright-cli console warning
+electron-playwright-cli network
+electron-playwright-cli run-code "async page => await page.context().grantPermissions(['geolocation'])"
+electron-playwright-cli tracing-start
+electron-playwright-cli tracing-stop
+electron-playwright-cli video-start
+electron-playwright-cli video-stop video.webm
+```
+
+### Electron
+
+```bash
+electron-playwright-cli electron_evaluate "electron => electron.app.getName()"
+electron-playwright-cli electron_evaluate "electron => electron.app.getPath('userData')"
+electron-playwright-cli electron_windows
+```
+
+## Snapshots
+
+After each command, electron-playwright-cli provides a snapshot of the current app state.
+
+```bash
+> electron-playwright-cli snapshot
+### Page
+- Page URL: file:///path/to/index.html
+- Page Title: My Electron App
+### Snapshot
+[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)
+```
+
+You can also take a snapshot on demand using `electron-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.
+
+## Sessions
+
+```bash
+electron-playwright-cli -s=name <cmd>            # run command in named session
+electron-playwright-cli -s=name close            # stop a named session
+electron-playwright-cli -s=name delete-data      # delete user data for named session
+electron-playwright-cli list                     # list all sessions
+electron-playwright-cli close-all                # close all sessions
+electron-playwright-cli kill-all                 # forcefully kill all daemon processes
+```
+
+## Local installation
+
+In some cases you might want to install electron-playwright-cli locally. It requires `playwright` as a peer dependency. If running the globally available `electron-playwright-cli` binary fails, use `npx electron-playwright-cli` to run the commands. For example:
+
+```bash
+npx electron-playwright-cli snapshot
+npx electron-playwright-cli click e1
+```
+
+## Example: Form submission
+
+```bash
+electron-playwright-cli snapshot
+
+electron-playwright-cli fill e1 "user@example.com"
+electron-playwright-cli fill e2 "password123"
+electron-playwright-cli click e3
+electron-playwright-cli snapshot
+electron-playwright-cli close
+```
+
+## Example: Multi-window workflow
+
+```bash
+electron-playwright-cli electron_windows
+electron-playwright-cli tab-select 0
+electron-playwright-cli snapshot
+electron-playwright-cli close
+```
+
+## Example: Debugging with DevTools
+
+```bash
+electron-playwright-cli snapshot
+electron-playwright-cli click e4
+electron-playwright-cli fill e7 "test"
+electron-playwright-cli console
+electron-playwright-cli network
+electron-playwright-cli close
+```
+
+```bash
+electron-playwright-cli tracing-start
+electron-playwright-cli click e4
+electron-playwright-cli fill e7 "test"
+electron-playwright-cli tracing-stop
+electron-playwright-cli close
+```
+
+## Example: Electron main process
+
+```bash
+electron-playwright-cli electron_evaluate "electron => electron.app.getName()"
+electron-playwright-cli electron_evaluate "electron => electron.app.getPath('userData')"
+electron-playwright-cli electron_windows
+```
+
+## Specific tasks
+
+* **Request mocking** [references/request-mocking.md](references/request-mocking.md)
+* **Running Playwright code** [references/running-code.md](references/running-code.md)
+* **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/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
+electron-playwright-cli route "**/*.jpg" --status=404
+
+# Mock with JSON body
+electron-playwright-cli route "**/api/users" --body='[{"id":1,"name":"Alice"}]' --content-type=application/json
+
+# Mock with custom headers
+electron-playwright-cli route "**/api/data" --body='{"ok":true}' --header="X-Custom: value"
+
+# Remove headers from requests
+electron-playwright-cli route "**/*" --remove-header=cookie,authorization
+
+# List active routes
+electron-playwright-cli route-list
+
+# Remove a route or all routes
+electron-playwright-cli unroute "**/*.jpg"
+electron-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
+electron-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
+electron-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
+electron-playwright-cli run-code "async page => {
+  await page.route('**/api/offline', route => route.abort('internetdisconnected'));
+}"
+# Options: connectionrefused, timedout, connectionreset, internetdisconnected
+```
+
+### Delayed Response
+
+```bash
+electron-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' }) });
+  });
+}"
+```