Package com.microsoft.playwright

Interface BrowserContext

public interface BrowserContext

BrowserContexts provide a way to operate multiple independent browser sessions.

If a page opens another page, e.g. with a window.open call, the popup will belong to the parent page's browser

context.

Playwright allows creation of "incognito" browser contexts with browser.newContext() method.

"Incognito" browser contexts don't write any browsing data to disk.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	BrowserContext.AddCookie
static class	BrowserContext.Cookie
static class	BrowserContext.EventType
static class	BrowserContext.ExposeBindingOptions
static class	BrowserContext.GrantPermissionsOptions
static class	BrowserContext.HTTPCredentials
static class	BrowserContext.SameSite
static class	BrowserContext.StorageState
static class	BrowserContext.WaitForEventOptions

Method Summary

Modifier and Type	Method	Description
void	addCookies(List<BrowserContext.AddCookie> cookies)
default void	addInitScript(String script)
void	addInitScript(String script, Object arg)	Adds a script which would be evaluated in one of the following scenarios:
void	addListener(BrowserContext.EventType type, Listener<BrowserContext.EventType> listener)
Browser	browser()
void	clearCookies()	Clears context cookies.
void	clearPermissions()	Clears all permission overrides for the browser context.
void	close()	Closes the browser context.
default List<BrowserContext.Cookie>	cookies()
default List<BrowserContext.Cookie>	cookies(String url)
List<BrowserContext.Cookie>	cookies(List<String> urls)	If no URLs are specified, this method returns all cookies.
default void	exposeBinding(String name, Page.Binding playwrightBinding)
void	exposeBinding(String name, Page.Binding playwrightBinding, BrowserContext.ExposeBindingOptions options)	The method adds a function called name on the window object of every frame in every page in the context.
void	exposeFunction(String name, Page.Function playwrightFunction)	The method adds a function called name on the window object of every frame in every page in the context.
default void	grantPermissions(List<String> permissions)
void	grantPermissions(List<String> permissions, BrowserContext.GrantPermissionsOptions options)	Grants specified permissions to the browser context.
Page	newPage()	Creates a new page in the browser context.
List<Page>	pages()
void	removeListener(BrowserContext.EventType type, Listener<BrowserContext.EventType> listener)
void	route(String url, Consumer<Route> handler)
void	route(Predicate<String> url, Consumer<Route> handler)	Routing provides the capability to modify network requests that are made by any page in the browser context.
void	route(Pattern url, Consumer<Route> handler)
void	setDefaultNavigationTimeout(int timeout)	This setting will change the default maximum navigation time for the following methods and related shortcuts:
void	setDefaultTimeout(int timeout)	This setting will change the default maximum time for all the methods accepting timeout option.
void	setExtraHTTPHeaders(Map<String,String> headers)	The extra HTTP headers will be sent with every request initiated by any page in the context.
void	setGeolocation(Geolocation geolocation)	Sets the context's geolocation.
void	setOffline(boolean offline)
BrowserContext.StorageState	storageState()	Returns storage state for this browser context, contains current cookies and local storage snapshot.
default void	unroute(String url)
void	unroute(String url, Consumer<Route> handler)
default void	unroute(Predicate<String> url)
void	unroute(Predicate<String> url, Consumer<Route> handler)	Removes a route created with browserContext.route(url, handler).
default void	unroute(Pattern url)
void	unroute(Pattern url, Consumer<Route> handler)
default Deferred<Event<BrowserContext.EventType>>	waitForEvent(BrowserContext.EventType event)
Deferred<Event<BrowserContext.EventType>>	waitForEvent(BrowserContext.EventType event, BrowserContext.WaitForEventOptions options)	Waits for event to fire and passes its value into the predicate function.
default Deferred<Event<BrowserContext.EventType>>	waitForEvent(BrowserContext.EventType event, Predicate<Event<BrowserContext.EventType>> predicate)

Method Detail

addListener

void addListener(BrowserContext.EventType type,
                 Listener<BrowserContext.EventType> listener)

removeListener

void removeListener(BrowserContext.EventType type,
                    Listener<BrowserContext.EventType> listener)

addCookies

void addCookies(List<BrowserContext.AddCookie> cookies)

addInitScript

default void addInitScript(String script)

addInitScript

void addInitScript(String script,
                   Object arg)

Adds a script which would be evaluated in one of the following scenarios:

Whenever a page is created in the browser context or is navigated.

Whenever a child frame is attached or navigated in any page in the browser context. In this case, the script is evaluated in the context of the newly attached frame.

The script is evaluated after the document was created but before any of its scripts were run. This is useful to amend the JavaScript environment, e.g. to seed Math.random.

NOTE The order of evaluation of multiple scripts installed via browserContext.addInitScript(script[, arg]) and page.addInitScript(script[, arg]) is not defined.

Parameters:

script - Script to be evaluated in all pages in the browser context.

arg - Optional argument to pass to script (only supported when passing a function).

browser

Browser browser()

Returns:

Returns the browser instance of the context. If it was launched as a persistent context null gets returned.

clearCookies

void clearCookies()

Clears context cookies.

clearPermissions

void clearPermissions()

Clears all permission overrides for the browser context.

close

void close()

Closes the browser context. All the pages that belong to the browser context

will be closed.

NOTE the default browser context cannot be closed.

cookies

default List<BrowserContext.Cookie> cookies()

cookies

default List<BrowserContext.Cookie> cookies(String url)

cookies

List<BrowserContext.Cookie> cookies(List<String> urls)

If no URLs are specified, this method returns all cookies.

If URLs are specified, only cookies that affect those URLs are returned.

exposeBinding

default void exposeBinding(String name,
                           Page.Binding playwrightBinding)

exposeBinding

void exposeBinding(String name,
                   Page.Binding playwrightBinding,
                   BrowserContext.ExposeBindingOptions options)

The method adds a function called name on the window object of every frame in every page in the context.

When called, the function executes playwrightBinding in Node.js and returns a Promise which resolves to the return value of playwrightBinding.

If the playwrightBinding returns a Promise, it will be awaited.

The first argument of the playwrightBinding function contains information about the caller:

{ browserContext: BrowserContext, page: Page, frame: Frame }.

See page.exposeBinding(name, playwrightBinding) for page-only version.

Parameters:

name - Name of the function on the window object.

playwrightBinding - Callback function that will be called in the Playwright's context.

exposeFunction

void exposeFunction(String name,
                    Page.Function playwrightFunction)

The method adds a function called name on the window object of every frame in every page in the context.

When called, the function executes playwrightFunction in Node.js and returns a Promise which resolves to the return value of playwrightFunction.

If the playwrightFunction returns a Promise, it will be awaited.

See page.exposeFunction(name, playwrightFunction) for page-only version.

Parameters:

name - Name of the function on the window object.

playwrightFunction - Callback function that will be called in the Playwright's context.

grantPermissions

default void grantPermissions(List<String> permissions)

grantPermissions

void grantPermissions(List<String> permissions,
                      BrowserContext.GrantPermissionsOptions options)

Grants specified permissions to the browser context. Only grants corresponding permissions to the given origin if specified.

Parameters:

permissions - A permission or an array of permissions to grant. Permissions can be one of the following values: - 'geolocation' - 'midi' - 'midi-sysex' (system-exclusive midi) - 'notifications' - 'push' - 'camera' - 'microphone' - 'background-sync' - 'ambient-light-sensor' - 'accelerometer' - 'gyroscope' - 'magnetometer' - 'accessibility-events' - 'clipboard-read' - 'clipboard-write' - 'payment-handler'

newPage

Page newPage()

Creates a new page in the browser context.

pages

List<Page> pages()

Returns:

All open pages in the context. Non visible pages, such as "background_page", will not be listed here. You can find them using chromiumBrowserContext.backgroundPages().

route

void route(String url,
           Consumer<Route> handler)

route

void route(Pattern url,
           Consumer<Route> handler)

route

void route(Predicate<String> url,
           Consumer<Route> handler)

Routing provides the capability to modify network requests that are made by any page in the browser context.

Once route is enabled, every request matching the url pattern will stall unless it's continued, fulfilled or aborted.

or the same snippet using a regex pattern instead:

Page routes (set up with page.route(url, handler)) take precedence over browser context routes when request matches both handlers.

NOTE Enabling routing disables http cache.

Parameters:

url - A glob pattern, regex pattern or predicate receiving URL to match while routing.

handler - handler function to route the request.

setDefaultNavigationTimeout

void setDefaultNavigationTimeout(int timeout)

This setting will change the default maximum navigation time for the following methods and related shortcuts:

page.goBack([options])

page.goForward([options])

page.goto(url[, options])

page.reload([options])

page.setContent(html[, options])

page.waitForNavigation([options])

NOTE page.setDefaultNavigationTimeout and page.setDefaultTimeout take priority over browserContext.setDefaultNavigationTimeout.

Parameters:

timeout - Maximum navigation time in milliseconds

setDefaultTimeout

void setDefaultTimeout(int timeout)

This setting will change the default maximum time for all the methods accepting timeout option.

NOTE page.setDefaultNavigationTimeout, page.setDefaultTimeout and browserContext.setDefaultNavigationTimeout take priority over browserContext.setDefaultTimeout.

Parameters:

timeout - Maximum time in milliseconds

setExtraHTTPHeaders

void setExtraHTTPHeaders(Map<String,String> headers)

The extra HTTP headers will be sent with every request initiated by any page in the context. These headers are merged with page-specific extra HTTP headers set with page.setExtraHTTPHeaders(). If page overrides a particular header, page-specific header value will be used instead of the browser context header value.

NOTE browserContext.setExtraHTTPHeaders does not guarantee the order of headers in the outgoing requests.

Parameters:

headers - An object containing additional HTTP headers to be sent with every request. All header values must be strings.

setGeolocation

void setGeolocation(Geolocation geolocation)

Sets the context's geolocation. Passing null or undefined emulates position unavailable.

NOTE Consider using browserContext.grantPermissions to grant permissions for the browser context pages to read its geolocation.

setOffline

void setOffline(boolean offline)

Parameters:

offline - Whether to emulate network being offline for the browser context.

storageState

BrowserContext.StorageState storageState()

Returns storage state for this browser context, contains current cookies and local storage snapshot.

unroute

default void unroute(String url)

unroute

default void unroute(Pattern url)

unroute

default void unroute(Predicate<String> url)

unroute

void unroute(String url,
             Consumer<Route> handler)

unroute

void unroute(Pattern url,
             Consumer<Route> handler)

unroute

void unroute(Predicate<String> url,
             Consumer<Route> handler)

Removes a route created with browserContext.route(url, handler). When handler is not specified, removes all routes for the url.

Parameters:

url - A glob pattern, regex pattern or predicate receiving URL used to register a routing with browserContext.route(url, handler).

handler - Handler function used to register a routing with browserContext.route(url, handler).

waitForEvent

default Deferred<Event<BrowserContext.EventType>> waitForEvent(BrowserContext.EventType event)

waitForEvent

default Deferred<Event<BrowserContext.EventType>> waitForEvent(BrowserContext.EventType event,
                                                               Predicate<Event<BrowserContext.EventType>> predicate)

waitForEvent

Deferred<Event<BrowserContext.EventType>> waitForEvent(BrowserContext.EventType event,
                                                       BrowserContext.WaitForEventOptions options)

Waits for event to fire and passes its value into the predicate function. Resolves when the predicate returns truthy value. Will throw an error if the context closes before the event

is fired.

Parameters:

event - Event name, same one would pass into browserContext.on(event).

Returns:

Promise which resolves to the event data value.