Clean up deprecated fields from stagehand.ts and allow CDP parameterization (#609)

kamath · web-flow · commit c92295d8424d · 2025-03-29T11:59:23.000-07:00
diff --git a/.changeset/shaggy-mails-march.md b/.changeset/shaggy-mails-march.md
@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": minor
+---
+
+Removed deprecated fields and methods from Stagehand constructor and added cdpUrl to localBrowserLaunchOptions for custom CDP URLs support.
diff --git a/evals/deterministic/stagehand.config.ts b/evals/deterministic/stagehand.config.ts
@@ -7,10 +7,12 @@ const StagehandConfig: ConstructorParams = {
   ...DefaultStagehandConfig,
   env: "LOCAL" /* Environment to run Stagehand in */,
   verbose: 1 /* Logging verbosity level (0=quiet, 1=normal, 2=verbose) */,
-  headless: true /* Run browser in headless mode */,
   browserbaseSessionCreateParams: {
     projectId: process.env.BROWSERBASE_PROJECT_ID,
   },
   enableCaching: false /* Enable caching functionality */,
+  localBrowserLaunchOptions: {
+    headless: true /* Run browser in headless mode */,
+  },
 };
 export default StagehandConfig;
diff --git a/evals/deterministic/tests/browserbase/sessions.test.ts b/evals/deterministic/tests/browserbase/sessions.test.ts
@@ -0,0 +1,67 @@
+import { test, expect } from "@playwright/test";
+import { Stagehand } from "@/dist";
+import StagehandConfig from "@/evals/deterministic/stagehand.config";
+import Browserbase from "@browserbasehq/sdk";
+
+test.describe("Browserbase Sessions", () => {
+  let browserbase: Browserbase;
+  let sessionId: string;
+  let bigStagehand: Stagehand;
+
+  test.beforeAll(async () => {
+    browserbase = new Browserbase({
+      apiKey: process.env.BROWSERBASE_API_KEY,
+    });
+    bigStagehand = new Stagehand({
+      ...StagehandConfig,
+      env: "BROWSERBASE",
+      browserbaseSessionCreateParams: {
+        projectId: process.env.BROWSERBASE_PROJECT_ID,
+        keepAlive: true,
+      },
+    });
+    await bigStagehand.init();
+    await bigStagehand.page.goto(
+      "https://docs.stagehand.dev/get_started/introduction",
+    );
+    sessionId = bigStagehand.browserbaseSessionID;
+    if (!sessionId) {
+      throw new Error("Failed to get browserbase session ID");
+    }
+  });
+  test.afterAll(async () => {
+    await bigStagehand.close();
+  });
+  test("resumes a session via sessionId", async () => {
+    const stagehand = new Stagehand({
+      ...StagehandConfig,
+      env: "BROWSERBASE",
+      browserbaseSessionID: sessionId,
+    });
+    await stagehand.init();
+
+    const page = stagehand.page;
+
+    expect(page.url()).toBe(
+      "https://docs.stagehand.dev/get_started/introduction",
+    );
+    await stagehand.close();
+  });
+  test("resumes a session via CDP URL", async () => {
+    const session = await browserbase.sessions.retrieve(sessionId);
+    const stagehand = new Stagehand({
+      ...StagehandConfig,
+      env: "LOCAL",
+      localBrowserLaunchOptions: {
+        headless: true,
+        cdpUrl: session.connectUrl,
+      },
+    });
+    await stagehand.init();
+    const page = stagehand.page;
+
+    expect(page.url()).toBe(
+      "https://docs.stagehand.dev/get_started/introduction",
+    );
+  });
+});
diff --git a/evals/deterministic/tests/local/create.test.ts b/evals/deterministic/tests/local/create.test.ts
@@ -4,21 +4,11 @@ import path from "path";
 import fs from "fs";
 import os from "os";
 import type { Cookie } from "@playwright/test";
+import StagehandConfig from "../../stagehand.config";
 
 test.describe("Local browser launch options", () => {
   test("launches with default options when no localBrowserLaunchOptions provided", async () => {
-    const stagehand = new Stagehand({
-      env: "LOCAL",
-      verbose: 1,
-      headless: true,
-      debugDom: true,
-      domSettleTimeoutMs: 30_000,
-      enableCaching: true,
-      modelName: "gpt-4o",
-      modelClientOptions: {
-        apiKey: process.env.OPENAI_API_KEY,
-      },
-    });
+    const stagehand = new Stagehand(StagehandConfig);
     await stagehand.init();
 
     const context = stagehand.context;
@@ -32,18 +22,10 @@ test.describe("Local browser launch options", () => {
     const customUserDataDir = path.join(os.tmpdir(), "custom-user-data");
 
     const stagehand = new Stagehand({
-      env: "LOCAL",
-      verbose: 1,
-      headless: true,
-      debugDom: true,
-      domSettleTimeoutMs: 30_000,
-      enableCaching: true,
-      modelName: "gpt-4o",
-      modelClientOptions: {
-        apiKey: process.env.OPENAI_API_KEY,
-      },
+      ...StagehandConfig,
       localBrowserLaunchOptions: {
         userDataDir: customUserDataDir,
+        headless: true,
       },
     });
     await stagehand.init();
@@ -60,17 +42,9 @@ test.describe("Local browser launch options", () => {
     const customViewport = { width: 1920, height: 1080 };
 
     const stagehand = new Stagehand({
-      env: "LOCAL",
-      verbose: 1,
-      headless: true,
-      debugDom: true,
-      domSettleTimeoutMs: 30_000,
-      enableCaching: true,
-      modelName: "gpt-4o",
-      modelClientOptions: {
-        apiKey: process.env.OPENAI_API_KEY,
-      },
+      ...StagehandConfig,
       localBrowserLaunchOptions: {
+        ...StagehandConfig.localBrowserLaunchOptions,
         viewport: customViewport,
       },
     });
@@ -99,17 +73,9 @@ test.describe("Local browser launch options", () => {
     ];
 
     const stagehand = new Stagehand({
-      env: "LOCAL",
-      verbose: 1,
-      headless: true,
-      debugDom: true,
-      domSettleTimeoutMs: 30_000,
-      enableCaching: true,
-      modelName: "gpt-4o",
-      modelClientOptions: {
-        apiKey: process.env.OPENAI_API_KEY,
-      },
+      ...StagehandConfig,
       localBrowserLaunchOptions: {
+        ...StagehandConfig.localBrowserLaunchOptions,
         cookies: testCookies,
       },
     });
@@ -133,17 +99,9 @@ test.describe("Local browser launch options", () => {
     };
 
     const stagehand = new Stagehand({
-      env: "LOCAL",
-      verbose: 1,
-      headless: true,
-      debugDom: true,
-      domSettleTimeoutMs: 30_000,
-      enableCaching: true,
-      modelName: "gpt-4o",
-      modelClientOptions: {
-        apiKey: process.env.OPENAI_API_KEY,
-      },
+      ...StagehandConfig,
       localBrowserLaunchOptions: {
+        ...StagehandConfig.localBrowserLaunchOptions,
         geolocation: customGeolocation,
         permissions: ["geolocation"],
       },
@@ -174,17 +132,9 @@ test.describe("Local browser launch options", () => {
 
   test("applies custom timezone and locale", async () => {
     const stagehand = new Stagehand({
-      env: "LOCAL",
-      verbose: 1,
-      headless: true,
-      debugDom: true,
-      domSettleTimeoutMs: 30_000,
-      enableCaching: true,
-      modelName: "gpt-4o",
-      modelClientOptions: {
-        apiKey: process.env.OPENAI_API_KEY,
-      },
+      ...StagehandConfig,
       localBrowserLaunchOptions: {
+        ...StagehandConfig.localBrowserLaunchOptions,
         locale: "ja-JP",
         timezoneId: "Asia/Tokyo",
       },
@@ -210,17 +160,9 @@ test.describe("Local browser launch options", () => {
     fs.mkdirSync(videoDir, { recursive: true });
 
     const stagehand = new Stagehand({
-      env: "LOCAL",
-      verbose: 1,
-      headless: true,
-      debugDom: true,
-      domSettleTimeoutMs: 30_000,
-      enableCaching: true,
-      modelName: "gpt-4o",
-      modelClientOptions: {
-        apiKey: process.env.OPENAI_API_KEY,
-      },
+      ...StagehandConfig,
       localBrowserLaunchOptions: {
+        ...StagehandConfig.localBrowserLaunchOptions,
         recordVideo: {
           dir: videoDir,
           size: { width: 800, height: 600 },
diff --git a/evals/tasks/expect_act_timeout.ts b/evals/tasks/expect_act_timeout.ts
@@ -16,7 +16,6 @@ export const expect_act_timeout: EvalFunction = async ({
   const result = await stagehand.page.act({
     action: "search for 'Stagehand'",
     timeoutMs: 1_000,
-    slowDomBasedAct: true,
   });
 
   await stagehand.close();
diff --git a/evals/tasks/expect_act_timeout_global.ts b/evals/tasks/expect_act_timeout_global.ts
@@ -17,7 +17,7 @@ export const expect_act_timeout_global: EvalFunction = async ({
 
   const result = await stagehand.page.act({
     action: "search for 'Stagehand'",
-    slowDomBasedAct: true,
+    timeoutMs: 1_000,
   });
   console.log("RESULT", result);
 
diff --git a/evals/tasks/extract_zillow.ts b/evals/tasks/extract_zillow.ts
@@ -11,9 +11,6 @@ export const extract_zillow: EvalFunction = async ({
     modelName,
     logger,
     domSettleTimeoutMs: 3000,
-    configOverrides: {
-      debugDom: false,
-    },
   });
 
   const { debugUrl, sessionUrl } = initResponse;
diff --git a/evals/tasks/nextChunk.ts b/evals/tasks/nextChunk.ts
@@ -13,7 +13,6 @@ export const nextChunk: EvalFunction = async ({ modelName, logger }) => {
   await stagehand.page.goto("https://www.apartments.com/san-francisco-ca/");
   await stagehand.page.act({
     action: "click on the all filters button",
-    slowDomBasedAct: false,
   });
 
   const { initialScrollTop, chunkHeight } = await stagehand.page.evaluate(
@@ -36,7 +35,6 @@ export const nextChunk: EvalFunction = async ({ modelName, logger }) => {
 
   await stagehand.page.act({
     action: "scroll down one chunk on the filters modal",
-    slowDomBasedAct: false,
   });
 
   await new Promise((resolve) => setTimeout(resolve, 2000));
diff --git a/evals/tasks/prevChunk.ts b/evals/tasks/prevChunk.ts
@@ -32,7 +32,6 @@ export const prevChunk: EvalFunction = async ({ modelName, logger }) => {
   await new Promise((resolve) => setTimeout(resolve, 2000));
   await stagehand.page.act({
     action: "scroll up one chunk",
-    slowDomBasedAct: false,
   });
 
   await new Promise((resolve) => setTimeout(resolve, 5000));
diff --git a/evals/tasks/scroll_50.ts b/evals/tasks/scroll_50.ts
@@ -12,7 +12,6 @@ export const scroll_50: EvalFunction = async ({ modelName, logger }) => {
   await stagehand.page.goto("https://aigrant.com/");
   await stagehand.page.act({
     action: "Scroll 50% down the page",
-    slowDomBasedAct: false,
   });
 
   await new Promise((resolve) => setTimeout(resolve, 5000));
diff --git a/evals/tasks/scroll_75.ts b/evals/tasks/scroll_75.ts
@@ -12,7 +12,6 @@ export const scroll_75: EvalFunction = async ({ modelName, logger }) => {
   await stagehand.page.goto("https://aigrant.com/");
   await stagehand.page.act({
     action: "Scroll 75% down the page",
-    slowDomBasedAct: false,
   });
 
   await new Promise((resolve) => setTimeout(resolve, 5000));
diff --git a/examples/2048.ts b/examples/2048.ts
@@ -6,7 +6,6 @@ async function example() {
   const stagehand = new Stagehand({
     env: "LOCAL",
     verbose: 1,
-    debugDom: true,
     domSettleTimeoutMs: 100,
   });
   try {
diff --git a/examples/debugUrl.ts b/examples/debugUrl.ts
@@ -4,7 +4,9 @@ async function debug(url: string) {
   const stagehand = new Stagehand({
     env: "LOCAL",
     verbose: 2,
-    debugDom: true,
+    localBrowserLaunchOptions: {
+      headless: true,
+    },
   });
   await stagehand.init();
   await stagehand.page.goto(url);
diff --git a/examples/parameterizeApiKey.ts b/examples/parameterizeApiKey.ts
@@ -15,7 +15,6 @@ async function example() {
   const stagehand = new Stagehand({
     env: "LOCAL",
     verbose: 1,
-    debugDom: true,
     enableCaching: false,
     modelName: "gpt-4o",
     modelClientOptions: {
diff --git a/lib/StagehandPage.ts b/lib/StagehandPage.ts
diff --git a/lib/handlers/actHandler.ts b/lib/handlers/actHandler.ts
diff --git a/lib/index.ts b/lib/index.ts
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
diff --git a/stagehand.config.ts b/stagehand.config.ts
diff --git a/types/stagehand.ts b/types/stagehand.ts
