electron-playwright-cli 0.1.1 → 0.1.3

package/README.md

@@ -26,12 +26,43 @@ Create `.playwright/cli.config.json` in your project root:
 
 The `args` array is passed to Electron. Point it at your app's main process entry point.
 
+The daemon shuts down automatically when the Electron app closes (via `close` or the app exiting on its own). The next command spawns a fresh daemon that reads the current config from disk, so config changes take effect immediately — no need to manually kill the daemon.
+
 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
 
+### App readiness
+
+By default, the CLI waits for the `load` event and a paint frame before accepting commands. For apps with async rendering (React, etc.), the first screenshot may still capture a blank page. Use `readyCondition` to tell the CLI when your app is actually ready:
+
+```json
+{
+  "browser": {
+    "launchOptions": {
+      "args": ["main.js"]
+    },
+    "readyCondition": {
+      "waitForSelector": "[data-testid='app-ready']",
+      "timeout": 10000
+    }
+  }
+}
+```
+
+Available options (all optional, can be combined):
+
+| Option | Type | Description |
+|---|---|---|
+| `waitForSelector` | CSS selector | Waits for the element to be visible |
+| `waitForFunction` | JS expression | Waits for the expression to return truthy (e.g. `"document.fonts.ready"`) |
+| `waitForLoadState` | `"load"` \| `"domcontentloaded"` \| `"networkidle"` | Waits for the specified load state |
+| `timeout` | number (ms) | Timeout for all conditions (default: 10000) |
+
+A double `requestAnimationFrame` paint wait always runs after any conditions, ensuring pixels are rendered before the first command.
+
 ## Usage
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "electron-playwright-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Playwright CLI with Electron app support",
   "keywords": [
     "playwright",
@@ -26,7 +26,7 @@
   },
   "license": "Apache-2.0",
   "scripts": {
-    "check": "npm run fmt:check && npm run lint && npm run typecheck",
+    "check": "npm run fmt && npm run lint && npm run typecheck",
     "fmt": "oxfmt .",
     "fmt:check": "oxfmt --check .",
     "lint": "oxlint .",

package/playwright-cli.js

@@ -128,8 +128,10 @@ async function connectToSocket(socketPath) {
 async function connectToDaemon(sessionName) {
   const socketPath = daemonSocketPath(sessionName);
 
-  // try to connect to existing daemon
-  if (await socketExists(socketPath)) {
+  // try to connect to existing daemon.
+  // on Windows, named pipes aren't detected by stat().isSocket(),
+  // so we always attempt a direct connection.
+  if (os.platform() === "win32" || (await socketExists(socketPath))) {
     try {
       const socket = await connectToSocket(socketPath);
       return new SocketSession(socket);
@@ -203,7 +205,7 @@ async function main() {
   const args = require("minimist")(argv);
 
   if (args.version || args.v) {
-    const pkg = require("playwright/package.json");
+    const pkg = require("./package.json");
     console.log(pkg.version);
     process.exit(0);
   }

package/playwright-electron/electron-context-factory.js

@@ -33,23 +33,22 @@ class ElectronContextFactory {
         await electronApp.firstWindow();
       }
 
-      // wait for the page to finish loading before handing it off —
+      // wait for the page to be ready before handing it off —
       // without this, screenshots taken immediately can capture a blank page
       const firstPage = browserContext.pages()[0];
       if (firstPage) {
-        await firstPage
-          .waitForLoadState("domcontentloaded", { timeout: 10000 })
-          .catch(() => {});
+        await this._waitForReady(firstPage);
       }
 
       electronApp.process().on("exit", () => {
-        setTimeout(() => process.exit(0), 1000);
+        setTimeout(() => process.exit(0), 500);
       });
 
       return {
         browserContext,
         close: async () => {
           await electronApp.close().catch(() => {});
+          setTimeout(() => process.exit(0), 500);
         },
       };
     } catch (e) {
@@ -57,6 +56,57 @@ class ElectronContextFactory {
       throw e;
     }
   }
+
+  // waits for the app to be ready using either user-provided conditions
+  // from config.browser.readyCondition, or a sensible default.
+  //
+  // config example:
+  //   "readyCondition": {
+  //     "waitForLoadState": "load",
+  //     "waitForSelector": "[data-testid='app-ready']",
+  //     "waitForFunction": "document.fonts.ready",
+  //     "timeout": 10000
+  //   }
+  async _waitForReady(page) {
+    const ready = this.config.browser?.readyCondition ?? {};
+    const timeout = ready.timeout ?? 10000;
+
+    // if user provided custom conditions, use those
+    if (
+      ready.waitForLoadState ||
+      ready.waitForSelector ||
+      ready.waitForFunction
+    ) {
+      if (ready.waitForLoadState) {
+        await page
+          .waitForLoadState(ready.waitForLoadState, { timeout })
+          .catch(() => {});
+      }
+      if (ready.waitForSelector) {
+        await page
+          .waitForSelector(ready.waitForSelector, { state: "visible", timeout })
+          .catch(() => {});
+      }
+      if (ready.waitForFunction) {
+        await page
+          .waitForFunction(ready.waitForFunction, null, { timeout })
+          .catch(() => {});
+      }
+    } else {
+      // default: wait for load event (all resources loaded)
+      await page.waitForLoadState("load", { timeout }).catch(() => {});
+    }
+
+    // always wait for at least one paint frame to ensure pixels are rendered
+    await page
+      .evaluate(
+        () =>
+          new Promise((resolve) =>
+            requestAnimationFrame(() => requestAnimationFrame(resolve)),
+          ),
+      )
+      .catch(() => {});
+  }
 }
 
 module.exports = { ElectronContextFactory };

package/skills/playwright-cli/SKILL.md

@@ -33,12 +33,41 @@ Create `.playwright/cli.config.json` in your project root:
 
 The `args` array is passed to Electron. Point it at your app's main process entry point.
 
+The daemon shuts down automatically when the Electron app closes (via `close` or the app exiting on its own). The next command spawns a fresh daemon that reads the current config from disk, so config changes take effect immediately — no need to manually kill the daemon.
+
 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
 
+### App readiness
+
+By default, the CLI waits for the `load` event and a paint frame before accepting commands. For apps with async rendering (React, etc.), use `readyCondition` to tell the CLI when your app is actually ready:
+
+```json
+{
+  "browser": {
+    "launchOptions": {
+      "args": ["main.js"]
+    },
+    "readyCondition": {
+      "waitForSelector": "[data-testid='app-ready']",
+      "timeout": 10000
+    }
+  }
+}
+```
+
+Available options (all optional, can be combined):
+
+| Option | Type | Description |
+|---|---|---|
+| `waitForSelector` | CSS selector | Waits for the element to be visible |
+| `waitForFunction` | JS expression | Waits for the expression to return truthy (e.g. `"document.fonts.ready"`) |
+| `waitForLoadState` | `"load"` \| `"domcontentloaded"` \| `"networkidle"` | Waits for the specified load state |
+| `timeout` | number (ms) | Timeout for all conditions (default: 10000) |
+
 ## Commands
 
 ### Core