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

Whenever the page sends a request for a network resource the following sequence of events are emitted by [`Page`](`Playwright.Page`):

* [`Page.on(:request)`](Playwright.Page.html#module-request) emitted when the request is issued by the page.
* [`Page.on(:response)`](Playwright.Page.html#module-response) emitted when/if the response status and headers are received for the request.
* [`Page.on(:request_finished)`](Playwright.Page.html#module-request_finished) emitted when the response body is downloaded and the request is complete.

If request fails at some point, then instead of `'requestfinished'` event (and possibly instead of 'response' event),
the  [`Page.on(:request_failed)`](Playwright.Page.html#module-request_failed) event is emitted.

> #### Note {: .info}
>
> HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete
> with `'requestfinished'` event.

If request gets a 'redirect' response, the request is successfully finished with the `requestfinished` event, and a new
request is  issued to a redirected url.

*Since Playwright 1.8.*

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

# `t`

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

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

# `all_headers`

```elixir
@spec all_headers(t()) ::
  {:ok, %{optional(String.t()) =&gt; String.t()}} | {:error, Playwright.error()}
```

An object with all the request HTTP headers associated with this request. The header names are lower-cased.

*Since Playwright 1.15.*

# `all_headers!`

```elixir
@spec all_headers!(t()) :: %{optional(String.t()) =&gt; String.t()}
```

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

# `existing_response`

```elixir
@spec existing_response(t()) :: nil | Playwright.Response.t()
```

Returns the [`Response`](`Playwright.Response`) object if the response has already been received, `nil` otherwise.

Unlike `Playwright.Request.response/1`, this method does not wait for the response to arrive. It returns
immediately with the response object if the response has been received, or `nil` if the response
has not been received yet.

*Since Playwright 1.59.*

# `failure`

```elixir
@spec failure(t()) :: nil | %{errorText: String.t()}
```

The method returns `nil` unless this request has failed, as reported by `requestfailed` event.

**Usage**

Example of logging of all the failed requests:

```elixir
Page.on(page, :request_failed, fn request ->
  IO.puts(Request.url(request) <> " " <> Request.failure(request).errorText)
end)
```

*Since Playwright 1.8.*

# `frame`

```elixir
@spec frame(t()) :: Playwright.Frame.t()
```

Returns the [`Frame`](`Playwright.Frame`) that initiated this request.

**Usage**

```elixir
frame_url = Request.frame(request) |> Frame.url()
```

**Details**

Note that in some cases the frame is not available, and this method will fail.

* When request originates in the Service Worker. You can use `Playwright.Request.service_worker/1` to check that.
* When navigation request is issued before the corresponding frame is created. You can use `Playwright.Request.is_navigation_request/1` to check that.

Here is an example that handles all the cases:

```elixir
cond do
  Request.service_worker(request) ->
    IO.puts("request #{Request.url(request)} from a service worker")

  Request.is_navigation_request(request) ->
    IO.puts("request #{Request.url(request)} is a navigation request")

  true ->
    IO.puts("request #{Request.url(request)} from a frame #{Request.frame(request) |> Frame.url()}")
end
```

*Since Playwright 1.8.*

# `header_value`

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

Returns the value of the header matching the name. The name is case-insensitive.

*Since Playwright 1.15.*

## Arguments

* `name` - Name of the header.

# `header_value!`

```elixir
@spec header_value!(t(), String.t()) :: nil | String.t()
```

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

# `headers`

```elixir
@spec headers(t()) :: %{optional(String.t()) =&gt; String.t()}
```

An object with the request HTTP headers. The header names are lower-cased.
Note that this method does not return security-related headers, including cookie-related ones.
You can use `Playwright.Request.all_headers/1` for complete list of headers that include `cookie` information.

*Since Playwright 1.8.*

# `headers_array`

```elixir
@spec headers_array(t()) ::
  {:ok, [%{name: String.t(), value: String.t()}]} | {:error, Playwright.error()}
```

An array with all the request HTTP headers associated with this request. Unlike `Playwright.Request.all_headers/1`, header names are NOT lower-cased.
Headers with multiple entries, such as `Set-Cookie`, appear in the array multiple times.

*Since Playwright 1.15.*

# `headers_array!`

```elixir
@spec headers_array!(t()) :: [%{name: String.t(), value: String.t()}]
```

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

# `is_navigation_request`

```elixir
@spec is_navigation_request(t()) :: boolean()
```

Whether this request is driving frame's navigation.

Some navigation requests are issued before the corresponding frame is created, and therefore
do not have `Playwright.Request.frame/1` available.

*Since Playwright 1.8.*

# `method`

```elixir
@spec method(t()) :: String.t()
```

Request's method (GET, POST, etc.)

*Since Playwright 1.8.*

# `post_data`

```elixir
@spec post_data(t()) :: nil | String.t()
```

Request's post body, if any.

*Since Playwright 1.8.*

# `post_data_buffer`

```elixir
@spec post_data_buffer(t()) :: nil | binary()
```

Request's post body in a binary form, if any.

*Since Playwright 1.8.*

# `post_data_json`

```elixir
@spec post_data_json(t()) :: nil | term()
```

Returns parsed request's body for `form-urlencoded` and JSON as a fallback if any.

When the response is `application/x-www-form-urlencoded` then a key/value object of the values will be returned.
Otherwise it will be parsed as JSON.

*Since Playwright 1.8.*

# `redirected_from`

```elixir
@spec redirected_from(t()) :: nil | t()
```

Request that was redirected by the server to this one, if any.

When the server responds with a redirect, Playwright creates a new [`Request`](`Playwright.Request`) object. The two requests are connected by
`redirectedFrom()` and `redirectedTo()` methods. When multiple server redirects has happened, it is possible to
construct the whole redirect chain by repeatedly calling `redirectedFrom()`.

**Usage**

For example, if the website `http://example.com` redirects to `https://example.com`:

```elixir
response = Page.goto!(page, "http://example.com")
Response.request(response) |> Request.redirected_from() |> Request.url()
# => "http://example.com/"
```

If the website `https://google.com` has no redirects:

```elixir
response = Page.goto!(page, "https://google.com")
Response.request(response) |> Request.redirected_from()
# => nil
```

*Since Playwright 1.8.*

# `redirected_to`

```elixir
@spec redirected_to(t()) :: nil | t()
```

New request issued by the browser if the server responded with redirect.

**Usage**

This method is the opposite of `Playwright.Request.redirected_from/1`:

```elixir
# prints true
IO.puts(Request.redirected_to(Request.redirected_from(request)) == request)
```

*Since Playwright 1.8.*

# `resource_type`

```elixir
@spec resource_type(t()) :: String.t()
```

Contains the request's resource type as it was perceived by the rendering engine. ResourceType will be one of the
following: `document`, `stylesheet`, `image`, `media`, `font`, `script`, `texttrack`, `xhr`, `fetch`, `eventsource`,
`websocket`, `manifest`, `beacon`, `ping`, `cspreport`, `other`.

*Since Playwright 1.8.*

# `response`

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

Returns the matching [`Response`](`Playwright.Response`) object, or `nil` if the response was not received due to error.

*Since Playwright 1.8.*

# `response!`

```elixir
@spec response!(t()) :: nil | Playwright.Response.t()
```

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

# `service_worker`

```elixir
@spec service_worker(t()) :: nil | Playwright.Worker.t()
```

The Service [`Worker`](`Playwright.Worker`) that is performing the request.

**Details**

This method is Chromium only. It's safe to call when using other browsers, but it will always be `nil`.

Requests originated in a Service Worker do not have a `Playwright.Request.frame/1` available.

*Since Playwright 1.24.*

# `sizes`

```elixir
@spec sizes(t()) ::
  {:ok,
   %{
     requestBodySize: integer(),
     requestHeadersSize: integer(),
     responseBodySize: integer(),
     responseHeadersSize: integer()
   }}
  | {:error, Playwright.error()}
```

Returns resource size information for given request.

*Since Playwright 1.15.*

# `sizes!`

```elixir
@spec sizes!(t()) :: %{
  requestBodySize: integer(),
  requestHeadersSize: integer(),
  responseBodySize: integer(),
  responseHeadersSize: integer()
}
```

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

# `timing`

```elixir
@spec timing(t()) :: %{
  startTime: number(),
  domainLookupStart: number(),
  domainLookupEnd: number(),
  connectStart: number(),
  secureConnectionStart: number(),
  connectEnd: number(),
  requestStart: number(),
  responseStart: number(),
  responseEnd: number()
}
```

Returns resource timing information for given request. Most of the timing values become available upon the response,
`responseEnd` becomes available when request finishes. Find more information at
[Resource Timing API](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming).

**Usage**

```elixir
request_finished_promise = Page.wait_for_event(page, :request_finished)
Page.goto!(page, "http://example.com")
request = Playwright.Promise.await!(request_finished_promise)
Request.timing(request)
# => %{startTime: 1730000000000.0, domainLookupStart: -1, ...}
```

*Since Playwright 1.8.*

# `url`

```elixir
@spec url(t()) :: String.t()
```

URL of the request.

*Since Playwright 1.8.*

---

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