# `PlaywrightEx.Tracing`
[🔗](https://github.com/probably-not/playwright_ex/blob/v0.5.0-fork.2/lib/playwright_ex/channels/tracing.ex#L1)

Interact with a Playwright `Tracing`.

There is no official documentation, since this is considered Playwright internal.

Reference: https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/tracing.ts

# `group_opt`

```elixir
@type group_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:name, binary()}
  | {:location, keyword()}
```

# `start_chunk_opt`

```elixir
@type start_chunk_opt() ::
  {:connection, GenServer.name()} | {:timeout, timeout()} | {:title, binary()}
```

# `start_opt`

```elixir
@type start_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:title, binary()}
  | {:screenshots, boolean()}
  | {:snapshots, boolean()}
  | {:sources, boolean()}
```

# `stop_chunk_opt`

```elixir
@type stop_chunk_opt() ::
  {:connection, GenServer.name()} | {:timeout, timeout()} | {:mode, atom()}
```

# `stop_opt`

```elixir
@type stop_opt() :: {:connection, GenServer.name()} | {:timeout, timeout()}
```

# `tracing_start`

```elixir
@spec tracing_start(PlaywrightEx.guid(), [start_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, any()} | {:error, any()}
```

Starts tracing.

Reference: https://playwright.dev/docs/api/class-tracing#tracing-start

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

* `:timeout` (`t:timeout/0`) - Required. Maximum time for the operation (milliseconds).

* `:title` (`t:String.t/0`) - Trace name to be shown in the Trace Viewer.

* `:screenshots` (`t:boolean/0`) - Whether to capture screenshots during tracing

* `:snapshots` (`t:boolean/0`) - Captures DOM snapshots and records network activity

* `:sources` (`t:boolean/0`) - Whether to include source files for trace actions

# `tracing_start_chunk`

```elixir
@spec tracing_start_chunk(PlaywrightEx.guid(), [
  start_chunk_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, any()} | {:error, any()}
```

Starts a new chunk in the tracing.

Reference: https://playwright.dev/docs/api/class-tracing#tracing-start-chunk

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

* `:timeout` (`t:timeout/0`) - Required. Maximum time for the operation (milliseconds).

* `:title` (`t:String.t/0`) - Trace name to be shown in the Trace Viewer.

# `tracing_stop`

```elixir
@spec tracing_stop(PlaywrightEx.guid(), [stop_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, any()} | {:error, any()}
```

Stops tracing.

Reference: https://playwright.dev/docs/api/class-tracing#tracing-stop

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

* `:timeout` (`t:timeout/0`) - Required. Maximum time for the operation (milliseconds).

# `tracing_stop_chunk`

```elixir
@spec tracing_stop_chunk(PlaywrightEx.guid(), [
  stop_chunk_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, %{guid: PlaywrightEx.guid(), absolute_path: Path.t()}} | {:error, any()}
```

Stops a chunk of tracing.

Reference: https://playwright.dev/docs/api/class-tracing#tracing-stop-chunk

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

* `:timeout` (`t:timeout/0`) - Required. Maximum time for the operation (milliseconds).

* `:mode` (`t:atom/0`) - Mode for stopping the chunk The default value is `:archive`.

# `group`

```elixir
@spec group(
  PlaywrightEx.guid(),
  [group_opt() | PlaywrightEx.unknown_opt()],
  (-> result)
) :: result
when result: any()
```

Wraps a function call in a named trace group.

Reference: https://playwright.dev/docs/api/class-tracing#tracing-group

Automatically starts a trace group before executing the function and ends it after,
ensuring proper cleanup even if the function raises an exception.

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

* `:timeout` (`t:timeout/0`) - Required. Maximum time for the operation (milliseconds).

* `:name` (`t:String.t/0`) - Required. Name of the group to appear in trace viewer

* `:location` (non-empty `t:keyword/0`) - Source location metadata for the trace group

  * `:file` (`t:String.t/0`) - Required. File path for the source location

  * `:line` (`t:integer/0`) - Required. Line number in the source file

  * `:column` (`t:integer/0`) - Column number in the source file

## Examples
    Tracing.group(browser_context.tracing.guid, [name: "Login Flow"], fn ->
      Page.fill(page_id, "#email", "user@example.com")
      Page.fill(page_id, "#password", "secret")
      Page.click(page_id, "button[type=submit]")
    end)

    # Custom location for trace viewer navigation
    Tracing.group(browser_context.tracing.guid,
      [name: "Login Flow", location: [file: "/absolute/path/to/test.exs", line: 42]],
      fn ->
        # assertion logic
      end)

    # Groups can be nested
    Tracing.group(browser_context.tracing.guid, [name: "User Workflow"], fn ->
      Tracing.group(browser_context.tracing.guid, [name: "Login"], fn ->
        # login actions
      end)

      Tracing.group(browser_context.tracing.guid, [name: "Dashboard"], fn ->
        # dashboard actions
      end)
    end)

---

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