Storage state persistence broken in Stagehand v3 - userDataDir doesn't work, storageState() method missing

[illia-fliplet]

Storage state persistence broken in Stagehand v3 - userDataDir doesn't work, storageState() method missing

Before submitting an issue, please:

• Check the documentation for relevant information
• Search existing issues to avoid duplicates

Environment Information

Please provide the following information to help us reproduce and resolve your issue:

Stagehand:

• Language/SDK: TypeScript
• Stagehand version: 3.0.1

AI Provider:

• Provider: Google
• Model: gemini-2.5-flash-preview-04-17

Issue Description

Storage state persistence is broken in Stagehand v3. The userDataDir and preserveUserDataDir options in localBrowserLaunchOptions do not persist browser data (cookies, localStorage) as expected. Additionally, the storageState() method is no longer available on the context/page objects, preventing manual extraction of authentication state.

Expected Behavior:

1. When userDataDir is specified, Chrome should create and use that directory to store user data
2. When preserveUserDataDir: true is set, the directory should persist after stagehand.close()
3. The directory should contain Chrome's standard profile structure (e.g., Default subdirectory)
4. When a new Stagehand instance is created with the same userDataDir, it should automatically load the persisted authentication state

Actual Behavior:

1. The userDataDir directory is never created - it doesn't exist after init(), during the session, or after close()
2. Even when manually creating the directory before init(), Chrome does not write any data to it
3. The storageState() method is not available on stagehand.context or page.context(), preventing manual extraction
4. Authentication state cannot be persisted between sessions

Steps to Reproduce

1. Create a Stagehand instance with userDataDir and preserveUserDataDir: true
2. Perform login to establish authentication (cookies are set successfully)
3. Close the Stagehand instance
4. Check if the userDataDir directory exists and contains data

Minimal Reproduction Code

import { Stagehand } from '@browserbasehq/stagehand';
import { join } from 'path';
import { existsSync, readdirSync } from 'fs';

const adminUserDataDir = join(process.cwd(), 'chrome-user-data', 'admin');

const stagehand = new Stagehand({
  env: 'LOCAL',
  verbose: 1,
  localBrowserLaunchOptions: {
    headless: false,
    userDataDir: adminUserDataDir,
    preserveUserDataDir: true
  }
});

await stagehand.init();
const page = stagehand.context.pages()[0];

// Perform login (cookies are set successfully)
await page.goto('https://example.com/login');
// ... login steps ...
// Login succeeds, cookies exist (verified via document.cookie)

console.log(`Directory exists after init: ${existsSync(adminUserDataDir)}`); // false

await stagehand.close();

console.log(`Directory exists after close: ${existsSync(adminUserDataDir)}`); // false

// Even if directory is manually created before init(), it remains empty
if (existsSync(adminUserDataDir)) {
  const files = readdirSync(adminUserDataDir);
  console.log(`Directory contents: ${files.length} items`); // 0 - empty
}

Error Messages / Log trace

No errors are thrown, but the directory is never created:

Directory exists after init: false
Directory exists after close: false

When attempting to use storageState() method:

// Attempt 1: stagehand.context.storageState()
const storageState = await stagehand.context.storageState();
// Error: stagehand.context.storageState is not a function

// Attempt 2: page.context().storageState()
const page = stagehand.context.pages()[0];
const storageState = await page.context().storageState();
// Error: page.context is not a function

Screenshots / Videos

N/A - Issue is about missing functionality rather than visual bugs.

Root Cause Analysis

Issue 1: userDataDir Not Passed to Chrome
The userDataDir option in localBrowserLaunchOptions appears to not be passed correctly to the underlying Chrome browser instance. This could be due to:

• Stagehand v3's new architecture using Chrome DevTools Protocol instead of Playwright
• The option being filtered out or ignored during browser launch
• A bug in how Stagehand v3 handles localBrowserLaunchOptions

Issue 2: storageState() Method Removed
In Stagehand v2, storageState() was available via Playwright's BrowserContext. In Stagehand v3:

• Stagehand removed its internal Playwright dependency
• The context object is no longer a Playwright BrowserContext
• The storageState() method was not re-implemented in Stagehand v3's new architecture

Issue 3: API Changes Not Documented
The migration from v2 to v3 removed critical functionality without:

• Clear documentation of breaking changes
• Migration guide for storage state persistence
• Alternative methods for persisting authentication

Previous Approach (Playwright Browser Context)

Before Stagehand v3, we could use Playwright's native browser context methods:

Method 1: Using storageState() Method

import { chromium } from '@playwright/test';

const browser = await chromium.launch();
const context = await browser.newContext();

// Perform login
const page = await context.newPage();
await page.goto('https://example.com/login');
// ... login steps ...

// Save storage state (cookies + localStorage)
await context.storageState({ path: 'storage-state/admin.json' });

// Later, load storage state
const context2 = await browser.newContext({
  storageState: 'storage-state/admin.json'
});

Method 2: Using launchPersistentContext with userDataDir

import { chromium } from '@playwright/test';

// Launch browser with persistent user data directory
const context = await chromium.launchPersistentContext('./chrome-user-data/admin', {
  headless: false
});

// Login and close - data automatically persisted
await context.close();

// Later, launch with same userDataDir - authentication persists
const context2 = await chromium.launchPersistentContext('./chrome-user-data/admin', {
  headless: false
});

Method 3: Using Stagehand v2 (with Playwright under the hood)

import { Stagehand } from '@browserbasehq/stagehand';

const stagehand = new Stagehand({ env: 'LOCAL' });
await stagehand.init();
await loginAsAdmin(stagehand);

// Access Playwright context and save storage state
const playwrightContext = stagehand.page.context();
await playwrightContext.storageState({ path: 'storage-state/admin.json' });

Key Differences from Stagehand v3:

• ✅ context.storageState() method was available
• ✅ page.context() returned Playwright BrowserContext
• ✅ userDataDir actually worked and persisted data
• ✅ No manual cookie/localStorage extraction needed

Current Workaround

We've implemented a manual workaround that extracts cookies and localStorage manually:

// Extract cookies and localStorage
const cookies = await page.evaluate(() => {
  return document.cookie.split(';').map(cookie => {
    const [name, ...valueParts] = cookie.trim().split('=');
    return { name, value: valueParts.join('=') };
  });
});

const localStorage = await page.evaluate(() => {
  const items = [];
  for (let i = 0; i < window.localStorage.length; i++) {
    const key = window.localStorage.key(i);
    if (key) {
      items.push({ name: key, value: window.localStorage.getItem(key) || '' });
    }
  }
  return items;
});

// Save to JSON file in Playwright storage state format
// Load and apply when creating new browser instances

Limitations of workaround:

• Requires manual extraction code
• May miss HttpOnly cookies (not accessible via document.cookie)
• localStorage must be applied after navigating to the correct origin
• More error-prone than native browser persistence

Impact

• High: Authentication state cannot be persisted between test runs
• High: Tests must re-authenticate on every run, increasing execution time
• Medium: Workarounds require manual cookie/localStorage extraction and application
• Medium: No official way to share authentication state across multiple test files

Proposed Solutions

Option 1: Fix userDataDir Support
Ensure userDataDir and preserveUserDataDir are correctly passed to Chrome and that Chrome actually uses the specified directory.

Option 2: Re-implement storageState() Method
Add a storageState() method to Stagehand v3's context object that extracts and returns cookies/localStorage in Playwright format:

const storageState = await stagehand.context.storageState();
await stagehand.context.storageState({ path: 'storage-state/admin.json' });

Option 3: Provide Official Storage State API
Create a new Stagehand v3 API for persisting and loading authentication state:

// Save storage state
await stagehand.saveStorageState('path/to/storage-state.json');

// Load storage state
const stagehand = new Stagehand({
  env: 'LOCAL',
  storageState: 'path/to/storage-state.json'
});

Related Issues

Are there any related issues or PRs?

• Related to: Stagehand v3 migration (removed Playwright dependency)
• Related to: page.context() is no longer available
• Related to: stagehand.context is not a Playwright BrowserContext

Additional Context

• This issue affects all users migrating from Stagehand v2 to v3
• The workaround is functional but not ideal for production use
• We recommend prioritizing a fix as this is a critical feature for test automation
• Documentation on storage state persistence in v3 is missing

[illia-fliplet]

I have figured out a reliable way to persist authentication state in Stagehand v3. In short: launch via Stagehand, attach Playwright over CDP, perform AI login on the Playwright page, navigate to your app’s primary URL (APP_URL), save pwContext.storageState, and at runtime restore cookies only while starting tests from your app’s login URL (LOGIN_URL).

Resolution

1. Use CDP to attach Playwright to Stagehand’s live browser:
   • const browser = await chromium.connectOverCDP(stagehand.connectURL());
   • const pwContext = browser.contexts()[0];
   • const pwPage = pwContext.pages()[0];
2. Perform login using Stagehand AI, targeting the Playwright page.
3. After login completes, navigate to your app’s primary URL (APP_URL) to ensure all client-side flags (e.g., session and onboarding) are set under the correct origin.
4. Save real Playwright state from the existing context with pwContext.storageState({ path }).
5. At runtime, restore cookies via pwContext.addCookies(...) on the existing context.
6. Begin tests at your app’s login URL (LOGIN_URL) to leverage server-side session cookie redirect logic and reliably land on the post-login screen.

Key code snippets

Attach Playwright to Stagehand’s browser (via CDP):

const browser = await chromium.connectOverCDP(sh.connectURL());
const pwContext = browser.contexts()[0];
const pwPage = pwContext.pages()[0];

Save storage state on the existing context:

async function saveAuthState(stagehand: Stagehand, filename: string): Promise<void> {
  const browser = await chromium.connectOverCDP(stagehand.connectURL());
  const pwContext = browser.contexts()[0];
  await pwContext.storageState({ path: filename });
}

Cookies-only restore at runtime (recommended default):

if (userType) {
  const storageState = JSON.parse(readFileSync(storageStatePath, 'utf8'));
  if (Array.isArray(storageState.cookies) && storageState.cookies.length > 0) {
    await pwContext.addCookies(storageState.cookies);
  }
}

Optional: Hydrate localStorage when your app requires it (use with care)

• Only do this if your application stores session or onboarding flags in localStorage and you cannot rely purely on server-side cookies.
• Scope initialization strictly to the target origin to avoid cross-site leakage.
• Prefer setting localStorage during the auth-state generation phase; if you must set it at runtime, use addInitScript so it runs before app scripts.

// Example: scope localStorage hydration to the app origin before first navigation
const APP_URL = process.env.APP_URL!; // e.g., https://your-app.example.com
const appOrigin = new URL(APP_URL).origin;
const localStorageMap = {
  // Fill with the keys your app requires
  // e.g., 'onboarding_completed': 'true',
  //       'session_client_flag': '{"v":1}'
};

await pwContext.addInitScript(({ origin, kv }) => {
  try {
    if (window.location.origin === origin && kv && typeof kv === 'object') {
      for (const [k, v] of Object.entries(kv)) {
        localStorage.setItem(k, String(v));
      }
    }
  } catch {}
}, { origin: appOrigin, kv: localStorageMap });

// Now navigate; init script runs before the document loads
await pwPage.goto(APP_URL, { waitUntil: 'domcontentloaded' });

Alternatively (less ideal), set after navigation if timing is acceptable:

await pwPage.goto(APP_URL, { waitUntil: 'domcontentloaded' });
await pwPage.evaluate((kv) => {
  for (const [k, v] of Object.entries(kv)) {
    localStorage.setItem(k, String(v));
  }
}, localStorageMap);
await pwPage.reload({ waitUntil: 'domcontentloaded' });

How to use

1. Generate auth states (AI-driven login over CDP, saved via Playwright):
   • npm run auth:regenerate
2. In tests (authenticated flows):
   • Create/attach to the Stagehand browser and restore cookies into the existing Playwright context.
   • Use the Playwright page from that context.
   • Navigate to your app’s login URL (LOGIN_URL); the server session cookie should redirect you to the post-login screen automatically.

Why this works

• CDP ensures Playwright operates on Stagehand’s actual browser and context, making storageState() accurate.
• Avoiding a new Playwright context prevents CDP session mismatch.
• Starting from BASE_LOGIN_URL uses server-side cookies to redirect, while avoiding localStorage side effects in tests.

Request to Stagehand maintainers

• Please document the v3 CDP pattern for saving/loading auth state and note that restoring should happen on the existing context (cookies-only is usually sufficient) rather than by creating a new Playwright context from a state file.

[JerryWu1234]

nice description. I will take a look this BUg