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

API for collecting and saving Playwright traces. Playwright traces can be opened in [Trace Viewer](https://playwright.dev/docs/trace-viewer) after Playwright script runs.

Start recording a trace before performing actions. At the end, stop tracing and save it to a file.

```elixir
browser = Playwright.chromium(playwright) |> BrowserType.launch!()
context = Browser.new_context!(browser)
BrowserContext.tracing(context) |> Tracing.start!(screenshots: true, snapshots: true)
page = BrowserContext.new_page!(context)
Page.goto!(page, "https://playwright.dev")
assert Page.url(page) == "https://playwright.dev/"
BrowserContext.tracing(context) |> Tracing.stop!(path: "trace.zip")
```

*Since Playwright 1.12.*

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

# `group_options`

```elixir
@type group_options() ::
  [
    {:location,
     %{
       :file =&gt; String.t(),
       optional(:line) =&gt; integer(),
       optional(:column) =&gt; integer()
     }}
  ]
  | %{
      optional(:location) =&gt; %{
        :file =&gt; String.t(),
        optional(:line) =&gt; integer(),
        optional(:column) =&gt; integer()
      }
    }
```

Options of `group/3`, see its docs.

# `start_chunk_options`

```elixir
@type start_chunk_options() ::
  [name: String.t(), title: String.t()]
  | %{optional(:name) =&gt; String.t(), optional(:title) =&gt; String.t()}
```

Options of `start_chunk/2`, see its docs.

# `start_har_options`

```elixir
@type start_har_options() ::
  [
    content: :omit | :embed | :attach,
    mode: :full | :minimal,
    resources_dir: String.t(),
    url_filter: String.t() | Regex.t() | Playwright.RegExp.t()
  ]
  | %{
      optional(:content) =&gt; :omit | :embed | :attach,
      optional(:mode) =&gt; :full | :minimal,
      optional(:resources_dir) =&gt; String.t(),
      optional(:url_filter) =&gt; String.t() | Regex.t() | Playwright.RegExp.t()
    }
```

Options of `start_har/3`, see its docs.

# `start_options`

```elixir
@type start_options() ::
  [
    live: boolean(),
    name: String.t(),
    screenshots: boolean(),
    snapshots:
      boolean()
      | %{
          optional(:dom) =&gt; boolean(),
          optional(:aria) =&gt; boolean(),
          optional(:screen) =&gt; boolean()
        },
    sources: boolean(),
    title: String.t()
  ]
  | %{
      optional(:live) =&gt; boolean(),
      optional(:name) =&gt; String.t(),
      optional(:screenshots) =&gt; boolean(),
      optional(:snapshots) =&gt;
        boolean()
        | %{
            optional(:dom) =&gt; boolean(),
            optional(:aria) =&gt; boolean(),
            optional(:screen) =&gt; boolean()
          },
      optional(:sources) =&gt; boolean(),
      optional(:title) =&gt; String.t()
    }
```

Options of `start/2`, see its docs.

# `stop_chunk_options`

```elixir
@type stop_chunk_options() :: [{:path, String.t()}] | %{optional(:path) =&gt; String.t()}
```

Options of `stop_chunk/2`, see its docs.

# `stop_options`

```elixir
@type stop_options() :: [{:path, String.t()}] | %{optional(:path) =&gt; String.t()}
```

Options of `stop/2`, see its docs.

# `t`

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

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

# `group`

```elixir
@spec group(t(), String.t(), group_options()) ::
  {:ok, Playwright.Disposable.t()} | {:error, Playwright.error()}
```

> #### Caution {: .warning}
>
> Use `test.step` instead when available.

Creates a new group within the trace, assigning any subsequent API calls to this group, until `Playwright.Tracing.group_end/1` is called. Groups can be nested and will be visible in the trace viewer.

**Usage**

```elixir
# All actions between group and group_end
# will be shown in the trace viewer as a group.
Page.context(page) |> BrowserContext.tracing() |> Tracing.group!("Open Playwright.dev > API")
Page.goto!(page, "https://playwright.dev/")
Page.get_by_role(page, :link, name: "API") |> Locator.click!()
Page.context(page) |> BrowserContext.tracing() |> Tracing.group_end!()
```

*Since Playwright 1.49.*

## Arguments

* `name` - Group name shown in the trace viewer.

## Options

* `:location` (`t:map/0`) - Specifies a custom location for the group to be shown in the trace viewer. Defaults to the location of the `Playwright.Tracing.group/3` call.
  * `:file`
  * `:line`
  * `:column`

# `group!`

```elixir
@spec group!(t(), String.t(), group_options()) :: Playwright.Disposable.t()
```

Like `group/3`, but returns the value and raises on error.

# `group_end`

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

Closes the last group created by `Playwright.Tracing.group/3`.

*Since Playwright 1.49.*

# `group_end!`

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

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

# `start`

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

Start tracing. Disposing the returned [`Disposable`](`Playwright.Disposable`) stops tracing without saving the trace, similarly to calling `Playwright.Tracing.stop/2` without a path.

**Usage**

```elixir
BrowserContext.tracing(context) |> Tracing.start!(screenshots: true, snapshots: true)
page = BrowserContext.new_page!(context)
Page.goto!(page, "https://playwright.dev")
assert Page.url(page) == "https://playwright.dev/"
BrowserContext.tracing(context) |> Tracing.stop!(path: "trace.zip")
```

*Since Playwright 1.12.*

## Options

* `:live` (`t:boolean/0`) - *Since Playwright 1.59.* When enabled, the trace is written to an unarchived file that is updated in real time as actions occur,
  instead of caching changes and archiving them into a zip file at the end. This is useful for live trace
  viewing during test execution.
* `:name` (`t:String.t/0`) - If specified, intermediate trace files are going to be saved into the files with the
  given name prefix inside the `:traces_dir` directory specified in `Playwright.BrowserType.launch/2`.
  To specify the final trace zip file name, you need to pass `path` option to
  `Playwright.Tracing.stop/2` instead.
* `:screenshots` (`t:boolean/0`) - Whether to capture screenshots during tracing. Screenshots are used to build
  a timeline preview.
* `:snapshots` (`t:boolean/0` | `t:map/0`) - Which snapshots to capture on every action. Passing `true` is a shortcut for `{ dom: true }`.
  * `:dom` - Capture DOM snapshot on every action and record network activity. Optional.
  * `:aria` - Capture aria snapshot of the page on every action. Optional.
  * `:screen` - Capture a screenshot of the page on every action. Optional.
* `:sources` (`t:boolean/0`) - *Since Playwright 1.17.* Whether to include source files for trace actions.
* `:title` (`t:String.t/0`) - *Since Playwright 1.17.* Trace name to be shown in the Trace Viewer.

# `start!`

```elixir
@spec start!(t(), start_options()) :: Playwright.Disposable.t()
```

Like `start/2`, but returns the value and raises on error.

# `start_chunk`

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

Start a new trace chunk. Disposing the returned [`Disposable`](`Playwright.Disposable`) stops the chunk without saving it, similarly to calling `Playwright.Tracing.stop_chunk/2` without a path. If you'd like to record multiple traces on the same [`BrowserContext`](`Playwright.BrowserContext`), use `Playwright.Tracing.start/2` once, and then create multiple trace chunks with `Playwright.Tracing.start_chunk/2` and `Playwright.Tracing.stop_chunk/2`.

**Usage**

```elixir
BrowserContext.tracing(context) |> Tracing.start!(screenshots: true, snapshots: true)
page = BrowserContext.new_page!(context)
Page.goto!(page, "https://playwright.dev")

BrowserContext.tracing(context) |> Tracing.start_chunk!()
Page.get_by_text(page, "Get Started") |> Locator.click!()
# Everything between start_chunk and stop_chunk will be recorded in the trace.
BrowserContext.tracing(context) |> Tracing.stop_chunk!(path: "trace1.zip")

BrowserContext.tracing(context) |> Tracing.start_chunk!()
Page.goto!(page, "http://example.com")
# Save a second trace file with different actions.
BrowserContext.tracing(context) |> Tracing.stop_chunk!(path: "trace2.zip")
```

*Since Playwright 1.15.*

## Options

* `:name` (`t:String.t/0`) - *Since Playwright 1.32.* If specified, intermediate trace files are going to be saved into the files with the
  given name prefix inside the `:traces_dir` directory specified in `Playwright.BrowserType.launch/2`.
  To specify the final trace zip file name, you need to pass `path` option to
  `Playwright.Tracing.stop_chunk/2` instead.
* `:title` (`t:String.t/0`) - *Since Playwright 1.17.* Trace name to be shown in the Trace Viewer.

# `start_chunk!`

```elixir
@spec start_chunk!(t(), start_chunk_options()) :: Playwright.Disposable.t()
```

Like `start_chunk/2`, but returns the value and raises on error.

# `start_har`

```elixir
@spec start_har(t(), String.t(), start_har_options()) ::
  {:ok, Playwright.Disposable.t()} | {:error, Playwright.error()}
```

Start recording a HAR (HTTP Archive) of network activity in this context. The HAR file is written to disk when `Playwright.Tracing.stop_har/1` is called, or when the returned [`Disposable`](`Playwright.Disposable`) is disposed.

Only one HAR recording can be active at a time per [`Tracing`](`Playwright.Tracing`) instance.

**Usage**

```elixir
BrowserContext.tracing(context) |> Tracing.start_har!("trace.har")
page = BrowserContext.new_page!(context)
Page.goto!(page, "https://playwright.dev")
BrowserContext.tracing(context) |> Tracing.stop_har!()
```

*Since Playwright 1.60.*

## Arguments

* `path` - Path on the filesystem to write the HAR file to. If the file name ends with `.zip`, the HAR is saved as a zip archive with response bodies attached as separate files.

## Options

* `:content` (`:omit` | `:embed` | `:attach`) - Optional setting to control resource content management. If `omit` is specified, content is not persisted. If `attach` is specified, resources are persisted as separate files or entries in the ZIP archive. If `embed` is specified, content is stored inline the HAR file as per HAR specification. Defaults to `:attach` for `.zip` output files and to `embed` for all other file extensions.
* `:mode` (`:full` | `:minimal`) - When set to `minimal`, only record information necessary for routing from HAR. This omits sizes, timing, page, cookies, security and other types of HAR information that are not used when replaying from HAR. Defaults to `:full`.
* `:resources_dir` (`t:String.t/0`) - Only used together with `content: 'attach'`. When set, response bodies are placed in this directory instead of next to
  the HAR file. Not compatible with a `.zip` HAR file.
* `:url_filter` (`t:String.t/0` | `t:Regex.t/0` | `t:Playwright.RegExp.t/0`) - A glob or regex pattern to filter requests that are stored in the HAR. Defaults to none.

# `start_har!`

```elixir
@spec start_har!(t(), String.t(), start_har_options()) :: Playwright.Disposable.t()
```

Like `start_har/3`, but returns the value and raises on error.

# `stop`

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

Stop tracing.

*Since Playwright 1.12.*

## Options

* `:path` (`t:String.t/0`) - Export trace into the file with the given path.

# `stop!`

```elixir
@spec stop!(t(), stop_options()) :: :ok
```

Like `stop/2`, but returns the value and raises on error.

# `stop_chunk`

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

Stop the trace chunk. See `Playwright.Tracing.start_chunk/2` for more details about multiple trace chunks.

*Since Playwright 1.15.*

## Options

* `:path` (`t:String.t/0`) - Export trace collected since the last `Playwright.Tracing.start_chunk/2` call into the file with the given path.

# `stop_chunk!`

```elixir
@spec stop_chunk!(t(), stop_chunk_options()) :: :ok
```

Like `stop_chunk/2`, but returns the value and raises on error.

# `stop_har`

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

Stop HAR recording and save the HAR file to the path given to `Playwright.Tracing.start_har/3`.

*Since Playwright 1.60.*

# `stop_har!`

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

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

---

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