# `Playwright.CDPSession`
[🔗](https://github.com/ftes/playwright_ex/blob/v1.65.0-rc.3/lib/playwright/api/cdp_session.ex#L7)

The [`CDPSession`](`Playwright.CDPSession`) instances are used to talk raw Chrome Devtools Protocol:

* protocol methods can be called with `Playwright.CDPSession.send/4` method.
* protocol events can be subscribed to with `Playwright.CDPSession.on/3` method.

Useful links:

* Documentation on DevTools Protocol can be found here:
  [DevTools Protocol Viewer](https://chromedevtools.github.io/devtools-protocol/).
* Getting Started with DevTools Protocol:
  https://github.com/aslushnikov/getting-started-with-cdp/blob/master/README.md

```elixir
client = Page.context(page) |> BrowserContext.new_cdp_session!(page)
CDPSession.send!(client, "Animation.enable")
CDPSession.on(client, "Animation.animationCreated", fn _ -> IO.puts("Animation created!") end)
response = CDPSession.send!(client, "Animation.getPlaybackRate")
IO.puts("playback rate is #{response["playbackRate"]}")
CDPSession.send!(client, "Animation.setPlaybackRate", %{playbackRate: response["playbackRate"] / 2})
```

*Since Playwright 1.8.*

The examples alias the modules they use (`alias Playwright.{Locator, Page}`).

## Events

### `:close`

*Since Playwright 1.59.* Emitted when the session is closed, either because the target was closed or `Playwright.CDPSession.detach/1` was called.

### `:event`

*Since Playwright 1.59.* Emitted for every CDP event received from the session. Allows subscribing to all CDP events at once without knowing
their names ahead of time.

**Usage**

```elixir
CDPSession.on(session, :event, fn event ->
  IO.puts("CDP event: #{event.method} #{inspect(event[:params])}")
end)
```

# `event`

```elixir
@type event() :: :close | :event
```

An event name, see the module docs.

# `send_options`

```elixir
@type send_options() ::
  [signal: Playwright.AbortSignal.t(), timeout: number() | :infinity]
  | %{
      optional(:signal) =&gt; Playwright.AbortSignal.t(),
      optional(:timeout) =&gt; number() | :infinity
    }
```

Options of `send/4`, see its docs.

# `t`

```elixir
@type t() :: %Playwright.CDPSession{
  conn: term(),
  guid: term(),
  initializer: term(),
  table: term(),
  type: term()
}
```

A `CDPSession` handle. Compare handles with `==`, their fields are internal.

# `detach`

```elixir
@spec detach(t()) :: :ok | {:error, Playwright.error()}
```

Detaches the CDPSession from the target. Once detached, the CDPSession object won't emit any events and can't be used to
send messages.

*Since Playwright 1.8.*

# `detach!`

```elixir
@spec detach!(t()) :: :ok
```

Like `detach/1`, but returns the value and raises on error.

# `send`

```elixir
@spec send(t(), String.t(), map() | nil, send_options()) ::
  {:ok, map()} | {:error, Playwright.error()}
```

*Since Playwright 1.8.*

## Arguments

* `method` - Protocol method name.
* `params` - Optional method parameters.

## Options

* `:signal` (`t:Playwright.AbortSignal.t/0`) - *Since Playwright 1.65.* Allows to cancel the operation using an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the operation will be aborted and fail.

  In Elixir, a `Playwright.AbortSignal` (`Playwright.AbortController.signal/1`).
* `:timeout` (`t:number/0` | `:infinity`) - *Since Playwright 1.65.* Maximum time in milliseconds to wait for the response. Defaults to `0` - no timeout.

  In Elixir, `:infinity` is the same as `0`: no timeout.

# `send!`

```elixir
@spec send!(t(), String.t(), map() | nil, send_options()) :: map()
```

Like `send/4`, but returns the value and raises on error.

# `add_listener`

```elixir
@spec add_listener(t(), :close, (t() -&gt; term())) :: t()
@spec add_listener(t(), :event, (%{:method =&gt; String.t(), optional(:params) =&gt; map()} -&gt;
                             term())) :: t()
@spec add_listener(t(), String.t(), (term() -&gt; term())) :: t()
```

Adds an event listener for `event`, see the module docs for the events.

# `off`

```elixir
@spec off(t(), :close, (t() -&gt; term())) :: t()
@spec off(t(), :event, (%{:method =&gt; String.t(), optional(:params) =&gt; map()} -&gt;
                    term())) :: t()
@spec off(t(), String.t(), (term() -&gt; term())) :: t()
```

Removes an event listener added by `on/3` or `add_listener/3`.

# `on`

```elixir
@spec on(t(), :close, (t() -&gt; term())) :: t()
@spec on(t(), :event, (%{:method =&gt; String.t(), optional(:params) =&gt; map()} -&gt; term())) ::
  t()
@spec on(t(), String.t(), (term() -&gt; term())) :: t()
```

Adds an event listener for `event`, see the module docs for the events.

# `once`

```elixir
@spec once(t(), :close, (t() -&gt; term())) :: t()
@spec once(t(), :event, (%{:method =&gt; String.t(), optional(:params) =&gt; map()} -&gt;
                     term())) :: t()
@spec once(t(), String.t(), (term() -&gt; term())) :: t()
```

Adds an event listener that is removed after it is triggered once. See `on/3`.

# `prepend_listener`

```elixir
@spec prepend_listener(t(), :close, (t() -&gt; term())) :: t()
@spec prepend_listener(t(), :event, (%{
                                 :method =&gt; String.t(),
                                 optional(:params) =&gt; map()
                               } -&gt;
                                 term())) ::
  t()
@spec prepend_listener(t(), String.t(), (term() -&gt; term())) :: t()
```

Adds an event listener for `event`, see the module docs for the events.

# `remove_listener`

```elixir
@spec remove_listener(t(), :close, (t() -&gt; term())) :: t()
@spec remove_listener(t(), :event, (%{
                                :method =&gt; String.t(),
                                optional(:params) =&gt; map()
                              } -&gt;
                                term())) ::
  t()
@spec remove_listener(t(), String.t(), (term() -&gt; term())) :: t()
```

Removes an event listener added by `on/3` or `add_listener/3`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
