# `Playwright.Promise`
[🔗](https://github.com/ftes/playwright_ex/blob/v1.65.0-rc.3/lib/playwright/promise.ex#L1)

A pending result, as returned by the waits that JS starts without `await`
(`Playwright.Page.wait_for_event/3`, `wait_for_request/3`, `wait_for_navigation/2`, ...):

    popup = Playwright.Page.wait_for_event(page, :popup)
    Playwright.Page.click!(page, "a[target=_blank]")
    {:ok, popup} = Playwright.Promise.await(popup)

The wait is set up before the function returns, so events of the actions that follow are
seen.

A promise is owned by the process that started it. Unlike a plain Elixir `Task`, any process
can await it, any number of times, and gets the same result, which is kept while the owner
lives. Once the owner has exited, awaiting raises `Playwright.TargetClosedError`. A promise
started inside an event listener is owned by the object it waits on (`page` in
`wait_for_event(page, ...)`) instead, since the listener's process may exit first; it lives
until that object is freed after close.
`free/1` drops a promise you no longer need before its owner exits.

The same waits have a callback form, as in the other official clients
(`Playwright.Page.expect_popup(page, fn -> ... end)`).

`async/1` starts any calls this way, as JS's `const p = locator.evaluate(...)` (see the
[Concurrency](concurrency.md) guide). `all/1`, `race/1` and `any/1` combine a list of promises,
as JS's `Promise.all`, `Promise.race` and `Promise.any`. Unlike JS's, they compare their inputs
when you await them: inputs already settled by then go in list order, so a later await may pick
another winner. Awaited right away, they behave as in JS. They take the promises the API
returns (`async/1`, the waits), not a local promise (from the runtime's `async`), which can be
awaited once, as a `Task`.

# `t`

```elixir
@type t() :: %Playwright.Runtime.Promise{
  cancel: term(),
  handlers: term(),
  kind: term(),
  monitor: term(),
  owner: term(),
  pid: term(),
  promises: term(),
  ref: term(),
  result: term(),
  watch: term()
}
```

A promise handle.

# `all`

```elixir
@spec all([t()]) :: t()
```

`Promise.all(promises)`: the values in input order, or the first rejection, without waiting
for the rest. `all([])` resolves to `[]`. The inputs must be promises: a call in the list
(`Page.click!(...)`) has already run, so start it with `async/1`.

    # JS: const [response] = await Promise.all([page.waitForResponse('**/api'), page.click('button')])
    [response, _] =
      Promise.all([
        Page.wait_for_response(page, "**/api"),
        Promise.async(fn -> Page.click!(page, "button") end)
      ])
      |> Promise.await!()

The inputs run on whatever the outcome, and stay awaitable. The combined promise holds
nothing of its own: free its inputs, not it.

# `any`

```elixir
@spec any([t()]) :: t()
```

`Promise.any(promises)`: the first value, ignoring rejections until all inputs have
rejected; then a `Playwright.AggregateError` with each rejection in input order. `any([])`
rejects with one at once. `await/1` returns it as `{:error, error}` when each of its errors is a
`t:Playwright.error/0`, and raises it otherwise. Otherwise as `all/1`.

    # JS: await Promise.any([page.waitForURL('**/home'), page.waitForURL('**/welcome')])
    Promise.any([
      Promise.async(fn -> Page.wait_for_url!(page, "**/home") end),
      Promise.async(fn -> Page.wait_for_url!(page, "**/welcome") end)
    ])
    |> Promise.await!()

# `async`

```elixir
@spec async((-&gt; term())) :: t()
```

Calls `fun` without waiting for it, as JS starts an async call without `await`
(`const p = locator.evaluate(...); ...; await p`). `fun` runs in a process of its own, and
`async/1` returns once `fun` returned or first waits on Playwright (for a call's reply, an
event), so the calls it made by then are sent before your next action, in order:

    # The click comes after the evaluate is in place.
    clicked = Promise.async(fn -> Page.evaluate!(page, "() => new Promise(r => onclick = () => r(1))") end)
    Page.click!(page, "body")
    1 = Promise.await!(clicked)

A `Task` gives no such order: its first call may be sent after the next action. Work before the
first Playwright call (a `Process.sleep/1`) delays the return.

The promise is owned by the calling process, as the waits' are: any process can await it, any
number of times, until that process exits. An error of `fun` is its result, raised by
`await!/1` and returned by `await/1` if it is a `t:Playwright.error/0`; one nobody awaits is
dropped. The
process carries the caller's `$callers`, as a `Task`'s does, so `Playwright.Test` (soft
matchers, steps), the Ecto sandbox and Mox find the test.

# `await`

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

Waits for the promise: `{:ok, value}`, or `{:error, exception}` if it is rejected with a
`t:Playwright.error/0`, or with an `any/1`'s `Playwright.AggregateError` of such errors. Other
exceptions (bugs) are raised.

# `await!`

```elixir
@spec await!(t()) :: term()
```

Like `await/1`, but returns the value and raises if the promise is rejected.

# `free`

```elixir
@spec free(t()) :: :ok
```

Elixir only: drops a promise nobody will await, such as a wait started before checking state
that turned out to be ready (see the [Concurrency](concurrency.md) guide). Its result is no longer kept, no
late message reaches the caller; don't await it afterwards. Without `free/1` the result is
kept until the owner exits.

Freeing a promise that is still pending doesn't stop it: when it settles later, its result is
kept until the owner exits.

# `race`

```elixir
@spec race([t()]) :: t()
```

`Promise.race(promises)`: settles as the first input to settle, fulfilled or rejected.
`race([])` never settles, as in JS. Otherwise as `all/1`.

    # JS: await Promise.race([page.waitForEvent('popup'), page.waitForEvent('download')])
    Promise.race([Page.wait_for_event(page, :popup), Page.wait_for_event(page, :download)])
    |> Promise.await!()

---

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