context - Stagehand

Use BrowserContext to coordinate pages and browser state that is shared across them.

TypeScript
Python
Go

Quick start

const context = browser.context;
const page = await context.newPage();

pages()

Return every open page in the browser context.

const pages = await browser.context.pages();

Promise<Page[]>

The operation result.

newPage()

Create a new page in the browser context.

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

string

The initial URL for the new page. Omit it to create a blank page.

Promise<Page>

The operation result.

activePage()

Return the page that is currently active.

const [page] = await browser.context.pages();

Promise<Page | undefined>

The operation result.

setActivePage()

Make a page the active page in the browser context.

await browser.context.setActivePage(page);

Page

The page to make active.

Promise<void>

Resolves after the operation completes.

close()

Close the remote browser context.

await browser.context.close();

Promise<void>

Resolves after the operation completes.

addInitScript()

Run a script before scripts on every newly created page.

await browser.context.addInitScript(() => {
  window.localStorage.clear();
});

InitScriptSource<Arg>

A function, JavaScript source string, or object with exactly one of path and content.

Arg

An optional JSON-serializable argument. Valid only when script is a function.

Promise<void>

Resolves after the operation completes.

setExtraHTTPHeaders()

Set additional HTTP headers for every page in the context.

await browser.context.setExtraHTTPHeaders({ "x-test": "true" });

Record<string, string>

HTTP header names and values.

Promise<void>

Resolves after the operation completes.

getDomainPolicy()

Return the context’s current domain policy.

const policy = await browser.context.getDomainPolicy();

Promise<DomainPolicy | null>

The operation result.

string[]

Domains that the context may access.

string[]

Domains that the context must reject.

setDomainPolicy()

Set or clear the context’s domain policy.

await browser.context.setDomainPolicy(null);

DomainPolicy | null

The policy to apply, or null/None to clear it.

string[]

Domains that the context may access.

string[]

Domains that the context must reject.

Promise<void>

Resolves after the operation completes.

cookies()

Return cookies, optionally filtered to one or more URLs.

const cookies = await browser.context.cookies("https://example.com");

string | string[]

A URL or collection of URLs used to filter cookies.

Promise<Cookie[]>

The operation result.

string

The cookie name.

string

The cookie value.

string

The cookie domain.

string

The cookie path.

number

The Unix expiration time in seconds, or -1 for a session cookie.

boolean

Whether the cookie is restricted to HTTP requests.

boolean

Whether the cookie requires HTTPS.

Cookie['sameSite']

The cookie SameSite policy: "Strict", "Lax", or "None".

addCookies()

Add cookies to the browser context.

await browser.context.addCookies([cookie]);

CookieParam[]

The cookies to add. Each requires name, value, and either url or both domain and path. Do not combine url with domain or path.

string

The cookie domain.

number

-1 for a session cookie or a non-negative Unix timestamp in seconds.

boolean

Whether the cookie is restricted to HTTP requests.

string

The cookie name.

string

The cookie path.

CookieParam['sameSite']

The cookie SameSite policy: "Strict", "Lax", or "None". "None" requires a secure cookie.

boolean

Whether the cookie requires HTTPS.

string

The URL scope. Cannot be about:blank or a data: URL.

string

The cookie value.

Promise<void>

Resolves after the operation completes.

clearCookies()

Clear cookies that match optional name, domain, and path filters.

await browser.context.clearCookies({ domain: "example.com" });

ClearCookieOptions

Options that configure this operation.

string | RegExp

A cookie domain or regular-expression filter.

string | RegExp

A cookie name or regular-expression filter.

string | RegExp

A cookie path or regular-expression filter.

Promise<void>

Resolves after the operation completes.

Quick start

context = browser.context
page = await context.new_page()

pages()

Return every open page in the browser context.

pages = await browser.context.pages()

list[Page]

The operation result.

new_page()

Create a new page in the browser context.

page = await browser.context.new_page("https://example.com")

str | None

The initial URL for the new page. Omit it to create a blank page.

Page

The operation result.

active_page()

Return the page that is currently active.

page = (await browser.context.pages())[0]

Page | None

The operation result.

set_active_page()

Make a page the active page in the browser context.

await browser.context.set_active_page(page)

Page

The page to make active.

None

Resolves after the operation completes.

close()

Close the remote browser context.

await browser.context.close()

None

Resolves after the operation completes.

add_init_script()

Run a script before scripts on every newly created page.

await browser.context.add_init_script("window.localStorage.clear()")

str | Path

JavaScript source or a path to a JavaScript file on the SDK caller’s machine.

None

Resolves after the operation completes.

set_extra_http_headers()

Set additional HTTP headers for every page in the context.

await browser.context.set_extra_http_headers({"x-test": "true"})

Mapping[str, str]

HTTP header names and values.

None

Resolves after the operation completes.

get_domain_policy()

Return the context’s current domain policy.

policy = await browser.context.get_domain_policy()

DomainPolicy | None

The operation result.

list[str]

Domains that the context may access.

list[str]

Domains that the context must reject.

set_domain_policy()

Set or clear the context’s domain policy.

await browser.context.set_domain_policy(None)

DomainPolicy | DomainPolicyInput | None

The policy to apply, or null/None to clear it.

list[str]

Domains that the context may access.

list[str]

Domains that the context must reject.

None

Resolves after the operation completes.

cookies()

Return cookies, optionally filtered to one or more URLs.

cookies = await browser.context.cookies("https://example.com")

str | Sequence[str] | None

A URL or collection of URLs used to filter cookies.

list[Cookie]

The operation result.

str

The cookie name.

str

The cookie value.

str

The cookie domain.

str

The cookie path.

float

The Unix expiration time in seconds, or -1 for a session cookie.

bool

Whether the cookie is restricted to HTTP requests.

bool

Whether the cookie requires HTTPS.

Literal['Strict', 'Lax', 'None']

The cookie SameSite policy: "Strict", "Lax", or "None".

add_cookies()

Add cookies to the browser context.

await browser.context.add_cookies([cookie])

Sequence[CookieParam]

The cookies to add. Each requires name, value, and either url or both domain and path. Do not combine url with domain or path.

str

The cookie domain.

float

-1 for a session cookie or a non-negative Unix timestamp in seconds.

bool

Whether the cookie is restricted to HTTP requests.

str

The cookie name.

str

The cookie path.

Literal['Strict', 'Lax', 'None']

The cookie SameSite policy: "Strict", "Lax", or "None". "None" requires a secure cookie.

bool

Whether the cookie requires HTTPS.

str

The URL scope. Cannot be about:blank or a data: URL.

str

The cookie value.

None

Resolves after the operation completes.

clear_cookies()

Clear cookies that match optional name, domain, and path filters.

await browser.context.clear_cookies(domain="example.com")

str | re.Pattern[str] | None

A cookie name or regular-expression filter.

str | re.Pattern[str] | None

A cookie domain or regular-expression filter.

str | re.Pattern[str] | None

A cookie path or regular-expression filter.

None

Resolves after the operation completes.

Quick start

Get the BrowserContext from the browser handle with browser.Context(). Except for the Clipboard() accessor, every method takes a context.Context as its first argument and returns an error as its last result.

browserContext, err := browser.Context()
if err != nil {
    return err
}
page, err := browserContext.NewPage(ctx)
if err != nil {
    return err
}
if _, err := page.Goto(ctx, "https://example.com", nil); err != nil {
    return err
}

Pages()

Return every open page in the browser context.

func (c *BrowserContext) Pages(ctx context.Context) ([]*Page, error)

pages, err := browserContext.Pages(ctx)
if err != nil {
    return err
}
fmt.Println(len(pages))

[]*Page

The operation result.

NewPage()

Create a new page in the browser context.

func (c *BrowserContext) NewPage(ctx context.Context, url ...string) (*Page, error)

if _, err := browserContext.NewPage(ctx, "https://example.com"); err != nil {
    return err
}

...string

The initial URL for the new page. Pass at most one URL; omit it to create a blank page.

*Page

The operation result.

ActivePage()

Return the page that is currently active.

func (c *BrowserContext) ActivePage(ctx context.Context) (*Page, error)

if _, err := browserContext.ActivePage(ctx); err != nil {
    return err
}

*Page

The operation result. Returns nil when no page is active.

SetActivePage()

Make a page the active page in the browser context.

func (c *BrowserContext) SetActivePage(ctx context.Context, page *Page) error

if err := browserContext.SetActivePage(ctx, page); err != nil {
    return err
}

*Page

The page to make active.

error

nil after the operation completes.

Close()

Close the remote browser context.

func (c *BrowserContext) Close(ctx context.Context) error

if err := browserContext.Close(ctx); err != nil {
    return err
}

error

nil after the operation completes.

AddInitScript()

Run a script before scripts on every newly created page.

func (c *BrowserContext) AddInitScript(ctx context.Context, source string) error

if err := browserContext.AddInitScript(ctx, "window.localStorage.clear()"); err != nil {
    return err
}

string

JavaScript source to evaluate. Go functions and file paths are not interpreted.

error

nil after the operation completes.

SetExtraHTTPHeaders()

Set additional HTTP headers for every page in the context.

func (c *BrowserContext) SetExtraHTTPHeaders(ctx context.Context, headers ContextSetExtraHTTPHeadersParamsHeaders) error

if err := browserContext.SetExtraHTTPHeaders(ctx, map[string]string{"x-test": "true"}); err != nil {
    return err
}

ContextSetExtraHTTPHeadersParamsHeaders

HTTP header names and values. The type is a named map[string]string, so a plain map literal works.

error

nil after the operation completes.

GetDomainPolicy()

Return the context’s current domain policy.

func (c *BrowserContext) GetDomainPolicy(ctx context.Context) (*DomainPolicy, error)

policy, err := browserContext.GetDomainPolicy(ctx)
if err != nil {
    return err
}
fmt.Println(policy)

*DomainPolicy

The operation result. Returns nil when no policy is set.

[]string

Domains that the context may access.

[]string

Domains that the context must reject.

SetDomainPolicy()

Set or clear the context’s domain policy.

func (c *BrowserContext) SetDomainPolicy(ctx context.Context, policy *DomainPolicy) error

if err := browserContext.SetDomainPolicy(ctx, nil); err != nil {
    return err
}

*DomainPolicy

The policy to apply, or nil to clear it.

[]string

Domains that the context may access.

[]string

Domains that the context must reject.

error

nil after the operation completes.

Cookies()

Return cookies, optionally filtered to one or more URLs.

func (c *BrowserContext) Cookies(ctx context.Context, urls *StringList) ([]Cookie, error)

urls := stagehand.StringList{"https://example.com"}
cookies, err := browserContext.Cookies(ctx, &urls)
if err != nil {
    return err
}
fmt.Println(cookies)

*StringList

A collection of URLs used to filter cookies. Pass nil to return every cookie.

[]Cookie

The operation result.

string

The cookie name.

string

The cookie value.

string

The cookie domain.

string

The cookie path.

float64

The Unix expiration time in seconds, or -1 for a session cookie.

bool

Whether the cookie is restricted to HTTP requests.

bool

Whether the cookie requires HTTPS.

CookieSameSite

The cookie SameSite policy: CookieSameSiteStrict, CookieSameSiteLax, or CookieSameSiteNone.

AddCookies()

Add cookies to the browser context.

func (c *BrowserContext) AddCookies(ctx context.Context, cookies []CookieParam) error

url := "https://example.com"
cookie := stagehand.CookieParam{Name: "session", Value: "abc123", URL: &url}
if err := browserContext.AddCookies(ctx, []stagehand.CookieParam{cookie}); err != nil {
    return err
}

[]CookieParam

The cookies to add. Each requires Name, Value, and either URL or both Domain and Path. Do not combine URL with Domain or Path. Optional fields are pointers.

*string

The cookie domain.

*float64

-1 for a session cookie or a non-negative Unix timestamp in seconds.

*bool

Whether the cookie is restricted to HTTP requests.

string

The cookie name.

*string

The cookie path.

*CookieParamSameSite

The cookie SameSite policy: CookieParamSameSiteStrict, CookieParamSameSiteLax, or CookieParamSameSiteNone. CookieParamSameSiteNone requires a secure cookie.

*bool

Whether the cookie requires HTTPS.

*string

The URL scope. Cannot be about:blank or a data: URL.

string

The cookie value.

error

nil after the operation completes.

ClearCookies()

Clear cookies that match optional name, domain, and path filters.

func (c *BrowserContext) ClearCookies(ctx context.Context, options *ClearCookieOptions) error

domain := stagehand.ExactCookie("example.com")
if err := browserContext.ClearCookies(ctx, &stagehand.ClearCookieOptions{Domain: &domain}); err != nil {
    return err
}

*ClearCookieOptions

Options that configure this operation. Pass nil to clear every cookie. Build each filter with ExactCookie() for an exact string or RegexCookie() for a regular expression.

*CookieFilter

A cookie name filter.

*CookieFilter

A cookie domain filter.

*CookieFilter

A cookie path filter.

error

nil after the operation completes.

​Quick start

​pages()

​newPage()

​activePage()

​setActivePage()

​close()

​addInitScript()

​setExtraHTTPHeaders()

​getDomainPolicy()

​setDomainPolicy()

​cookies()

​addCookies()

​clearCookies()

​Quick start

​pages()

​new_page()

​active_page()

​set_active_page()

​close()

​add_init_script()

​set_extra_http_headers()

​get_domain_policy()

​set_domain_policy()

​cookies()

​add_cookies()

​clear_cookies()

​Quick start

​Pages()

​NewPage()

​ActivePage()

​SetActivePage()

​Close()

​AddInitScript()

​SetExtraHTTPHeaders()

​GetDomainPolicy()

​SetDomainPolicy()

​Cookies()

​AddCookies()

​ClearCookies()

Quick start

pages()

newPage()

activePage()

setActivePage()

close()

addInitScript()

setExtraHTTPHeaders()

getDomainPolicy()

setDomainPolicy()

cookies()

addCookies()

clearCookies()

Quick start

pages()

new_page()

active_page()

set_active_page()

close()

add_init_script()

set_extra_http_headers()

get_domain_policy()

set_domain_policy()

cookies()

add_cookies()

clear_cookies()

Quick start

Pages()

NewPage()

ActivePage()

SetActivePage()

Close()

AddInitScript()

SetExtraHTTPHeaders()

GetDomainPolicy()

SetDomainPolicy()

Cookies()

AddCookies()

ClearCookies()