Wait Strategies
Choose the right readiness detection strategy for your target pages.
The waitFor parameter controls how PagePry determines when a page is fully loaded. Choosing the right strategy affects both result quality and speed.
Strategies
auto (default)
The recommended strategy for most use cases. PagePry races multiple detection strategies and picks the fastest one that produces a complete result:
- SSR fast-exit — for server-rendered pages, returns in under 100ms when the initial HTML already contains the full content
- Network idle — waits until there are no ongoing network requests
- DOM stable — waits until the DOM stops changing
This is the best default because it adapts to the page type automatically.
networkidle
Waits until there are no network requests for a sustained period. Best for:
- Single-page applications (React, Vue, Angular) that fetch data after initial load
- Pages with lazy-loaded content
- Pages that make multiple sequential API calls
Trade-off: slower than auto for server-rendered pages, but more reliable for complex SPAs.
domcontentloaded
Returns immediately after the browser fires the DOMContentLoaded event (initial HTML parsed). Best for:
- Static HTML pages with no JavaScript
- Pages where you only need the server-rendered content
- Maximum speed when dynamic content isn't needed
Trade-off: fastest strategy, but won't capture JavaScript-rendered content.
Choosing a strategy
| Page type | Recommended strategy | Why |
|---|---|---|
| Unknown / mixed | auto | Adapts automatically |
| React / Vue / Angular SPA | networkidle | Ensures async data is loaded |
| Server-rendered (Next.js SSR, Rails, etc.) | auto | SSR fast-exit returns almost instantly |
| Static HTML | domcontentloaded | No JS to wait for |
| Heavy dashboards with streaming data | networkidle | Waits for all API calls to complete |
Timeout behavior
If the page doesn't reach the ready state within timeoutMs (default: 30 seconds), PagePry returns whatever HTML has been rendered so far along with a 408 TIMEOUT_ERROR. You can increase timeoutMs up to 120 seconds for slow-loading pages.