Most waiting is built in: actions wait for their element, Expect.* retries, goto waits for the page to load. This guide covers events: a download, a popup, a dialog. Snippets alias Playwright.{Page, Locator, ...}; the Concurrency guide explains the processes underneath.

One event: start the wait, then act

wait_for_event/3 starts waiting at once and returns a Playwright.Promise. Trigger the event, then await it:

promise = Page.wait_for_event(page, :download)
Page.get_by_text(page, "Export") |> Locator.click!()
download = Promise.await!(promise)

The expect_* functions do the same with a callback, and read better for one action:

download = Page.expect_download!(page, fn -> Page.get_by_text(page, "Export") |> Locator.click!() end)

Waiting after the action can miss the event: the click returns when the browser has clicked, and the download may already have started. Page.wait_for_event!/3 awaits at once, so use it only for what happens later on its own, such as a timer in the page.

A predicate picks one event out of many, and timeout: bounds the wait:

save = fn -> Page.get_by_role(page, :button, name: "Save") |> Locator.click!() end
message = Page.expect_console_message!(page, save, predicate: &(ConsoleMessage.text(&1) == "saved"), timeout: 1_000)

Every event: listeners

on/3 calls a function for every event until off/3 removes it (pass the same function); once/3 removes it after the first. A listener runs in a process of its own, so send what you need to the process that owns the work:

owner = self()
listener = fn request -> send(owner, {:request, Request.method(request), Request.url(request)}) end

Page.on(page, :request, listener)
Page.goto!(page, "/")
assert_receive {:request, "GET", _url}, 1_000
Page.off(page, :request, listener)

Keep listeners short: one that blocks stalls the connection.

Dialogs

Without a listener, alert, confirm and prompt are dismissed. With one, the listener must accept or dismiss the dialog, or the page waits for it:

Page.on(page, :dialog, &Dialog.accept!/1)
Page.get_by_role(page, :button, name: "Delete") |> Locator.click!()

For a single dialog, once/3 with what to answer:

Page.once(page, :dialog, &Dialog.accept!(&1, "42"))
Page.get_by_role(page, :button, name: "Pick a number") |> Locator.click!()

Downloads

With the download from expect_download! above:

Download.suggested_filename(download)
Download.save_as!(download, Path.join(dir, Download.suggested_filename(download)))

Download.path!/1 is the file in a temporary directory, deleted with the context. Save it to keep it.

Popups and new pages

A link with target="_blank" or a window.open opens a popup:

popup = Page.expect_popup!(page, fn -> Page.get_by_text(page, "Open terms") |> Locator.click!() end)
Expect.to_have_title!(popup, "Terms")

The popup is returned as soon as it opens; actions and Expect.* on it wait as usual. For every new page of a context, opened by any page, listen on the context:

BrowserContext.on(context, :page, &send(owner, {:page, &1}))

File choosers

Locator.set_input_files!/2 sets the files of an <input type="file"> directly. When the page opens the chooser itself (a styled button that clicks a hidden input), catch the chooser:

chooser = Page.expect_file_chooser!(page, fn -> Page.get_by_text(page, "Upload avatar") |> Locator.click!() end)
FileChooser.set_files!(chooser, %{name: "avatar.png", mimeType: "image/png", buffer: png})

goto, reload and go_back wait for the load event. A click that navigates returns before the next page loads; assert on the new page, which waits for it:

Page.get_by_role(page, :link, name: "Settings") |> Locator.click!()
Expect.to_have_url!(page, ~r"/settings$")

Page.wait_for_url!/3 waits without asserting, Page.wait_for_load_state!/2 for a load state of the current page. Avoid :networkidle in tests; wait for what the user sees instead.

to_have_url and wait_for_url take a glob, a Regex or a function, which gets the URL as a URI (URI.parse/1), as JS gets a URL. Its missing parts are nil (the path of http://localhost:4000, a query), where a URL's are "":

Page.wait_for_url!(page, &match?(%URI{path: "/authorize"}, &1))
Page.wait_for_url!(page, fn uri -> match?(%{"login_hint" => "john@acme.org"}, URI.decode_query(uri.query || "")) end)

More on events: playwright.dev/python/docs/events, dialogs, downloads, navigations.