Page loaded is not data ready: choosing a wait condition
Understand DOM readiness, page load, text and element waits without confusing a finished navigation with complete data.
In this article
THE KEY IDEA
Wait for evidence that the information you need is present, then validate that information. A longer timeout alone does not establish readiness.
01Why a successful navigation can return an empty shell
A careers page may deliver its heading immediately and request the jobs later. A product page may show a price placeholder until a location is selected. The browser can finish one stage of loading while the information you need is still absent. Taking a snapshot at the wrong stage produces valid HTML with incomplete content.
Before selecting a wait, inspect one representative page in a browser and identify the specific signal that distinguishes useful content from a loading shell. Keep this signal narrow enough to test, but not tied to a fragile piece of presentation styling.
02What the common options actually mean
DOMContentLoaded follows document parsing and deferred script execution. It does not wait for every image or asynchronous operation. The load event waits for the document's dependent resources, but later application requests can still change the page. Provider defaults vary, so treat Default as a documented provider choice rather than a universal guarantee.
| Wait | Good starting point | Common false positive |
|---|---|---|
| Default | A first sample under the provider's documented behaviour | Assuming default means all content |
| DOM content | Content already present after parsing | Jobs fetched after the event |
| Page load | A page whose required resources finish normally | A later asynchronous price update |
| Text appears | A known result heading or status | The same text in navigation |
| Element appears | A result container or record element | An empty container or skeleton |
03Choose an observable completion signal
For a job board, a populated listing or an explicit no-results message is more useful than a generic page heading. For a product, the selected variant and its price belong together. Waiting for a price without confirming the variant can give you a technically complete but semantically wrong result.
Text waits can be sensitive to language, capitalisation and changing wording. Element waits can break when a site changes its markup. Test both the positive case and the legitimate empty state. A site with zero matching jobs should not wait forever for a job card that will never exist.
04Bound the wait and keep the reason for failure
Use an overall deadline so navigation, waiting and extraction cannot each consume an unlimited amount of time. Record whether the failure was a network timeout, an unmet condition or a content validation failure. These need different fixes. Increasing the deadline can help a slow response; it cannot repair a selector that never matches.
Avoid waiting for complete network silence as a general recipe. Pages with analytics, live updates or background polling may never become quiet. A condition tied to the actual data is easier to explain and cheaper to diagnose.
05Verify the returned representation
Finally, check that the returned format contains the waited-for content. A provider may render a page yet return original source HTML in one output mode and processed content in another. Test the exact combination of wait and output that your application will use, and retain a small regression fixture for future changes.
References & further reading
Put it into practice.
Try a public-page workflow, or scope a maintained dataset with our team.