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
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
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.
# 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.
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!()
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.
@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.
Like await/1, but returns the value and raises if the promise is rejected.
@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.
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!()