# `Fluffy.Playwright`
[🔗](https://github.com/ftes/fluffy/blob/v0.8.0/lib/fluffy/playwright.ex#L1)

Browser-only helpers for the active Playwright page.

These functions intentionally live under `Fluffy.Playwright` because they
depend on a real browser. Use them when behavior requires one; they are not
implemented by the Static or LiveView drivers.

# `evaluate_option`

```elixir
@type evaluate_option() ::
  {:arg, term()}
  | {:is_function, boolean()}
  | {:timeout, nil | non_neg_integer()}
```

# `screenshot_option`

```elixir
@type screenshot_option() ::
  {:full_page, boolean()}
  | {:omit_background, boolean()}
  | {:timeout, pos_integer()}
```

# `trace_option`

```elixir
@type trace_option() ::
  {:directory, binary()}
  | {:name, binary()}
  | {:open, boolean()}
  | {:screenshots, boolean()}
  | {:snapshots, boolean()}
  | {:sources, boolean()}
  | {:coverage, boolean()}
```

# `add_cookies`
*Playwright only* 

Adds cookie maps to the browser context and returns the session.

# `clear_cookies`
*Playwright only* 

Clears cookies and returns the session. Filters `:name`, `:domain`, and `:path` accept strings or regexes. Accepts `:timeout`.

# `cookies`
*Playwright only* 

Returns browser cookies, optionally filtered by a list of `:urls`. Accepts `:timeout`.

# `evaluate`
*Playwright only* 

```elixir
@spec evaluate(Fluffy.Session.t(), String.t(), [evaluate_option()]) :: term()
```

Evaluates JavaScript in the active Playwright page and returns the value.

This mirrors Playwright's page/frame evaluation semantics: promises are
awaited by Playwright, serializable JavaScript values are returned to Elixir,
and JavaScript or protocol failures raise.

`evaluate/3` is a browser-only value query, so it returns the evaluated value
rather than the Fluffy session. Use Elixir's `then/2` when a pipeline needs
the value and then should continue with the session:

    import Fluffy
    import Fluffy.Playwright
    import Fluffy.Locator
    alias Fluffy.Playwright

    session
    |> then(fn session ->
      title = Playwright.evaluate(session, "document.title")
      assert title == "Potions classroom"
      session
    end)
    |> click(by_role(:button, name: "Continue"))

For function-style expressions, pass `is_function: true` and `arg:`:

    Playwright.evaluate(session, "selector => document.querySelector(selector).textContent",
      is_function: true,
      arg: "#status"
    )

Do not use this for JavaScript that owns a navigation, opens a page, starts a
download, or installs a durable listener. Use the corresponding
listener-before-action `Fluffy.wait_for/3` event API so lifecycle and
cleanup remain owned by Fluffy. Reserve `Fluffy.unwrap/2` for uncommon
page-local operations that have no first-class API.

## Options

* `:arg` (`t:term/0`) - Serializable argument passed to a function-style expression. The default value is `nil`.

* `:is_function` (`t:boolean/0`) - Treat the expression as a JavaScript function. The default value is `false`.

* `:timeout` (`t:non_neg_integer/0` or `nil`) - Maximum evaluation time in milliseconds; defaults to the session timeout. The default value is `nil`.

# `screenshot`
*Playwright only* 

```elixir
@spec screenshot(Fluffy.Session.t(), Path.t(), [screenshot_option()]) ::
  Fluffy.Session.t()
```

Saves a PNG screenshot of the active page and returns the session.

## Options

* `:full_page` (`t:boolean/0`) - Capture the full scrollable page instead of only the viewport. The default value is `false`.

* `:omit_background` (`t:boolean/0`) - Hide the default white background to allow transparency. The default value is `false`.

* `:timeout` (`t:pos_integer/0`) - Maximum screenshot time in milliseconds.

# `storage_state`
*Playwright only* 

Returns storage state for reuse as `browser_context: [storage_state: state]`. Accepts `:indexed_db`, `:timeout`, and optional JSON output `:path`.

# `trace`
*Playwright only* 

```elixir
@spec trace(Fluffy.Session.t(), [trace_option()]) :: Fluffy.Session.t()
```

Starts a Playwright trace for this session's BrowserContext.

The trace includes every page in the session and is saved when the test's
lifecycle scope shuts down. Because an explicit trace is primarily a local
debugging request, its viewer opens by default; pass `open: false` in CI. A
session may start one trace.

## Options

* `:directory` (`t:String.t/0`) - Directory in which to save the trace archive.

* `:name` (`t:String.t/0`) - Human-readable trace name and artifact filename prefix.

* `:open` (`t:boolean/0`) - Open Playwright Trace Viewer after saving the trace. The default value is `true`.

* `:screenshots` (`t:boolean/0`) - Capture screenshots during tracing. The default value is `true`.

* `:snapshots` (`t:boolean/0`) - Capture DOM snapshots and network activity. The default value is `true`.

* `:sources` (`t:boolean/0`) - Include source files in the trace. The default value is `true`.

* `:coverage` (`t:boolean/0`) - Record Istanbul coverage from instrumented page code (`window.__coverage__`). The default value is `false`.

# `blur`
*Playwright only* 

```elixir
@spec blur(Fluffy.Session.t(), Fluffy.Locator.t(), [Fluffy.action_option()]) ::
  Fluffy.Session.t()
```

Blurs the target in the active browser page.

# `drag_to`
*Playwright only* 

Drags the source locator onto the target locator in the same frame. Requires Playwright.

# `focus`
*Playwright only* 

```elixir
@spec focus(Fluffy.Session.t(), Fluffy.Locator.t(), [Fluffy.action_option()]) ::
  Fluffy.Session.t()
```

Focuses the target in the active browser page.

# `hover`
*Playwright only* 

Hovers over a locator. Requires Playwright.

# `press_sequentially`
*Playwright only* 

Types text character by character, emitting keyboard events. Accepts `:delay` in milliseconds. Requires Playwright.

# `close_page`
*Playwright only* 

```elixir
@spec close_page(Fluffy.Session.t()) :: Fluffy.Session.t()
```

Closes a page. Handles selecting it must explicitly switch to another page before continuing.

# `close_page`
*Playwright only* 

```elixir
@spec close_page(Fluffy.Session.t(), Fluffy.Page.t()) :: Fluffy.Session.t()
```

Closes the given page handle, preserving the session's current-page selection.

# `current_page`
*Playwright only* 

```elixir
@spec current_page(Fluffy.Session.t()) :: Fluffy.Page.t()
```

Returns a live handle to the selected page.

# `go_back`
*Playwright only* 

Navigates backward in browser history. Does nothing if there is no entry.

# `go_forward`
*Playwright only* 

Navigates forward in browser history. Does nothing if there is no entry.

# `new_page`
*Playwright only* 

```elixir
@spec new_page(Fluffy.Session.t()) :: Fluffy.Page.t()
```

Creates a blank page in the session's browser context and returns its handle.

The session keeps its current page selection. Use `switch_page/2` to select
the new page. Pages share the context's cookies and storage.

    import Fluffy
    import Fluffy.Playwright

    main = current_page(session)
    other = Fluffy.Playwright.new_page(session)

    session
    |> switch_page(other)
    |> visit("/dashboard")
    |> switch_page(main)

# `pages`
*Playwright only* 

```elixir
@spec pages(Fluffy.Session.t()) :: [Fluffy.Page.t()]
```

Returns live handles for all open pages, including browser pages discovered without an event wait.

# `switch_page`
*Playwright only* 

```elixir
@spec switch_page(Fluffy.Session.t(), Fluffy.Page.t()) :: Fluffy.Session.t()
```

Selects a page handle for this pipeline, without changing other session handles.

---

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