electron-playwright-cli 0.1.1 → 0.1.2

package/README.md

@@ -32,6 +32,35 @@ Optional launch options:
 - `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.2",
   "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-electron/electron-context-factory.js

@@ -33,13 +33,11 @@ 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", () => {
@@ -57,6 +55,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

@@ -39,6 +39,33 @@ Optional launch options:
 - `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