Navigation and loading
Playwright logically splits the process of showing a new document in the page into navigation and loading.
#
NavigationPage navigation can be either initiated by the Playwright call:
or by the page itself:
Navigation intent may result in being canceled, for example transformed into a download or hitting an unresolved DNS address. Only when the navigation succeeds, page starts loading the document.
#
LoadingPage load takes time retrieving the response body over the network, parsing, executing the scripts and firing the events. Typical load scenario goes through the following load states:
page.url()
is set to the new url- document content is loaded over network and parsed
domcontentloaded
event is fired- page executes some scripts and loads resources like stylesheets and images
load
event is fired- page executes dynamically loaded scripts
networkidle
is fired - no new network requests made for at least500
ms
#
Common scenariosBy default, Playwright handles navigations seamlessly so that you did not need to think about them. Consider the following scenario, where everything is handled by Playwright behind the scenes:
Explicit loading handling may be required for more complicated scenarios though.
#
Loading a popupWhen popup is opened, explicitly calling page.waitForLoadState()
ensures that popup is loaded to the desired state.
#
Unusual client-side redirectsUsually, the client-side redirect happens before the load
event, and page.goto()
method automatically waits for the redirect. However, when redirecting from a link click or after the load
event, it would be easier to explicitly waitForNavigation()
to a specific url.
Notice the Promise.all
to click and wait for navigation. Awaiting these methods one after the other is racy, because navigation could happen too fast.
#
Click triggers navigation after a timeoutWhen onclick
handler triggers a navigation from a setTimeout
, use an explicit waitForNavigation()
call as a last resort.
Notice the Promise.all
to click and wait for navigation. Awaiting these methods one after the other is racy, because navigation could happen too fast.
#
Unpredictable patternsWhen the page has a complex loading pattern, the custom waiting function is most reliable.
When clicking on a button triggers some asynchronous processing, issues a couple GET requests and pushes a new history state multiple times, explicit waitForNavigation()
to a specific url is the most reliable option.
#
Lazy loading, hydrationTBD