stably 4.12.15 → 4.12.16

package/dist/stably-browser.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-// ../../app/node_modules/.pnpm/@stablyai-internal+playwright-cli@0.4.29/node_modules/@stablyai-internal/playwright-cli/playwright-cli.js
+// ../../app/node_modules/.pnpm/@stablyai-internal+playwright-cli@0.4.30/node_modules/@stablyai-internal/playwright-cli/playwright-cli.js
 var fs = require("fs");
 var path = require("path");
 if (process.platform === "darwin" && !process.env.PLAYWRIGHT_DAEMON_SOCKETS_DIR) {
@@ -405,9 +405,14 @@ const test = realPw.test.extend({
     // No close \u2014 preserve state for post-test inspection
   },
 
-  // Test-scoped: reuse the existing page from the daemon's context.
-  // Applies project options and baseURL wrapper after acquiring the page.
+  // Test-scoped: create a fresh page for each test to avoid stale CDP frame references.
+  // The previous test's page is closed to free resources. The new page gets a fresh
+  // CDP frame, avoiding the "second test always fails" issue where the reused page's
+  // internal frame reference becomes invalid between fixture teardown/setup cycles.
   page: async ({ context, browser, playwright, baseURL, extraHTTPHeaders, httpCredentials, geolocation, permissions, offline }, use, testInfo) => {
+    // Get or create a page. We reuse the existing page (don't close it \u2014 closing
+    // the last page on a CDP default context can terminate the browser process).
+    // Instead, navigate to about:blank to reset frame state.
     let page = context.pages()[0];
     if (!page) {
       try {
@@ -419,11 +424,24 @@ const test = realPw.test.extend({
         page = ctx.pages()[0] || await ctx.newPage();
       }
     }
+    // Navigate to about:blank to get a fresh frame/document, avoiding stale
+    // frame references from the previous test. This is cheaper than closing
+    // and recreating the page (which can kill the CDP browser).
+    try {
+      await page.goto('about:blank', { timeout: 5000 });
+    } catch {
+      // If navigation fails, the page might be stale \u2014 create a new one
+      try {
+        page = await context.newPage();
+      } catch (error) {
+        if (!isRecoverableCdpError(error)) throw error;
+        const freshBrowser = await reconnectBrowser(playwright);
+        const ctx = freshBrowser.contexts()[0] || await freshBrowser.newContext();
+        page = ctx.pages()[0] || await ctx.newPage();
+      }
+    }
 
     // Apply project options to the reused context.
-    // Navigate to about:blank first to ensure CDP emulation options (timezone, colorScheme)
-    // take effect before the test loads any content.
-    await page.goto('about:blank').catch(() => {});
     await applyContextOptions(context, page, testInfo, {
       extraHTTPHeaders, httpCredentials, geolocation, permissions, offline,
     });

package/dist/stably-plugin-cli/skills/stably-browser/SKILL.md

@@ -231,16 +231,13 @@ stably-browser run-test --help
 - Overrides `browser`/`context`/`page` fixtures to connect via CDP (no new browser launched)
 - Preserves browser state after the run (pages remain open for inspection)
 
-### Running Multiple Tests Sequentially (Verification)
+### Running Multiple Tests — Sequential vs Parallel
 
-**CRITICAL:** When verifying that multiple independent tests pass, you **MUST close and reopen the browser** between each `run-test` call. Browser state (cookies, localStorage, auth sessions) persists between runs, and stale state from one test will contaminate the next.
-
-This applies when you are running separate test files to check they pass — not when intentionally using `run-test` as a setup/seed mechanism (see "Use run-test as a Setup/Seed Mechanism" above).
-
-**IMPORTANT: `stably-browser close` must be its own separate Bash call.** Do NOT chain it with other commands (e.g., `stably-browser close; stably-browser run-test ...`). The browser is only fully terminated after the Bash command finishes, so chaining means the next command runs on the old browser with stale state.
+When verifying that multiple independent tests pass, each test needs its own clean browser state. Two approaches:
 
+**Option A: Sequential (close/reopen between each)**
 ```bash
-# CORRECT: Each command is a separate Bash call
+# Each test gets a fresh browser via close/reopen
 stably-browser run-test tests/login.spec.ts
 stably-browser close
 stably-browser run-test tests/checkout.spec.ts
@@ -248,17 +245,30 @@ stably-browser close
 stably-browser run-test tests/settings.spec.ts
 ```
 
+**Option B: Parallel (different browser sessions, run_in_background)**
+```bash
+# Start tests in parallel on separate browsers (each has clean state)
+stably-browser run-test tests/login.spec.ts              # run_in_background: true
+stably-browser -s=browser-2 run-test tests/checkout.spec.ts  # run_in_background: true
+stably-browser -s=browser-3 run-test tests/settings.spec.ts  # run_in_background: true
+# Poll results with TaskOutput (block: true)
+```
+
+**Rules:**
+- Only use `run_in_background` when running multiple tests in parallel — for single tests, run in foreground
+- Each parallel test MUST target a different browser session (`-s=<name>`)
+- Do NOT run multiple tests on the same browser simultaneously
+- **`stably-browser close` must be its own separate Bash call** — do NOT chain with other commands
+
 ```bash
 # WRONG: Chaining close with run-test in one command
 stably-browser close; stably-browser run-test tests/checkout.spec.ts  # ← run-test hits old browser
-stably-browser close && stably-browser run-test tests/settings.spec.ts  # ← same problem
 ```
 
 ```bash
-# WRONG: Running independent tests without resetting — causes cascading failures
+# WRONG: Running independent tests on the SAME browser without resetting
 stably-browser run-test tests/login.spec.ts
-stably-browser run-test tests/checkout.spec.ts   # ← may fail: browser still has login state from test 1
-stably-browser run-test tests/settings.spec.ts   # ← may fail: stale cookies/auth from previous tests
+stably-browser run-test tests/checkout.spec.ts   # ← may fail: stale state from test 1
 ```
 
 **Why this matters:** The browser is a cloud VM that persists across commands. `stably-browser close` terminates it, but only after the Bash call returns. If you chain `close; run-test`, the test runs on the old browser before it's terminated. Running `close` as its own Bash call ensures the old browser is fully gone before the next test starts with a fresh one.
@@ -280,13 +290,20 @@ stably-browser run-test tests/settings.spec.ts   # ← may fail: stale cookies/a
 
 ## Browser Session Policy
 
-Your environment may enforce a single-session browser policy. When active:
+Your environment may enforce a single-session or multi-session browser policy. **Check the system prompt for which policy is active.**
+
+When **single-session** policy is active:
 - Always use the default session — do not use `-s=<name>`.
 - Close the current browser before opening a new one.
 - If the user asks to "open a new browser", close the existing one first.
-- Do not use `stably-browser list` — there is at most one session.
 
-When multi-session is allowed, you may use named sessions as documented below.
+When **multi-session** policy is active (up to 5 concurrent browsers):
+- Use the default session (no `-s=` flag) for single-browser workflows
+- Open additional named browsers with `-s=<name>` (e.g., `stably-browser -s=browser-2 open https://bing.com`)
+- Run commands on a specific browser by prefixing with `-s=<name>` (e.g., `stably-browser -s=browser-2 click e5`)
+- Each named session is fully independent (cookies, state, tabs)
+- Do NOT mix commands for different sessions in one Bash call — use separate calls
+- The `-s=<name>` flag must come before the subcommand
 
 ## Browser Sessions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stably",
-  "version": "4.12.15",
+  "version": "4.12.16",
   "packageManager": "pnpm@10.24.0",
   "description": "AI-powered E2E Playwright testing CLI. Stably can understand your codebase, edit/run tests, and handle complex test scenarios for you.",
   "main": "dist/index.mjs",
@@ -87,7 +87,7 @@
     "playwright": "1.59.0-alpha-1771104257000",
     "@stablyai/codegen-agent-constants": "workspace:*",
     "@stablyai-internal/api-client": "workspace:*",
-    "@stablyai-internal/playwright-cli": "0.4.29",
+    "@stablyai-internal/playwright-cli": "0.4.30",
     "@stablyai-internal/pwtrace": "0.3.1",
     "@stablyai/agent-hooks": "workspace:*",
     "@stablyai/agent-schemas": "workspace:*",