Playwright.Promise (Playwright v1.65.0-rc.3)

Copy Markdown View Source

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 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.

Summary

Types

t()

A promise handle.

Functions

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.

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 Playwright.error/0, and raises it otherwise. Otherwise as all/1.

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

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

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

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 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.

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

Types

t()

@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.

Functions

all(promises)

@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(promises)

@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 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(fun)

@spec async((-> 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 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(promise)

@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 Playwright.error/0, or with an any/1's Playwright.AggregateError of such errors. Other exceptions (bugs) are raised.

await!(promise)

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

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

free(promise)

@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 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(promises)

@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!()