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

[`Download`](`Playwright.Download`) objects are dispatched by page via the [`Page.on(:download)`](Playwright.Page.html#module-download) event.

All the downloaded files belonging to the browser context are deleted when the
browser context is closed.

Download event is emitted once the download starts. Download path becomes available once download completes.

```elixir
# Start waiting for download before clicking. Note no await.
download_promise = Page.wait_for_event(page, :download)
Page.get_by_text(page, "Download file") |> Locator.click!()
download = Promise.await!(download_promise)

# Wait for the download process to complete and save the downloaded file somewhere.
Download.save_as!(download, "/path/to/save/at/" <> Download.suggested_filename(download))
```

*Since Playwright 1.8.*

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

# `t`

```elixir
@type t() :: %Playwright.Download{
  _artifact: term(),
  _page: term(),
  _suggestedFilename: term(),
  _url: term()
}
```

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

# `cancel`

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

Cancels a download. Will not fail if the download is already finished or canceled.
Upon successful cancellations, `Playwright.Download.failure/1` returns `'canceled'`.

*Since Playwright 1.13.*

# `cancel!`

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

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

# `create_read_stream`

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

Returns a readable stream for a successful download, or fails for a failed/canceled download.

> #### Note {: .info}
>
> If you don't need a readable stream, it's usually simpler to read the file from disk after the download completed. See `Playwright.Download.path/1`.

*Since Playwright 1.8.*

# `create_read_stream!`

```elixir
@spec create_read_stream!(t()) :: Enumerable.t(binary())
```

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

# `delete`

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

Deletes the downloaded file. Will wait for the download to finish if necessary.

*Since Playwright 1.8.*

# `delete!`

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

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

# `failure`

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

Returns download error if any. Will wait for the download to finish if necessary.

*Since Playwright 1.8.*

# `failure!`

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

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

# `page`

```elixir
@spec page(t()) :: Playwright.Page.t()
```

Get the page that the download belongs to.

*Since Playwright 1.12.*

# `path`

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

Returns path to the downloaded file for a successful download, or fails for a failed/canceled download. The method will wait for the download to finish if necessary. The method fails when connected remotely.

Note that the download's file name is a random GUID, use `Playwright.Download.suggested_filename/1`
to get suggested file name.

*Since Playwright 1.8.*

# `path!`

```elixir
@spec path!(t()) :: String.t()
```

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

# `save_as`

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

Copy the download to a user-specified path. It is safe to call this method while the download
is still in progress. Will wait for the download to finish if necessary.

**Usage**

```elixir
Download.save_as!(download, "/path/to/save/at/" <> Download.suggested_filename(download))
```

*Since Playwright 1.8.*

## Arguments

* `path` - Path where the download should be copied.

# `save_as!`

```elixir
@spec save_as!(t(), String.t()) :: :ok
```

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

# `suggested_filename`

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

Returns suggested filename for this download. It is typically computed by the browser from the
[`Content-Disposition`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) response header
or the `download` attribute. See the spec on [whatwg](https://html.spec.whatwg.org/#downloading-resources). Different
browsers can use different logic for computing it.

*Since Playwright 1.8.*

# `url`

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

Returns downloaded url.

*Since Playwright 1.8.*

---

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