Waiting & page loading

What counts as “loaded”

--wait-until controls what ShotSweep waits for before it considers a page ready to capture:

shotsweep capture --url https://example.com --wait-until load

When load or networkidle doesn’t arrive in time, see Pages that never finish loading below.

The default is load, not networkidle. networkidle demands total network silence, so any page with a lingering connection — an analytics beacon, a polling request, an open websocket — can hang until the timeout even though the page has fully rendered. load waits for real resources without requiring the network to go completely quiet.

Wait a fixed amount of time

shotsweep capture --url https://example.com --wait 2000

Any numeric value is treated as milliseconds, applied after --wait-until resolves.

Wait for a CSS selector

shotsweep capture --url https://example.com --wait ".dashboard"

Any non-numeric value is treated as a CSS selector. ShotSweep waits up to --timeout (30 seconds by default) for it to appear. If it never does, the page is captured anyway and a warning such as --wait selector ".dashboard" didn't appear within 30000ms is recorded in the manifest, which usually means the selector has a typo.

When this matters

--wait-until and --wait are particularly useful for pages built with:

• React, Next.js, Vue, or Angular
• client-side dashboards
• animations or transitions
• lazy-loaded or infinite-scroll content (see scroll warm-up)
• pages with long-lived connections (analytics, chat widgets, websockets) that would never satisfy networkidle

Pages that never finish loading

Real sites often never fire load. A tracker, chat widget, video or slow image can hold a request open for minutes on a page that is otherwise fully rendered. Failing the whole capture helps nobody, so ShotSweep handles it:

1. If --wait-until times out but the document is already usable (interactive or complete), ShotSweep captures the page anyway, cancels the stalled requests, and records a warning:

   ⚠ https://example.com (1440x900): "load" didn't fire within 30000ms (document was interactive);
   captured anyway.

2. A page that never rendered at all (still blank) is still recorded as an error.

Choose the behaviour you want:

For a slow host, this is usually the fastest reliable setup:

shotsweep capture --url https://example.com --wait-until domcontentloaded --image-wait 30000

Timeouts and retries

Independently of waiting, every page load has its own timeout and retry budget:

shotsweep capture --url https://example.com --timeout 45000 --retries 2

--timeout (default 30000ms) bounds the initial page.goto(), a --wait selector, and each screenshot. --retries (default 0) re-attempts a failed page load that many additional times, pausing a little longer before each retry, before the page is recorded as failed in the manifest.