The WebSocket class represents WebSocket connections within a page. It provides the ability to inspect and manipulate the data being transmitted and received.
If you want to intercept or modify WebSocket frames, consider using WebSocketRoute.
Since Playwright 1.8.
The examples alias the modules they use (alias Playwright.{Locator, Page}).
Events
:close
Fired when the websocket closes.
:frame_received
Since Playwright 1.9. Fired when the websocket receives a frame.
:frame_sent
Since Playwright 1.9. Fired when the websocket sends a frame.
:socket_error
Since Playwright 1.9. Fired when the websocket has an error.
Summary
Types
An event name, see the module docs.
Options of expect_event/4, see its docs.
A WebSocket handle. Compare handles with ==, their fields are internal.
Options of wait_for_event/3, see its docs.
Functions
Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy value. Will fail if the webSocket is closed before the event is fired. Returns the event data value.
Like expect_event/4, but returns the value and raises on error.
Indicates that the web socket has been closed.
Contains the URL of the WebSocket.
Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy value. Will fail if the webSocket is closed before the event is fired. Returns the event data value.
Like wait_for_event/3, but awaits the promise: Playwright.Promise.await!(wait_for_event(...)), the value or a raise.
Events
Adds an event listener for event, see the module docs for the events.
Removes an event listener added by on/3 or add_listener/3.
Adds an event listener for event, see the module docs for the events.
Adds an event listener that is removed after it is triggered once. See on/3.
Adds an event listener for event, see the module docs for the events.
Removes an event listener added by on/3 or add_listener/3.
Types
@type event() :: :close | :frame_received | :frame_sent | :socket_error
An event name, see the module docs.
@type expect_event_options() :: [ predicate: fun(), timeout: number() | :infinity, signal: Playwright.AbortSignal.t() ] | %{ optional(:predicate) => fun(), optional(:timeout) => number() | :infinity, optional(:signal) => Playwright.AbortSignal.t() }
Options of expect_event/4, see its docs.
@type t() :: %Playwright.WebSocket{ conn: term(), guid: term(), initializer: term(), table: term(), type: term() }
A WebSocket handle. Compare handles with ==, their fields are internal.
@type wait_for_event_options() :: [ predicate: fun(), timeout: number() | :infinity, signal: Playwright.AbortSignal.t() ] | %{ optional(:predicate) => fun(), optional(:timeout) => number() | :infinity, optional(:signal) => Playwright.AbortSignal.t() }
Options of wait_for_event/3, see its docs.
Functions
@spec expect_event( t(), event() | String.t(), (-> term()), expect_event_options() | fun() ) :: {:ok, term()} | {:error, Playwright.error()}
Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy value. Will fail if the webSocket is closed before the event is fired. Returns the event data value.
Since Playwright 1.8.
Arguments
event- Event name, same one would pass intoPlaywright.WebSocket.on/3.action- A function that performs the action triggering the wait. It runs once the wait is set up; its result is ignored and what it raises propagates.
Options
A function in place of the options is the :predicate option.
:predicate(fun/0) - Receives the event data and returns a truthy value when the waiting should resolve.:timeout(number/0|:infinity) - Maximum time to wait for in milliseconds. Defaults to30000(30 seconds). Pass0to disable timeout. The default value can be changed with its page'sPlaywright.Page.set_default_timeout/2orPlaywright.BrowserContext.set_default_timeout/2.In Elixir,
:infinityis the same as0: no timeout.:signal(Playwright.AbortSignal.t/0) - Since Playwright 1.62. Allows to cancel the waiting using anAbortSignal. If the signal is aborted, the waiting will be aborted and the operation will fail. Note that providing a signal does not disable the default timeout, which can be changed usingPlaywright.BrowserContext.set_default_timeout/2; passtimeout: 0to disable the timeout entirely.In Elixir, a
Playwright.AbortSignal(Playwright.AbortController.signal/1).In Elixir, a
Playwright.AbortSignal(Playwright.AbortController.signal/1).
@spec expect_event!( t(), event() | String.t(), (-> term()), expect_event_options() | fun() ) :: term()
Like expect_event/4, but returns the value and raises on error.
Indicates that the web socket has been closed.
Since Playwright 1.8.
Contains the URL of the WebSocket.
Since Playwright 1.8.
@spec wait_for_event(t(), event() | String.t(), wait_for_event_options() | fun()) :: Playwright.Promise.t()
Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy value. Will fail if the webSocket is closed before the event is fired. Returns the event data value.
Since Playwright 1.8.
Arguments
event- Event name, same one would pass intoPlaywright.WebSocket.on/3.
Options
A function in place of the options is the :predicate option.
:predicate(fun/0) - Receives the event data and returns a truthy value when the waiting should resolve.:timeout(number/0|:infinity) - Maximum time to wait for in milliseconds. Defaults to30000(30 seconds). Pass0to disable timeout. The default value can be changed with its page'sPlaywright.Page.set_default_timeout/2orPlaywright.BrowserContext.set_default_timeout/2.In Elixir,
:infinityis the same as0: no timeout.:signal(Playwright.AbortSignal.t/0) - Since Playwright 1.62. Allows to cancel the waiting using anAbortSignal. If the signal is aborted, the waiting will be aborted and the operation will fail. Note that providing a signal does not disable the default timeout, which can be changed usingPlaywright.BrowserContext.set_default_timeout/2; passtimeout: 0to disable the timeout entirely.In Elixir, a
Playwright.AbortSignal(Playwright.AbortController.signal/1).
Returns a Playwright.Promise at once, with the wait already set up. Start it before the action that triggers it and await it after with Playwright.Promise.await/1:
promise = Playwright.WebSocket.wait_for_event(web_socket, event)
Playwright.Locator.click!(button)
value = Playwright.Promise.await!(promise)The callback form expect_event/4 runs the action:
value = Playwright.WebSocket.expect_event!(web_socket, event, fn -> Playwright.Locator.click!(button) end)
Like wait_for_event/3, but awaits the promise: Playwright.Promise.await!(wait_for_event(...)), the value or a raise.
Start waiting before the action
This waits from the time it is called, so it misses what the code before it triggered. Start the wait with wait_for_event/3 before the action and await it after, or use the callback form expect_event!/4:
promise = Playwright.WebSocket.wait_for_event(web_socket, event)
Playwright.Locator.click!(button)
value = Playwright.Promise.await!(promise)value = Playwright.WebSocket.expect_event!(web_socket, event, fn -> Playwright.Locator.click!(button) end)Events
@spec add_listener(t(), :close, (t() -> term())) :: t()
@spec add_listener(t(), :frame_received, (%{payload: String.t() | {:binary, binary()}} -> term())) :: t()
@spec add_listener(t(), :frame_sent, (%{payload: String.t() | {:binary, binary()}} -> term())) :: t()
@spec add_listener(t(), :socket_error, (String.t() -> term())) :: t()
@spec add_listener(t(), String.t(), (term() -> term())) :: t()
Adds an event listener for event, see the module docs for the events.
@spec off(t(), :close, (t() -> term())) :: t()
@spec off(t(), :frame_received, (%{payload: String.t() | {:binary, binary()}} -> term())) :: t()
@spec off(t(), :frame_sent, (%{payload: String.t() | {:binary, binary()}} -> term())) :: t()
@spec off(t(), :socket_error, (String.t() -> term())) :: t()
@spec off(t(), String.t(), (term() -> term())) :: t()
Removes an event listener added by on/3 or add_listener/3.
@spec on(t(), :close, (t() -> term())) :: t()
@spec on(t(), :frame_received, (%{payload: String.t() | {:binary, binary()}} -> term())) :: t()
@spec on(t(), :frame_sent, (%{payload: String.t() | {:binary, binary()}} -> term())) :: t()
@spec on(t(), :socket_error, (String.t() -> term())) :: t()
@spec on(t(), String.t(), (term() -> term())) :: t()
Adds an event listener for event, see the module docs for the events.
@spec once(t(), :close, (t() -> term())) :: t()
@spec once(t(), :frame_received, (%{payload: String.t() | {:binary, binary()}} -> term())) :: t()
@spec once(t(), :frame_sent, (%{payload: String.t() | {:binary, binary()}} -> term())) :: t()
@spec once(t(), :socket_error, (String.t() -> term())) :: t()
@spec once(t(), String.t(), (term() -> term())) :: t()
Adds an event listener that is removed after it is triggered once. See on/3.
@spec prepend_listener(t(), :close, (t() -> term())) :: t()
@spec prepend_listener(t(), :frame_received, (%{ payload: String.t() | {:binary, binary()} } -> term())) :: t()
@spec prepend_listener(t(), :frame_sent, (%{payload: String.t() | {:binary, binary()}} -> term())) :: t()
@spec prepend_listener(t(), :socket_error, (String.t() -> term())) :: t()
@spec prepend_listener(t(), String.t(), (term() -> term())) :: t()
Adds an event listener for event, see the module docs for the events.
@spec remove_listener(t(), :close, (t() -> term())) :: t()
@spec remove_listener(t(), :frame_received, (%{ payload: String.t() | {:binary, binary()} } -> term())) :: t()
@spec remove_listener(t(), :frame_sent, (%{payload: String.t() | {:binary, binary()}} -> term())) :: t()
@spec remove_listener(t(), :socket_error, (String.t() -> term())) :: t()
@spec remove_listener(t(), String.t(), (term() -> term())) :: t()
Removes an event listener added by on/3 or add_listener/3.