"@browserbasehq/stagehand": patch

add support for page.addInitScript()

import { test, expect } from "@playwright/test";

import { V3 } from "../v3";

import { v3TestConfig } from "./v3.config";

import { V3Context } from "../understudy/context";

const EXAMPLE_URL = "https://example.com";

test.describe("page.addInitScript", () => {

let v3: V3;

let ctx: V3Context;

test.beforeEach(async () => {

v3 = new V3(v3TestConfig);

await v3.init();

ctx = v3.context;

});

test.afterEach(async () => {

await v3?.close?.().catch(() => {});

});

test("runs scripts on real network navigations", async () => {

const page = await ctx.awaitActivePage();

await page.addInitScript(() => {

(window as unknown as { __fromPageInit?: string }).__fromPageInit =

"page-level";

});

await page.goto(EXAMPLE_URL, { waitUntil: "domcontentloaded" });

const observed = await page.evaluate(() => {

return (window as unknown as { __fromPageInit?: string }).__fromPageInit;

});

expect(observed).toBe("page-level");

});

test("scopes scripts to the page only", async () => {

const first = await ctx.awaitActivePage();

await first.addInitScript(() => {

function markScope(): void {

const root = document.documentElement;

if (!root) return;

root.dataset.scopeWitness = "page-one";

}

if (document.readyState === "loading") {

document.addEventListener("DOMContentLoaded", markScope, {

once: true,

});

} else {

markScope();

}

});

await first.goto(`${EXAMPLE_URL}/?page=one`, {

waitUntil: "domcontentloaded",

});

const second = await ctx.newPage();

await second.goto(`${EXAMPLE_URL}/?page=two`, {

waitUntil: "domcontentloaded",

});

const firstValue = await first.evaluate(() => {

return document.documentElement.dataset.scopeWitness ?? "missing";

});

const secondValue = await second.evaluate(() => {

return document.documentElement.dataset.scopeWitness ?? "missing";

});

expect(firstValue).toBe("page-one");

expect(secondValue).toBe("missing");

});

test("supports passing arguments to function sources", async () => {

const page = await ctx.awaitActivePage();

const payload = { greeting: "hi", nested: { count: 1 } };

await page.addInitScript((arg) => {

function setPayload(): void {

const root = document.documentElement;

if (!root) return;

root.dataset.pageInitPayload = JSON.stringify(arg);

}

if (document.readyState === "loading") {

document.addEventListener("DOMContentLoaded", setPayload, {

once: true,

});

} else {

setPayload();

}

}, payload);

await page.goto(`${EXAMPLE_URL}/?page=payload`, {

waitUntil: "domcontentloaded",

});

const observed = await page.evaluate(() => {

const raw = document.documentElement.dataset.pageInitPayload;

return raw ? JSON.parse(raw) : undefined;

});

expect(observed).toEqual(payload);

});

export type InitScriptSource<Arg> =

| string

| { path?: string; content?: string }

| ((arg: Arg) => unknown);

import { InitScriptSource } from "../types/private";

import { normalizeInitScriptSource } from "./initScripts";

import { TimeoutError, PageNotFoundError } from "../types/public/sdkErrors";

import { promises as fs } from "fs";

import { InitScriptSource } from "../types/private";

import { StagehandInvalidArgumentError } from "../types/public/sdkErrors";

const DEFAULT_CALLER = "context.addInitScript";

function appendSourceURL(source: string, filePath: string): string {

const sanitized = filePath.replace(/\n/g, "");

return `${source}\n//# sourceURL=${sanitized}`;

export async function normalizeInitScriptSource<Arg>(

script: InitScriptSource<Arg>,

arg?: Arg,

caller: string = DEFAULT_CALLER,

): Promise<string> {

if (typeof script === "function") {

const argString = Object.is(arg, undefined)

? "undefined"

: JSON.stringify(arg);

return `(${script.toString()})(${argString})`;

}

if (!Object.is(arg, undefined)) {

throw new StagehandInvalidArgumentError(

`${caller}: 'arg' is only supported when passing a function.`,

);

}

if (typeof script === "string") {

return script;

}

if (!script || typeof script !== "object") {

throw new StagehandInvalidArgumentError(

`${caller}: provide a string, function, or an object with path/content.`,

);

}

if (typeof script.content === "string") {

return script.content;

}

if (typeof script.path === "string" && script.path.trim()) {

const raw = await fs.readFile(script.path, "utf8");

return appendSourceURL(raw, script.path);

}

throw new StagehandInvalidArgumentError(

`${caller}: provide a string, function, or an object with path/content.`,

);

import { normalizeInitScriptSource } from "./initScripts";

import { InitScriptSource } from "../types/private";

public async addInitScript<Arg>(

script: InitScriptSource<Arg>,

arg?: Arg,

): Promise<void> {

const source = await normalizeInitScriptSource(

script,

arg,

"page.addInitScript",

);

await this.registerInitScript(source);

}

Inject JavaScript that runs before any of the page's scripts on every navigation.

await page.addInitScript<Arg>(

script: string | { path?: string; content?: string } | ((arg: Arg) => unknown),

arg?: Arg,

): Promise<void>

<ParamField

path="script"

type="string | { path?: string; content?: string } | (arg: Arg) => unknown"

required

>

Provide the script to inject. Pass raw source, reference a preload file on disk,

or supply a function that Stagehand serializes before sending to the browser.

</ParamField>

<ParamField path="arg" type="Arg" optional>

Extra data that is JSON-serialized and passed to your function. Only supported

when `script` is a function.

</ParamField>

This method:

- Runs at document start for the current page (including adopted iframe sessions) on every navigation

- Reinstalls the script for all future navigations of this page without affecting other pages

- Mirrors Playwright's `page.addInitScript()` ordering semantics; use [`context.addInitScript()`](/v3/references/context#addinitscript) to target every page in the context

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

const stagehand = new Stagehand({ env: "LOCAL" });

await stagehand.init();

const context = stagehand.context;

const page = await context.awaitActivePage();

await page.addInitScript(() => {

window.Math.random = () => 42;

});

await page.goto("https://example.com", { waitUntil: "load" });

const result = await page.evaluate(() => Math.random());

console.log("Math.random() returned:", result);