Migrate Playwright to v4

Stagehand v4 drives Chromium over the Chrome DevTools Protocol and has no Playwright dependency, so you can’t hand a Playwright Page to act(). There is no interop; moving a flow to Stagehand means porting it. The deterministic API is familiar but smaller. page.goto(), page.locator(), locator.fill(), and page.screenshot() behave the way you expect, but auto-waiting, getBy* locators, expect(), and route interception don’t exist. In exchange you get act(), extract(), and observe(): natural-language steps that survive the UI changes that break selectors, plus server-side caching that removes inference from a flow once it’s stable.

This guide is TypeScript throughout, because that’s where most Playwright code lives. Stagehand behaves the same way in Python and Go; the SDK reference carries each language’s naming.

What changed

What Stagehand does and doesn’t cover, and what the smallest script looks like on both sides.

Stagehand is not a test framework

Playwright is two things in one install: the library that automates a browser, and @playwright/test, the runner layered on top of it. Stagehand covers the first and has no counterpart to the second, so there are no fixtures, no expect(), no retries, no HTML reporter, no codegen, and no trace viewer. Keep your existing runner if it’s a general one such as Vitest or Jest, and call Stagehand inside it. Tests that depend on @playwright/test fixtures need porting, because those fixtures hand you a Playwright page.

Hello world, side by side

import { chromium } from "playwright";

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

await page.goto("https://example.com");
await page.click("a");
console.log(await page.title());

await browser.close();

import { browserbase, Stagehand } from "@browserbasehq/stagehand";

const browser = await browserbase.launch({
  apiKey: process.env.BROWSERBASE_API_KEY,
});
const stagehand = await Stagehand.create({ browser });

const page = await browser.context.newPage("https://example.com");
await page.locator("a").click();
console.log(await page.title());

await stagehand.close();
await browser.close();

The smallest possible script shows the shape of the port:

A browser factory replaces chromium.launch(), and Stagehand.create() attaches the runtime to it.
There’s one context per browser, reached at browser.context. browser.newContext() has no equivalent.
page.click(selector) is now page.locator(selector).click(). In v4, page.click(x, y) clicks page coordinates.

page.click(), page.hover(), and page.type() all changed meaning. They take coordinates or raw text now, not selectors, so the compiler catches the mistake. Route every selector through page.locator().

Port a script

The order to work in, and a worked example end to end. Most of the work is mechanical, so consider handing it to a coding assistant with the porting rules before doing it by hand.

Recommended migration order

Port one script end to end, keeping selectors exactly as they are. Get it launching, navigating, and closing on v4 first.
Add explicit waits wherever you relied on Playwright’s auto-waiting.
Replace getBy* locators and assertions, which have no direct equivalent.
Swap the selectors that break most often for act() and extract().
Turn on cache once the flow is stable.

A complete port

A Playwright script that opens Hacker News, switches to the newest stories, and reads the top five titles:

import { chromium } from "playwright";

const browser = await chromium.launch();
const page = await browser.newPage();

await page.goto("https://news.ycombinator.com");
await page.getByRole("link", { name: "new" }).click();
await page.waitForLoadState("domcontentloaded");

const titles = await page.locator(".titleline > a").allTextContents();
console.log(titles.slice(0, 5));

await browser.close();

The v4 port keeps the stable selector and spends a model call only where Playwright’s getByRole() did the work:

import { browserbase, Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod/v4";

const browser = await browserbase.launch({ apiKey: process.env.BROWSERBASE_API_KEY });
const stagehand = await Stagehand.create({ browser });

try {
  const page = await browser.context.newPage("https://news.ycombinator.com");

  // getByRole() has no built-in equivalent, and the link has no stable selector.
  await stagehand.act("Click the 'new' link in the top navigation");
  await page.waitForLoadState("domcontentloaded");

  // extract() replaces the allTextContents() loop and returns typed data in one call.
  const { data } = await stagehand.extract(
    "Extract the titles of the first five stories",
    z.object({ titles: z.array(z.string()) }),
  );
  console.log(data.titles);
} finally {
  await stagehand.close();
  await browser.close();
}

API differences

One section per area of the API. Skip to the one you’re porting.

Launching and connecting

chromium.launch() becomes a browser factory, and Stagehand.create() attaches to what the factory returns:

- const browser = await chromium.launch({ headless: false });
+ const browser = await localBrowser.launch({ headless: false });
+ const stagehand = await Stagehand.create({ browser });

localBrowser.launch() accepts the launch and context options you already use: headless, args, executablePath, userDataDir, proxy, locale, viewport, deviceScaleFactor, hasTouch, ignoreHTTPSErrors, downloadsPath, and acceptDownloads. For a hosted browser, use browserbase.launch({ apiKey }). That’s what enables server-side caching and the Model Gateway. To attach to a browser that’s already running, use localBrowser.connect({ cdpUrl }) or browserbase.connect({ apiKey, sessionId }). Close both handles. stagehand.close() releases the Stagehand runtime and leaves the browser running, so call browser.close() yourself. See browser configuration.

Chromium only. Stagehand has no Firefox or WebKit support, and no bundled browser download step. A local run uses the Chrome you already have installed, and a Browserbase run needs nothing installed at all.

Contexts and pages

A Stagehand browser has exactly one context, so there’s no isolation-per-context pattern and no storageState handoff between them. Run separate browsers when you need separate profiles.

- const context = await browser.newContext();
- const page = await context.newPage();
- await page.goto("https://example.com");
+ const page = await browser.context.newPage("https://example.com");

newPage() takes an optional URL, which saves a goto(). The rest of the surface maps closely:

Playwright	Stagehand v4
`context.pages()`	`await browser.context.pages()`
`page.bringToFront()`	`await browser.context.setActivePage(page)`
The page you last used	`await browser.context.activePage()`
`context.addCookies()`, `cookies()`, `clearCookies()`	Same names on `browser.context`
`context.addInitScript()`, `setExtraHTTPHeaders()`	Same names on `browser.context`

act(), extract(), and observe() run against the active page unless you pass one: stagehand.act("...", { page }). See using multiple tabs.

Locators

page.locator() takes CSS, XPath (xpath= or a leading /), or text=. CSS selectors pierce shadow DOM, including closed roots, and >> hops through iframes, so page.locator("iframe#checkout >> button.submit") reaches the button inside the frame. That replaces frameLocator(). The getBy* family has no equivalent. In order of preference: Rewrite as CSS, when the app gives you something stable:

- page.getByTestId("submit")
+ page.locator("[data-testid=submit]")

Use text=, which matches a case-insensitive substring of the element’s text:

- page.getByText("Add to cart")
+ page.locator("text=Add to cart")

Ask a model, when the original describes the target by role or context rather than markup. observe() returns candidate actions with real selectors attached, so you can inspect one, then drive it deterministically:

- await page.getByRole("button", { name: "Add to cart" }).click();
+ const { data: actions } = await stagehand.observe("the add to cart button");
+ await page.locator(actions[0].selector).click();

Passing that action straight to act() replays it with no further inference. See observe use cases. Rebuild it, when you want the original semantics with no model in the loop. Role, accessible name, and label lookups are DOM logic, and Rebuilding the missing APIs implements them. Chaining and filtering are gone: no locator.locator(), filter(), and(), or or(). Write one selector, narrow with observe(), or filter in the page. first() and nth() work; build last() and all() from count():

- const titles = await page.locator(".titleline > a").allTextContents();
+ const links = page.locator(".titleline > a");
+ const count = await links.count();
+ const titles = [];
+ for (let i = 0; i < count; i++) {
+   titles.push(await links.nth(i).innerText());
+ }

For a list you’re going to read anyway, extract() with an array schema replaces that loop and one round trip per row.

Waiting and timeouts

Waiting is where most ported scripts start flaking. Playwright retries every action until the element is attached, visible, stable, and enabled. Stagehand resolves the selector once and throws Could not find an element for the given xPath(s) if it isn’t there yet. Navigation defaults differ, which is easy to miss because nothing errors. Playwright’s goto() waits for load; v4’s waits for domcontentloaded. A script that relied on subresources being ready needs the state spelled out, and waitUntil: "commit" has no equivalent, since v4 accepts load, domcontentloaded, and networkidle only.

- await page.goto(url);                                 // waits for load
+ await page.goto(url, { waitUntil: "load" });          // v4 defaults to domcontentloaded

Wait first, then act:

- await page.locator("#results").click();
+ await page.waitForSelector("#results", { state: "visible" });
+ await page.locator("#results").click();

waitForSelector() returns a boolean rather than an element handle, so branch on it instead of catching. waitForLoadState() and waitForTimeout() work as you’d expect. Actions do scroll their target into view, so scrollIntoViewIfNeeded() has no port. locator.scrollTo(percent) is a different call: it scrolls content inside a scrollable element. A single wait isn’t the same as Playwright’s per-action retry. When a step races a re-render, use the retry loop instead. There are no default-timeout setters. page.setDefaultTimeout() and setDefaultNavigationTimeout() have no equivalent, so pass timeout per call: on goto(), waitForSelector(), waitForLoadState(), and on act(), observe(), and extract(). domSettleTimeoutMs on Stagehand.create() sets how long the runtime waits for the DOM to settle. Event-based waits have no equivalent: no waitForResponse(), waitForRequest(), waitForEvent(), or waitForURL(). page.on() supports "console" only. Poll page.url() for navigation, or wait for something that only exists on the destination page. Where a wait condition is hard to express as a selector, act() absorbs it. The model reads the page when the call runs, so it sees whatever has rendered by then.

Assertions

There’s no expect() and no web-first assertion retry. Combine an explicit wait with your runner’s assertions:

- await expect(page.locator(".cart-count")).toHaveText("1");
+ await page.waitForSelector(".cart-count", { state: "visible" });
+ expect(await page.locator(".cart-count").innerText()).toBe("1");

Locator state reads that survive the port: textContent(), innerText(), innerHtml(), inputValue(), isChecked(), isVisible(), and count(). For getAttribute(), isEnabled(), isEditable(), or a bounding box, drop to page.evaluate(). locator.centroid() gives you the element’s center point. For assertions about what a page says rather than what it contains, extract() with a schema is usually the shorter path:

const { data } = await stagehand.extract(
  "Extract the cart item count and order total",
  z.object({ itemCount: z.number(), total: z.number() }),
);
expect(data.itemCount).toBe(1);

Network, storage, and files

Route interception has no equivalent. page.route(), context.route(), and request mocking don’t exist. The closest control is a domain allowlist or blocklist on the context:

- await context.route("**/analytics/**", (route) => route.abort());
+ await browser.context.setDomainPolicy({ blockedDomains: ["analytics.example.com"] });

storageState() has no equivalent either. Persist auth with the cookie API, or with a Browserbase context for full profile reuse. See user data.

- await context.storageState({ path: "auth.json" });
+ const cookies = await browser.context.cookies();
+ await fs.writeFile("auth.json", JSON.stringify(cookies));

Dialogs have no handler. There’s no page.on("dialog") and no dialog.accept(), so replace those flows by stubbing the dialog functions before the page loads:

- page.on("dialog", (dialog) => dialog.accept());
+ await browser.context.addInitScript(() => {
+   window.confirm = () => true;
+   window.alert = () => undefined;
+ });

locator.setInputFiles() ports directly, and also accepts in-memory payloads. The SDK serializes each file in memory and caps it at 50 MiB. Stagehand configures downloads at launch rather than exposing them as events. Pass acceptDownloads and downloadsPath to localBrowser.launch(), and note that Stagehand requires downloadsPath whenever acceptDownloads is true. Stagehand emits no download event and provides no download.saveAs(), so watch the directory yourself instead of awaiting the download.

Debugging

page.pause(), the Playwright Inspector, the trace viewer, page.video(), and npx playwright codegen are all Playwright test tooling, so none of them come along. On Browserbase, the session inspector gives you live view, a full recording with frame-by-frame playback, and network detail. Locally, logging: { level: "debug" } and locator.highlight() cover most of the gap. stagehand.metrics() reports token usage and inference timing per method. See observability.

Rebuilding the missing APIs

Most of what Playwright gives you and v4 doesn’t is DOM logic: getByRole() reads roles and accessible names, filter() compares text, and auto-waiting is a polling loop. All of that runs in the page, so page.evaluate() plus page.locator() is enough to rebuild it. These are the implementations Browserbase uses for its own agent integrations.

The tag-and-locate pattern

One obstacle shapes every recipe here: page.evaluate() returns JSON, so it can’t hand an element back. Work around it by stamping matches with a temporary attribute inside the page, then addressing them with an ordinary locator. That gives you an escape hatch for any query you can express as JavaScript. Here’s getByRole():

const TAG = "data-sh-tag";

// Tag every element matching a role and accessible name, then return one locator per match.
async function locateByRole(page: Page, role: string, name?: string): Promise<Locator[]> {
  const count = await page.evaluate(
    ({ tag, role, name }) => {
      const normalize = (value: string) => value.replace(/\s+/g, " ").trim().toLowerCase();

      const roleOf = (element: Element) => {
        const explicit = element.getAttribute("role");
        if (explicit) return explicit.trim().split(/\s+/)[0];
        const tagName = element.tagName.toLowerCase();
        if (tagName === "button") return "button";
        if (tagName === "a") return element.hasAttribute("href") ? "link" : undefined;
        if (/^h[1-6]$/.test(tagName)) return "heading";
        if (tagName === "textarea") return "textbox";
        if (tagName === "select") return element.hasAttribute("multiple") ? "listbox" : "combobox";
        if (tagName !== "input") return undefined;
        const type = (element.getAttribute("type") || "text").toLowerCase();
        if (["button", "submit", "reset", "image"].includes(type)) return "button";
        if (["checkbox", "radio"].includes(type)) return type;
        return ["hidden", "file"].includes(type) ? undefined : "textbox";
      };

      const labelOf = (element: Element) => {
        const id = element.getAttribute("id");
        const explicit = id && document.querySelector(`label[for="${id}"]`);
        return explicit?.textContent || element.closest("label")?.textContent || "";
      };

      const nameOf = (element: Element) =>
        element.getAttribute("aria-label") ||
        labelOf(element) ||
        element.getAttribute("alt") ||
        element.textContent ||
        "";

      const isVisible = (element: Element) => {
        const style = getComputedStyle(element);
        if (style.visibility === "hidden" || style.display === "none") return false;
        const rect = element.getBoundingClientRect();
        return rect.width > 0 && rect.height > 0;
      };

      const matches = [...document.querySelectorAll("*")].filter(
        (element) =>
          roleOf(element) === role &&
          isVisible(element) &&
          (name === undefined || normalize(nameOf(element)).includes(normalize(name))),
      );

      matches.forEach((element, index) => element.setAttribute(tag, String(index)));
      return matches.length;
    },
    { tag: TAG, role, name },
  );

  return Array.from({ length: count }, (_, index) => page.locator(`[${TAG}="${index}"]`));
}

// Drop the attributes once you're done with the locators.
async function clearTags(page: Page): Promise<void> {
  await page.evaluate(
    (tag) => document.querySelectorAll(`[${tag}]`).forEach((el) => el.removeAttribute(tag)),
    TAG,
  );
}

const [addToCart] = await locateByRole(page, "button", "Add to cart");
await addToCart.click();
await clearTags(page);

Worth knowing about the pattern:

Tag immediately before you act, and clear afterwards. A tag written before a re-render points at a detached node.
The role map above covers the tags that carry an implicit role in practice. option, list, listitem, table, row, columnheader, cell, navigation, main, form, slider, spinbutton, and searchbox follow the same shape if you need them.
Accessible name precedence is aria-label, then the associated label’s text, then alt on an image, then value on an <input> of type button, submit, or reset, then textContent, then title. The snippet stops at textContent, which covers most targets. Add the rest when a page needs it. Playwright’s name option is a case-insensitive substring match unless you pass exact: true.
document.querySelectorAll() stops at the main document. To reach shadow DOM, recurse through element.shadowRoot, which exposes open roots only. page.locator() pierces both open and closed roots, so prefer a plain selector when the target sits inside one.

getByText and the smallest-match rule

page.locator("text=Add to cart") matches every element whose text contains the string, including wrappers, so it can resolve a <div> around the button rather than the button. Playwright targets the smallest match. That rule is one line: keep an element only when no child also matches.

async function locateByText(page: Page, text: string): Promise<Locator[]> {
  const count = await page.evaluate(
    ({ tag, text }) => {
      const normalize = (value: string) => value.replace(/\s+/g, " ").trim().toLowerCase();
      const target = normalize(text);
      const hasText = (element: Element) => normalize(element.textContent).includes(target);

      const matches = [...document.querySelectorAll("*")].filter(
        (element) => hasText(element) && ![...element.children].some(hasText),
      );

      matches.forEach((element, index) => element.setAttribute(tag, String(index)));
      return matches.length;
    },
    { tag: TAG, text },
  );

  return Array.from({ length: count }, (_, index) => page.locator(`[${TAG}="${index}"]`));
}

filter() and strict mode

filter({ hasText }) is a loop over count() and nth(). Playwright normalizes whitespace and ignores case, so do the same or the port will miss rows:

async function filterByText(locator: Locator, hasText: string): Promise<Locator[]> {
  const normalize = (value: string) => value.replace(/\s+/g, " ").trim().toLowerCase();
  const target = normalize(hasText);
  const total = await locator.count();

  const kept: Locator[] = [];
  for (let index = 0; index < total; index++) {
    const candidate = locator.nth(index);
    if (normalize(await candidate.textContent()).includes(target)) kept.push(candidate);
  }
  return kept;
}

Strict mode is worth rebuilding too, and it’s the difference most likely to hide a bug. Playwright refuses to act when a locator matches more than one element. v4 acts on the first match, so a selector that quietly went ambiguous keeps working on the wrong element:

const submit = page.locator("button.submit");
const matches = await submit.count();
if (matches !== 1) throw new Error(`strict mode violation: ${matches} elements matched`);
await submit.click();

Auto-waiting and retries

Playwright retries an action until the element is actionable, which is why ported scripts flake without explicit waits. The loop is short: poll until the element is present and visible, act, and retry if it detached between the check and the action.

// A re-render between the check and the action produces one of these. Anything
// else is a real failure and must not wait out the deadline.
const RETRYABLE = /detached|not visible|could not find|no element|timed? out/i;

async function actWhenReady(
  page: Page,
  locator: Locator,
  action: (target: Locator) => Promise<void>,
  timeout = 30_000,
): Promise<void> {
  const deadline = Date.now() + timeout;
  let lastError;

  while (Date.now() < deadline) {
    if ((await locator.count()) > 0 && (await locator.isVisible())) {
      try {
        await action(locator);
        return;
      } catch (error) {
        if (!RETRYABLE.test(String(error))) throw error;
        lastError = error;
      }
    }
    await page.waitForTimeout(50);
  }

  // Surface the real failure. A generic timeout would hide which locator broke and why.
  throw lastError ?? new Error(`Timed out after ${timeout}ms waiting for an actionable element`);
}

await actWhenReady(page, page.locator("#checkout"), (target) => target.click());

Both halves of the error handling matter. Without the RETRYABLE test, the loop swallows assertion and logic failures until the deadline, so a genuine bug surfaces 30 seconds later as a timeout. Without lastError, a failure that keeps recurring loses its message and locator detail to the generic timeout. Widen the pattern as you meet new transient messages, and keep rethrowing everything else immediately. The same loop replaces locator.waitFor({ state }) when the query isn’t a selector you can hand to page.waitForSelector(). Read count() for attached and detached, and count() plus isVisible() for visible and hidden.

Don’t wrap act() in a retry loop. A failed act() may already have clicked or submitted before the error surfaced. Retry observe(), which only plans, then pass its action to act() once.

Element reads through evaluate

Locator covers text, value, checked state, visibility, and count. Everything else is a one-line evaluate():

const href = await page.evaluate(
  (selector) => document.querySelector(selector).getAttribute("href"),
  "a.download",
);

const enabled = await page.evaluate(
  (selector) => !document.querySelector(selector).matches(":disabled"),
  "button.submit",
);

const box = await page.evaluate((selector) => {
  const { x, y, width, height } = document.querySelector(selector).getBoundingClientRect();
  return { x, y, width, height };
}, "#banner");

The remaining equivalences

Each of these is a direct substitution:

Playwright	Stagehand v4
`locator.check()`	`if (!(await locator.isChecked())) await locator.click()`
`locator.uncheck()`	`if (await locator.isChecked()) await locator.click()`
`locator.clear()`	`locator.fill("")`
`locator.press(key)`	`await locator.click()`, then `page.keyPress(key)`. Combos such as `"Control+A"` work
`locator.pressSequentially(text)`	`locator.type(text)`
`locator.dblclick()`	`locator.click({ clickCount: 2 })`
`locator.dispatchEvent("click")`	`locator.sendClickEvent()`
`locator.last()`	`locator.nth(await locator.count() - 1)`
`locator.allTextContents()`	`page.evaluate((s) => [...document.querySelectorAll(s)].map((el) => el.textContent), selector)`
`locator.selectOption({ index })`	Read `select.options[index].value` with `evaluate()`, then pass that value
`locator.focus()`, `blur()`	`page.evaluate((s) => document.querySelector(s).focus(), selector)`
`page.content()`	`page.evaluate(() => document.documentElement.outerHTML)`
`page.$eval(selector, fn)`	`page.evaluate()` with the selector as its argument
`page.getByTestId(x)`	`page.locator('[data-testid="x"]')`
`page.getByPlaceholder(x)`	`page.locator('[placeholder*="x"]')`, substring like Playwright’s default
`page.getByAltText(x)`, `getByTitle(x)`	`page.locator('[alt="x"]')`, `page.locator('[title="x"]')`
`page.getByLabel(x)`	Tag with the `label[for]` and wrapping-label lookup from `locateByRole()`
`page.waitForNavigation()`	Poll `page.url()` every 50 ms until it changes
`page.waitForFunction(fn)`	Poll `page.evaluate(fn)` on the same 50 ms loop
`keyboard.press(key)`, `keyboard.type(text)`	`page.keyPress(key)`, `page.type(text)`
`mouse.move(x, y)`, `mouse.click(x, y)`	`page.hover(x, y)`, `page.click(x, y)`
`mouse.wheel(dx, dy)`	`page.scroll(x, y, dx, dy)`
`request.fetch(url)`	`page.evaluate(async (u) => (await fetch(u)).text(), url)`

What doesn’t rebuild this way is anything that needs the network layer rather than the DOM: page.route(), request mocking, waitForResponse(), waitForRequest(), and the request, response, and download page events. The SDK exposes no CDP escape hatch and page.on() carries "console" only, so those stay unported.

What to convert after the port

A one-for-one port gets the script running on v4. Once it’s green, convert the steps that break most often:

Selectors that churn. Marketing pages, third-party checkouts, and A/B tested UI. Replace with act(), and turn on selfHeal so a recorded action re-infers when its selector breaks.
Scraping loops. A count() and nth() loop over rows becomes one extract() call with an array schema, typed and validated.
Flows you run repeatedly. Set cache: true on Stagehand.create(). Browserbase caches act(), observe(), and extract() results keyed on the instruction, page content, and options, so a stable flow stops paying for inference. Read metadata.cache.status to confirm hits.
Chatty stretches of deterministic code. Every SDK call is a round trip to the browser, which a Playwright script full of locator reads will feel. experimentalBatch() runs a callback next to the page so those calls stay local. The callback can’t capture variables from your process, so pass what it needs as input. It’s experimental and can change in patch releases.

Reach for page.locator() everywhere a selector is stable. A model call per step costs latency and money that a CSS selector doesn’t. See cost optimization.

Quick reference

“No equivalent” here means no built-in method. Rebuilding the missing APIs implements most of them in a few lines.

Setup and lifecycle

Playwright	Stagehand v4
`chromium.launch()`	`localBrowser.launch()` or `browserbase.launch({ apiKey })`
`chromium.connectOverCDP(url)`	`localBrowser.connect({ cdpUrl })`
`firefox`, `webkit`	Not supported. Chromium only
`npx playwright install`	Not needed. Local uses installed Chrome
`browser.newContext()`	One context per browser: `browser.context`
`context.newPage()`	`browser.context.newPage()`, optionally with a URL
`browser.close()`	`await stagehand.close()`, then `await browser.close()`

Playwright	Stagehand v4
`page.goto()`, `reload()`, `goBack()`, `goForward()`	Same names
`page.url()`, `page.title()`	Same names, both async
`page.goto()` default `waitUntil`	`"domcontentloaded"`, not Playwright’s `"load"`
`waitUntil: "commit"`	Not supported. `load`, `domcontentloaded`, and `networkidle` only
`page.waitForURL()`	Poll `page.url()`, or wait for a destination selector
`page.setContent()`	No equivalent. Navigate, or build the DOM in `page.evaluate()`
`page.evaluate()`, `addInitScript()`	Same names
`page.$eval()`, `$$eval()`	`page.evaluate()`
`page.setViewportSize()`	Same name, two arguments instead of an object
`page.setExtraHTTPHeaders()`	Same name, also on the context
`page.screenshot()`	Same, returns bytes and honors `path`
`page.pdf()`	No equivalent
`page.accessibility.snapshot()`	`page.snapshot()`, returns a tree plus an XPath map

Locators

Playwright	Stagehand v4
`page.locator(css)`	Same, and it pierces shadow DOM
`page.locator("xpath=...")`	Same, or a leading `/`
`page.locator("text=...")`	Same, matches a case-insensitive substring
`page.getByRole()`, `getByLabel()`	`observe()`, or rebuild the query
`page.getByPlaceholder()`, `getByAltText()`, `getByTitle()`	`page.locator('[placeholder*="..."]')`, and the same for `alt` and `title`
`page.getByText()`	`page.locator("text=...")`, plus the leaf rule
`page.getByTestId()`	`page.locator("[data-testid=...]")`
`locator.locator()`, `filter()`, `and()`, `or()`	One selector, `observe()`, or a count and nth loop
`locator.first()`, `nth()`	Same names
`locator.last()`	`nth(count - 1)`
`locator.all()`, `allTextContents()`	`count()` plus `nth()`, or `extract()`
Strict mode	Not enforced. Assert `count() === 1`
`frameLocator("iframe").locator(x)`	`page.locator("iframe >> x")`
`page.frames()`	No equivalent. Selectors cross frames

Actions

Playwright	Stagehand v4
`page.click(selector)`	`page.locator(selector).click()`. `page.click(x, y)` takes coordinates
`page.fill(selector, value)`	`page.locator(selector).fill(value)`
`page.type(selector, text)`	`page.locator(selector).type(text)`
`locator.click()`, `hover()`, `fill()`, `type()`	Same names
`locator.dblclick()`	`locator.click({ clickCount: 2 })`
`locator.press("Enter")`	`locator.click()`, then `page.keyPress("Enter")`
`locator.check()`, `uncheck()`	`locator.click()`, confirm with `isChecked()`
`locator.clear()`	`locator.fill("")`
`locator.selectOption()`, `setInputFiles()`	Same names
`locator.dragTo()`	`page.dragAndDrop(fromX, fromY, toX, toY)` with `locator.centroid()`
`locator.scrollIntoViewIfNeeded()`	Automatic. `locator.scrollTo()` scrolls within an element
`locator.dispatchEvent("click")`	`locator.sendClickEvent()`
`mouse`, `keyboard`, `touchscreen`	`page.click(x, y)`, `hover()`, `scroll()`, `type()`, `keyPress()`

Waiting and assertions

Playwright	Stagehand v4
Auto-waiting on every action	Not automatic. `page.waitForSelector()`, or a retry loop
`page.waitForSelector()`	Same name, returns a boolean
`page.waitForLoadState()`, `waitForTimeout()`	Same names
`page.setDefaultTimeout()`, `setDefaultNavigationTimeout()`	No equivalent. Pass `timeout` per call
`page.waitForFunction()`	Poll `page.evaluate()`
`page.waitForResponse()`, `waitForRequest()`, `waitForEvent()`	No equivalent
`page.on("request")`, `on("response")`, `on("dialog")`	`page.on("console")` only
`expect(locator).toBeVisible()`	`waitForSelector()`, then your runner’s assertion
`expect(locator).toHaveText()`	`innerText()`, or `extract()` with a schema

Reading state

Playwright	Stagehand v4
`locator.textContent()`, `innerText()`, `inputValue()`, `isChecked()`, `isVisible()`, `count()`	Same names
`locator.innerHTML()`	`locator.innerHtml()`
`locator.getAttribute()`, `isEnabled()`, `isEditable()`	`page.evaluate()`
`locator.boundingBox()`	`locator.centroid()` for the center point

Storage, network, and tooling

Playwright	Stagehand v4
`context.cookies()`, `addCookies()`, `clearCookies()`	Same names on `browser.context`
`context.storageState()`	Cookie API, or a Browserbase context
`page.route()`, `context.route()`, request mocking	No equivalent. `context.setDomainPolicy()` blocks whole domains
`page.on("dialog")`, `dialog.accept()`	Stub `window.confirm` and `window.alert` with `addInitScript()`
`page.waitForEvent("download")`, `download.saveAs()`	No equivalent. Set `acceptDownloads` and `downloadsPath` at launch
`@playwright/test`, fixtures, `expect`	Bring your own runner, such as Vitest or Jest
Trace viewer, `page.video()`, `page.pause()`	Browserbase session recordings and `stagehand.metrics()`
`npx playwright codegen`	A coding assistant with AI rules, or `observe()`

Agent instructions

Most of this guide is a mapping table, so hand it to a coding assistant rather than retyping the rules. The rules below carry the whole mapping, so pair them with the prompt and the assistant has everything the page covers. Set up AI rules first. Without them, assistants fall back on the v2 and v3 patterns in their training data, and on Playwright APIs that v4 doesn’t have.

Kick off the port

Port this Playwright script to Stagehand v4 (@browserbasehq/stagehand).

Apply the porting rules below verbatim; they override anything you remember
about Stagehand. Keep every selector as-is. Where a Playwright API has no
equivalent, comment out the line and add a TODO naming the API instead of
inventing one. List every TODO you left when you're done.

Porting rules

Paste this block into your rules file (AGENTS.md, CLAUDE.md, or .cursor/rules) for the length of the migration. It’s the mapping an assistant gets wrong most often, stated as rules rather than prose:

PORTING PLAYWRIGHT TO STAGEHAND V4

Stagehand v4 has no Playwright interop. Port the code; never pass a Playwright
object to Stagehand. Keep every original selector unless a rule below says
otherwise. Where an API has no equivalent, comment out the original line and
leave a TODO naming it. Do not invent APIs.

SETUP AND LIFECYCLE
- import { browserbase, localBrowser, Stagehand } from "@browserbasehq/stagehand".
- chromium.launch(opts) -> localBrowser.launch(opts), or
  browserbase.launch({ apiKey }) for a hosted browser.
- chromium.connectOverCDP(url) -> localBrowser.connect({ cdpUrl }).
  Existing Browserbase session -> browserbase.connect({ apiKey, sessionId }).
- After launching: const stagehand = await Stagehand.create({ browser }).
- localBrowser.launch() accepts args, executablePath, port, userDataDir,
  preserveUserDataDir, headless, devtools, chromiumSandbox, ignoreDefaultArgs,
  proxy, locale, viewport, deviceScaleFactor, hasTouch, ignoreHTTPSErrors,
  downloadsPath, acceptDownloads, and keepAlive.
- Stagehand.create() accepts model, cache, logging, systemPrompt, selfHeal,
  domSettleTimeoutMs, and apiKey. Stagehand reads no environment variables;
  pass every key explicitly.
- Teardown: await stagehand.close() then await browser.close().
  stagehand.close() leaves the browser running.
- Chromium only. Do not port firefox or webkit projects. No browser download
  step: local runs use installed Chrome.

CONTEXTS AND PAGES
- One context per browser, at browser.context. Never call browser.newContext().
  Separate profiles need separate browsers.
- context.newPage() -> browser.context.newPage(url?), URL optional.
- context.pages() -> await browser.context.pages() (async).
- The current page -> await browser.context.activePage().
- page.bringToFront() -> await browser.context.setActivePage(page).
- context.addCookies, cookies, clearCookies, addInitScript, and
  setExtraHTTPHeaders keep their names on browser.context.
- act(), observe(), and extract() target the active page unless you pass
  { page }: stagehand.act("...", { page }).

RESULT SHAPES
- act(), observe(), and extract() return { data, metadata }. Read .data.
  metadata carries the action id, cache status, and token usage.
- extract() is positional: extract(instruction, schema, options?). With no
  schema it returns { extraction: string }.
- observe() returns Action[] on .data. Each Action has selector, description,
  and optional method and arguments.
- act() accepts a string or an Action. Passing an Action replays it with no
  inference.
- act(), observe(), and extract() accept model, timeout, cache, locator, and
  ignoreLocators. act() and observe() also accept variables, which keeps
  secrets out of the instruction.

SELECTORS
- page.locator() accepts CSS, xpath= or a leading /, css=, and text=.
  It pierces shadow DOM including closed roots. Use >> to hop into an iframe:
  page.locator("iframe#checkout >> button.submit").
- frameLocator("f").locator("x") -> page.locator("f >> x").
  There is no page.frames() and no frame objects.
- getByTestId(x) -> page.locator('[data-testid="x"]').
- getByPlaceholder(x) -> page.locator('[placeholder*="x"]').
  Same shape for getByAltText -> [alt*="x"] and getByTitle -> [title*="x"].
  Use *= because Playwright's default is a substring match.
- getByText(x) -> page.locator("text=x"), which is a case-insensitive
  substring match. WARNING: it also matches wrapper elements, so it can
  resolve a container instead of the leaf. When the port depends on
  Playwright's leaf match, use tagAndLocate below with the leaf rule.
- getByRole and getByLabel have no selector form. Options, in order:
  1. Rewrite as CSS when the markup is stable.
  2. const { data } = await stagehand.observe("<description>"), then
     page.locator(data[0].selector), or hand data[0] to act().
  3. Rebuild with tagAndLocate below.
- No locator.locator(), filter(), and(), or or(). Collapse to one selector,
  or filter with a count() and nth() loop.
- first() and nth() exist. last() is nth(await locator.count() - 1).
  all() and allTextContents() are a count() and nth() loop, or one extract().
- STRICT MODE IS NOT ENFORCED. A locator matching several elements acts on the
  first. Where the original relied on strict mode, assert count() === 1 first.
- Stuck finding a target? Read (await page.snapshot()).formattedTree, which is
  the accessibility tree, and use the paired xpathMap.

TAG AND LOCATE (rebuilding getByRole, getByLabel, and any custom query)
page.evaluate() returns JSON and cannot hand back an element, so run the query
in the page, stamp matches with an attribute, then address them with a locator:

  const TAG = "data-sh-tag";

  // Write the query inline in the callback. Do not build it with new Function()
  // or eval(): that is page-level eval and a strict CSP blocks it.
  async function locateByRole(page, role, name) {
    const count = await page.evaluate(
      ({ tag, role, name }) => {
        const normalize = (v) => v.replace(/\s+/g, " ").trim().toLowerCase();
        const roleOf = (el) => { /* implicit role map, see below */ };
        const nameOf = (el) => { /* accessible name precedence, see below */ };
        const isVisible = (el) => { /* see below */ };

        const matches = [...document.querySelectorAll("*")].filter(
          (el) =>
            roleOf(el) === role &&
            isVisible(el) &&
            (name === undefined || normalize(nameOf(el)).includes(normalize(name))),
        );
        matches.forEach((el, i) => el.setAttribute(tag, String(i)));
        return matches.length;
      },
      { tag: TAG, role, name },
    );
    return Array.from({ length: count }, (_, i) => page.locator(`[${TAG}="${i}"]`));
  }

  async function clearTags(page) {
    await page.evaluate(
      (tag) => document.querySelectorAll(`[${tag}]`).forEach((el) => el.removeAttribute(tag)),
      TAG,
    );
  }

Rules for it:
- page.evaluate() serializes the callback and JSON-stringifies its argument, so
  the callback captures nothing from the calling scope. Pass everything it needs
  as the second argument, and return only JSON.
- Write one helper per query shape (role, label, leaf text) on this pattern.
- Tag immediately before acting and clear afterwards. A tag written before a
  re-render points at a detached node.
- Implicit roles: button->button, a[href]->link, h1-h6->heading,
  textarea->textbox, select->combobox (listbox when multiple), input by type
  (button/submit/reset/image->button, checkbox, radio, range->slider,
  number->spinbutton, search->searchbox, otherwise textbox). An explicit
  role attribute wins.
- Accessible name precedence: aria-label, then associated label text
  (aria-labelledby ids, then label[for=id], then a wrapping label), then alt,
  then value on an <input> of type button, submit, or reset, then textContent,
  then title. Playwright's name
  option is a case-insensitive substring unless exact: true.
- Normalize text before comparing: value.replace(/\s+/g, " ").trim() and
  lowercase, matching Playwright.
- Leaf rule for text queries: keep an element only when no child also matches.
- Visibility: getComputedStyle display and visibility, plus a
  getBoundingClientRect with non-zero width and height.
- document.querySelectorAll() stops at the main document. Recurse
  element.shadowRoot for open roots. Closed roots are unreachable from
  evaluate(), so use page.locator() for those.

ACTIONS
- page.click(selector) -> page.locator(selector).click().
  page.click(x, y) takes COORDINATES. Same for page.hover(x, y).
  page.type(text) types at the focused element. Never pass a selector to these.
- Locator has click, hover, fill, type, selectOption, setInputFiles, scrollTo,
  centroid, highlight, sendClickEvent, count, isChecked, isVisible, innerText,
  innerHtml, textContent, inputValue, first, and nth.
- locator.press(key) -> await locator.click() then page.keyPress(key).
  Combos work: page.keyPress("Control+A").
- locator.pressSequentially(text) -> locator.type(text).
- locator.check() -> if (!(await locator.isChecked())) await locator.click().
  locator.uncheck() is the same with the condition inverted.
- locator.clear() -> locator.fill("").
- locator.dblclick() -> locator.click({ clickCount: 2 }).
- locator.dispatchEvent("click") -> locator.sendClickEvent().
- locator.dragTo(target) -> page.dragAndDrop(fromX, fromY, toX, toY) using
  coordinates from locator.centroid().
- locator.scrollIntoViewIfNeeded() -> drop it. Actions scroll their target
  into view. locator.scrollTo(percent) is unrelated: it scrolls content
  inside a scrollable element.
- locator.selectOption({ index }) -> read select.options[index].value with
  evaluate(), then pass that value.
- locator.setInputFiles() keeps its name and also takes in-memory payloads
  ({ name, mimeType, buffer }). Cap is 50 MiB per file.
- keyboard.press/type -> page.keyPress/page.type.
  mouse.move/click -> page.hover(x, y)/page.click(x, y).
  mouse.wheel(dx, dy) -> page.scroll(x, y, dx, dy).

NAVIGATION AND WAITING
- goto, reload, goBack, and goForward keep their names and return the main
  document Response or null.
- DEFAULT LOAD STATE DIFFERS. Playwright goto() waits for "load"; v4 waits for
  "domcontentloaded". Pass { waitUntil: "load" } where the original relied on
  subresources. Valid states: load, domcontentloaded, networkidle.
  waitUntil: "commit" does not exist.
- page.url() and page.title() are async. Await them.
- NOTHING AUTO-WAITS. Stagehand resolves a selector once and throws
  "Could not find an element for the given xPath(s)". Before acting on or
  reading an element that may not be present, call
  await page.waitForSelector(selector, { state: "visible" }).
  It returns a boolean, not an element handle.
- One wait is not Playwright's per-action retry. For a step that races a
  re-render, wrap it:

  const RETRYABLE = /detached|not visible|could not find|no element|timed? out/i;

  async function actWhenReady(page, locator, action, timeout = 30_000) {
    const deadline = Date.now() + timeout;
    let lastError;
    while (Date.now() < deadline) {
      if ((await locator.count()) > 0 && (await locator.isVisible())) {
        try { await action(locator); return; }
        catch (error) {
          if (!RETRYABLE.test(String(error))) throw error;
          lastError = error;
        }
      }
      await page.waitForTimeout(50);
    }
    throw lastError ?? new Error(`Timed out after ${timeout}ms waiting for an actionable element`);
  }

  Both guards are required. Without RETRYABLE, the loop swallows assertion and
  logic failures until the deadline, turning a real bug into a timeout. Without
  lastError, a recurring failure loses its message to the generic timeout.
  NEVER retry act(): a failed act() may already have clicked or submitted.
  Retry observe() instead, then pass its Action to act() once.
- locator.waitFor({ state }) -> the same loop. count() for attached and
  detached; count() plus isVisible() for visible and hidden.
- page.waitForFunction(fn) -> poll page.evaluate(fn) on that loop.
- page.waitForNavigation() -> poll page.url() until it changes.
- page.waitForURL() -> poll page.url(), or wait for a selector that exists
  only on the destination.
- No waitForResponse, waitForRequest, or waitForEvent. page.on() supports
  "console" only: no request, response, requestfailed, download, dialog,
  popup, or pageerror events, and no CDP escape hatch.
- No setDefaultTimeout or setDefaultNavigationTimeout. Pass timeout per call.
  waitForLoadState takes it positionally: waitForLoadState(state, timeout).
  domSettleTimeoutMs on Stagehand.create() covers DOM settling.

ASSERTIONS AND READING STATE
- expect() does not exist, and neither does assertion retry. Read state, then
  assert with the runner already in the project (Vitest, Jest).
- Available directly: textContent, innerText, innerHtml (note the casing),
  inputValue, isChecked, isVisible, count.
- Via page.evaluate(): getAttribute, isEnabled and isDisabled
  (element.matches(":disabled")), isEditable, allTextContents
  ([...document.querySelectorAll(s)].map((el) => el.textContent)),
  focus, blur, page.content() (document.documentElement.outerHTML),
  and $eval / $$eval.
- locator.boundingBox() -> locator.centroid() for the center point, or
  getBoundingClientRect() inside evaluate() for the full box.
- When the assertion is about page content rather than DOM structure, prefer
  extract() with a schema and assert on the typed result.

NETWORK, STORAGE, AND FILES
- No page.route(), context.route(), or request mocking. The nearest control is
  await browser.context.setDomainPolicy({ allowedDomains, blockedDomains }).
- No context.storageState(). Persist auth with browser.context.cookies() and
  addCookies(), or a Browserbase context for full profile reuse.
- request.fetch(url) -> page.evaluate(async (u) => (await fetch(u)).text(), url).
- page.on("dialog") -> stub the dialog functions before load:
  await browser.context.addInitScript(() => { window.confirm = () => true; });
- Downloads are launch-time only: acceptDownloads plus downloadsPath on
  localBrowser.launch(), and downloadsPath is required when acceptDownloads is
  true. There is no download event and no download.saveAs().
- page.setViewportSize(width, height) takes two arguments, not an object.
- page.screenshot(options?) keeps its name and returns bytes (Uint8Array).
  fullPage, clip, mask, maskColor, omitBackground, type, quality, scale, style,
  animations, caret, path, and timeout are all supported.
- page.accessibility.snapshot() -> page.snapshot(), which returns
  formattedTree, xpathMap, and urlMap.
- No page.pdf(), page.setContent(), page.pause(), tracing, or video. For
  page.setContent(), navigate to a real URL or build the DOM in evaluate().

WHAT TO USE INSTEAD OF SELECTORS
- Prefer page.locator() wherever a selector is stable. A model call per step
  costs latency and money that a CSS selector does not.
- Replace the steps that break most often with act(), and set selfHeal: true so
  a recorded action re-infers when its selector breaks.
- Replace a count()/nth() scraping loop with one extract() call and an array
  schema.
- Set cache: true on Stagehand.create() once a flow is stable, then check
  metadata.cache.status for HIT.
- For long stretches of deterministic calls, stagehand.experimentalBatch()
  runs a callback next to the page and avoids a round trip per call. The
  callback cannot capture outer variables; pass them as input. It is
  experimental.

DEBUGGING WHAT YOU PORTED
- logging: { level: "debug" } on Stagehand.create(), locator.highlight() to see
  what a selector resolved to, and await stagehand.metrics() for token usage
  and inference timing.
- On Browserbase, the session inspector replaces the trace viewer: live view,
  recording, and network detail.

Troubleshooting

Could not find an element for the given xPath(s). The element wasn’t in the DOM when the locator resolved. Stagehand doesn’t auto-wait, so add page.waitForSelector() before the action. page.click() clicks the wrong thing, or nothing. You passed a selector to the coordinate API. Use page.locator(selector).click(). Property 'getByRole' does not exist on type 'Page'. The getBy* family has no equivalent. Rewrite as CSS, use text=, or resolve the element with observe(). A Playwright page won’t type-check as act()’s page option. v4 has no page interop, so that option only accepts a page from browser.context. Property 'length' does not exist on an observe() result. Every primitive returns { data, metadata }. Read .data. Assertions pass locally and fail in CI. Playwright’s assertion retry is gone. An innerText() read that follows a click needs a waitForSelector() between them. Your generated script uses Playwright APIs on a Stagehand page. The assistant is pattern-matching on Playwright in its training data. Install the rule files from AI rules.

Next steps

Page reference

The full deterministic surface

Observe

Get real selectors from a description

Extract

Replace scraping loops with typed data

Caching

Cut inference out of a stable flow

​What changed

​Stagehand is not a test framework

​Hello world, side by side

​Port a script

​Recommended migration order

​A complete port

​API differences

​Launching and connecting

​Contexts and pages

​Locators

​Waiting and timeouts

​Assertions

​Network, storage, and files

​Debugging

​Rebuilding the missing APIs

​The tag-and-locate pattern

​getByText and the smallest-match rule

​filter() and strict mode

​Auto-waiting and retries

​Element reads through evaluate

​The remaining equivalences

​What to convert after the port

​Quick reference

​Setup and lifecycle

​Navigation and page state

​Locators

​Actions

​Waiting and assertions

​Reading state

​Storage, network, and tooling

​Agent instructions

​Kick off the port

​Porting rules

​Troubleshooting

​Next steps

Page reference

Observe

Extract

Caching

What changed

Stagehand is not a test framework

Hello world, side by side

Port a script

Recommended migration order

A complete port

API differences

Launching and connecting

Contexts and pages

Locators

Waiting and timeouts

Assertions

Network, storage, and files

Debugging

Rebuilding the missing APIs

The tag-and-locate pattern

getByText and the smallest-match rule

filter() and strict mode

Auto-waiting and retries

Element reads through evaluate

The remaining equivalences

What to convert after the port

Quick reference

Setup and lifecycle

Navigation and page state

Locators

Actions

Waiting and assertions

Reading state

Storage, network, and tooling

Agent instructions

Kick off the port

Porting rules

Troubleshooting

Next steps