Playwright.BrowserContext (playwright v0.1.16-preview-3) View Source

Playwright.BrowserContext provides 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 the Playwright.Browser.new_context/1 function.

Example

# create a new "incognito" browser context:
{:ok, context} = Playwright.Browser.new_context(browser)

# create and use a new page within that context:
{:ok, page} = Playwright.BrowserContext.new_page(context)
{:ok, resp} = Playwright.Page.goto(page, "https://example.com")

# dispose the context once it's no longer needed:
Playwright.BrowserContext.close(context)

Regarding expect_event/5 and on/3

The first argument given to on/3 and expect_event/5 functions is the "owner" on which to bind the event.

The second argument is the event type.

The third argument is a callback function that will be executed when the event fires, and is passed an instance of Playwright.Runner.EventInfo.

Details for expect_event/5

Calls to expect_event/5 are blocking. These functions take a "trigger", execution of which is expected to result in the event being fired.

If the event does not fire within the timeout window, the call to expect_event/5 will timeout.

An optional "predicate" function may be provided, in which case the fired event will be sent to the predicate, which must return a "truthy" result in order for the expectation to be fulfilled.

{:ok, e } = BrowserContext.expect_event(context, :close, fn ->
  Page.close(page)
end)
assert %BrowserContext{} = e.target

Details for on/3

Calls to on/3 are non-blocking and register callbacks for the lifetime of the binding target.

BrowserContext.on(context, :close, fn e ->
  assert %BrowserContext{} = e.target
end)

Event types

The expect_event/5 and on/3 functions support the following event types:

  • :background_page

    Emitted when a new background page is created in the context. The event target is a Playwright.Page.

    ...

    NOTE:

    • Only works with Chromium browser's persistent context.
  • :close

    Emitted when the Playwright.BrowserContext is closed. The event target is a Playwright.BrowserContext. This might happen because of any of the following:

    • Browser context is closed.
    • Browser application is closed or crashed.
    • Playwright.Browser.close/1 is called.
    • Playwright.Page.close/1 is with the "owner page" for this context.
  • :page

    Emitted when a new Playwright.Page is created within the context. The page may still be loading. The event target is a Playwright.Page. The event will also fire for popup pages. The earliest moment that a page is available is when it has navigated to the initial URL. For example, when opening a popup with window.open('http://example.com'), this event will fire when the network request to "http://example.com" is done and its response has started loading in the popup.

    BrowserContext.expect_event(context, :page, fn ->
      Page.click(page, "a[target=_blank]")
    end)

    NOTE:

  • :request

    Emitted when a request is issued from any pages created through this context. The event target is a Playwright.Request. To only listen for requests from a particular page, use Playwright.Page.on/3 (for :request). In order to intercept and mutate requests, see route/4 or Playwright.Page.route/4.

  • :request_failed

    Emitted when a request fails, for example by timing out. The event target is a Playwright.Request. To only listen for failed requests from a particular page, use Playwright.Page.on/3 (for :request_failed).

    NOTE:

    • HTTP error responses, such as 404 or 503, are still successful responses from HTTP standpoint. So, the request will complete with a :request_finished event and not with :request_failed.
  • :request_finished

    Emitted when a request finishes successfully after downloading the response body. The event target is a Playwright.Request. For a successful response, the sequence of events is :request, :response and :request_finished. To listen for successful requests from a particular page, use Playwright.Page.on/3 (for :request_finished).

  • :response

    Emitted when response status and headers are received for a request. The event target is a Playwright.Response. For a successful response, the sequence of events is :request, :response and :request_finished. To listen for response events from a particular page, use Playwright.Page.on/3 (for :response).

  • :service_worker

    Emitted when new service worker is created in the context. The event target is a Playwright.Worker.

    NOTE:

    • Service workers are only supported on Chromium-based browsers.

Link to this section Summary

Types

Recognized cookie fields

Supported events

An optional (maybe nil) function or option

A map/struct providing call options

t()

%Playwright.BrowserContext{}

A string URL

Link to this section Types

Specs

cookie() :: %{
  name: String.t(),
  value: String.t(),
  url: String.t(),
  domain: String.t(),
  path: String.t(),
  expires: float(),
  httpOnly: boolean(),
  secure: boolean(),
  sameSite: String.t()
}

Recognized cookie fields

Specs

event() ::
  :background_page
  | :close
  | :page
  | :request
  | :request_failed
  | :request_finished
  | :response
  | :service_worker

Supported events

Specs

function_or_options() :: (... -> any()) | options() | nil

An optional (maybe nil) function or option

Specs

options() :: map()

A map/struct providing call options

Specs

t() :: %Playwright.BrowserContext{
  browser: term(),
  connection: term(),
  guid: term(),
  listeners: term(),
  owner_page: term(),
  parent: term(),
  type: term()
}

%Playwright.BrowserContext{}

Specs

url() :: String.t()

A string URL

Link to this section Functions

Link to this function

add_cookies(owner, cookies)

View Source

Specs

add_cookies(t(), [cookie()]) :: :ok

Adds cookies into this Playwright.BrowserContext.

All pages within this context will have these cookies installed. Cookies can be obtained via Playwright.BrowserContext.cookies/1.

Example

:ok = BrowserContext.add_cookies(context, [cookie_1, cookie_2])
keydescription
:name
:value
:url(optional) either url or domain / path are required
:domain(optional) either url or domain / path are required
:path(optional) either url or domain / path are required
:expires(optional) Unix time in seconds.
:httpOnly(optional)
:secure(optional)
:sameSite(optional) one of "Strict", "Lax", "None"

Specs

close(t()) :: :ok

Closes the Playwright.BrowserContext. All pages that belong to the Playwright.BrowserContext will be closed.

NOTE:

  • The default browser context cannot be closed.
Link to this function

cookies(owner, urls \\ [])

View Source

Specs

cookies(t(), url() | [url()]) :: {:ok, [cookie()]}

Returns cookies for the Playwright.BrowserContext.

If no URLs are specified, this method returns all cookies. If URLs are specified, only cookies that affect those URLs are returned.

paramdescription
urls(optional) List of URLs

See add_cookies/2 for cookie field details.

Link to this function

expect_event(owner, event, trigger, predicate \\ nil, options \\ %{})

View Source

Specs

expect_event(
  t() | Playwright.Page.t(),
  atom() | binary(),
  (... -> any()),
  function_or_options(),
  map()
) :: {:ok, Playwright.Runner.EventInfo.t()}

Waits for an event to fire (i.e., is blocking) and passes its value into the predicate function.

Returns when the predicate returns a truthy value. Throws an error if the context closes before the event is fired. Returns a Playwright.Runner.EventInfo.

Arguments

  • event: Event name; the same as those passed to Playwright.BrowserContext.on/3
  • predicate: Receives the Playwright.Runner.EventInfo and resolves to a "truthy" value when the waiting should resolve.
  • options:
    • predicate: ...
    • timeout: The maximum time to wait in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. The default value can be changed via Playwright.BrowserContext.set_default_timeout/2.

Example

{:ok, event_info} = BrowserContext.expect_event(owner, :page, fn ->
  BrowserContext.new_page(owner)
end)

NOTE:

  • The "throw an error if the context closes..." is not yet implemented.
  • The handling of :predicate is not yet implemented.
Link to this function

expect_page(owner, trigger, predicate \\ nil, options \\ %{})

View Source

Specs

expect_page(t(), (... -> any()), function_or_options(), map()) ::
  {:ok, Playwright.Runner.EventInfo.t()}

Executes trigger and waits for a new Playwright.Page to be created within the Playwright.BrowserContext.

If predicate is provided, it passes the Playwright.Page value into the predicate function, wrapped in Playwright.Runner.EventInfo, and waits for predicate/1 to return a "truthy" value. Throws an error if the context closes before new Playwright.Page is created.

Arguments

  • predicate: Receives the Playwright.Page and resolves to truthy value when the waiting should resolve.
  • options:
    • predicate: ...
    • timeout: The maximum time to wait in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. The default value can be changed via Playwright.BrowserContext.set_default_timeout/2.

NOTE:

  • The handling of predicate is not yet implemented.
  • The handling of timeout is not yet implemented.

Specs

new_page(t()) :: {:ok, Playwright.Page.t()}

Creates a new Playwright.Page in the context.

If the context is already "owned" by a Playwright.Page (i.e., was created as a side effect of Playwright.Browser.new_page/1), will raise an error because there should be a 1-to-1 mapping in that case.

Link to this function

on(owner, event, callback)

View Source

Specs

on(t(), event(), function()) :: {:ok, t()}

Register a (non-blocking) callback/handler for various types of events.

Link to this function

wait_for_event(owner, event, trigger, predicate \\ nil, options \\ %{})

View Source

See Playwright.BrowserContext.expect_event/5.

Link to this function

wait_for_page(owner, trigger, predicate \\ nil, options \\ %{})

View Source

See Playwright.BrowserContext.expect_page/4.