ScreenshotNeo

BlogHow-to

How to Make PhantomJS Wait for the Full Page to Load

Use PhantomJS’s page.open callback for initial loading, then wait for the exact AJAX condition your page needs before capturing or reading it.

By the ScreenshotNeo team30 September 20267 min read

How to Make PhantomJS Wait for the Full Page to Load

Put every action that depends on the page inside the callback passed to page.open(), and check that the callback status is success. That callback marks PhantomJS’s initial page-load boundary. It does not guarantee that a single-page app, AJAX request, lazy component, or other post-load code has finished. For those pages, wait for the specific element or value you need, with a bounded timeout.

PhantomJS is a legacy headless browser, so this pattern applies to existing PhantomJS scripts rather than new browser automation projects. The official API documents that page.open(url, callback) completes through onLoadFinished and passes either success or fail (page.open, onLoadFinished).

1. The basic PhantomJS pattern

Open the URL, do not exit immediately, and render or inspect the DOM only after the callback reports success:

var page = require('webpage').create();

page.open('https://example.com', function (status) {
  if (status !== 'success') {
    console.log('Unable to load the page');
    phantom.exit(1);
    return;
  }

  console.log(page.title);
  page.render('page.png');
  phantom.exit();
});

phantom.exit() belongs on every terminal path. If it is omitted, the PhantomJS process can remain alive; if it is called immediately after page.open(), the process can end before the callback runs. The official quick start uses the same callback-and-exit structure (PhantomJS quick start).

2. Why the load callback may still be too early

The callback represents completion of the document’s initial loading process. Modern applications often continue work afterward:

Initial page load and application readiness are separate checkpoints.
Initial page load and application readiness are separate checkpoints.
  • AJAX or fetch-style requests insert results after the document loads.
  • Client-side routing renders the page after JavaScript starts.
  • Images, charts, ads, or widgets appear after a timer or intersection event.
  • An external library loaded with page.includeJs() has not finished loading yet.

There is no universal “everything on this website is finished” event. Define readiness in terms of the output you need: an element exists, a loading marker disappears, or a result has non-empty text. This avoids both an early screenshot and an unnecessarily long fixed sleep.

3. Wait for a specific DOM condition

A small polling function can check a page condition inside PhantomJS. The timeout is essential: a selector that never appears must not leave the process waiting forever.

var page = require('webpage').create();
var system = require('system');

var url = system.args[1] || 'https://example.com/dashboard';
var selector = system.args[2] || '#report-ready';
var timeoutMs = 15000;
var pollMs = 250;
var started = Date.now();

function finish(code, message) {
  if (message) {
    console.log(message);
  }
  phantom.exit(code);
}

function waitForSelector(done) {
  var timer = setInterval(function () {
    var present = page.evaluate(function (css) {
      return !!document.querySelector(css);
    }, selector);

    if (present) {
      clearInterval(timer);
      done(true);
      return;
    }

    if (Date.now() - started >= timeoutMs) {
      clearInterval(timer);
      done(false);
    }
  }, pollMs);
}

page.open(url, function (status) {
  if (status !== 'success') {
    finish(1, 'Initial page load failed');
    return;
  }

  waitForSelector(function (ready) {
    if (!ready) {
      finish(1, 'Timed out waiting for ' + selector);
      return;
    }

    page.render('ready.png');
    finish(0, 'Rendered after the page condition became true');
  });
});

Run it with a URL and selector:

phantomjs wait-and-render.js \
  https://example.com/dashboard \
  '#report-ready'

Wait for text instead of presence

An element can exist while it still contains a loading label. Check its text or another state that proves the data you need is present:

function reportHasRows() {
  return page.evaluate(function () {
    var table = document.querySelector('#report tbody');
    return table && table.querySelectorAll('tr').length > 0;
  });
}

Use the same bounded polling loop, replacing the selector test with reportHasRows(). Choose a condition tied to the actual screenshot or extraction requirement.

4. Waiting for an included script

If you add a library with page.includeJs(), put dependent work in that method’s completion callback. Exiting or rendering outside it can race the script download (includeJs).

var page = require('webpage').create();

page.open('https://example.com', function (status) {
  if (status !== 'success') {
    phantom.exit(1);
    return;
  }

  page.includeJs('https://cdn.example.com/library.js', function () {
    var value = page.evaluate(function () {
      return window.ExampleLibrary && window.ExampleLibrary.version;
    });

    console.log(value || 'Library did not initialize');
    page.render('with-library.png');
    phantom.exit(value ? 0 : 1);
  });
});

5. Resource timeouts

Set page.settings.resourceTimeout before page.open() when individual requests may stall. The value is in milliseconds, and PhantomJS calls page.onResourceTimeout when a resource exceeds it (page.settings, onResourceTimeout).

var page = require('webpage').create();

page.settings.resourceTimeout = 20000;
page.onResourceTimeout = function (request) {
  console.log('Resource timed out: ' + request.url);
};

page.open('https://example.com', function (status) {
  if (status !== 'success') {
    phantom.exit(1);
    return;
  }

  page.render('page.png');
  phantom.exit();
});

This bounds a resource request; it is not an application-readiness signal. Settings changed after page.open() do not affect that initial load, so configure them first.

6. Fixed delays: when they help and when they fail

A bounded delay can be useful when the page has no observable readiness marker, but it is only a fallback:

page.open('https://example.com', function (status) {
  if (status !== 'success') {
    phantom.exit(1);
    return;
  }

  window.setTimeout(function () {
    page.render('after-delay.png');
    phantom.exit();
  }, 2000);
});

Two seconds may be too short on a slow run and waste time on a fast run. Prefer a selector, text check, row count, or application-specific flag. Always keep a maximum wait so a broken page cannot hang the job indefinitely.

7. A complete script with load, condition, timeout, and diagnostics

var page = require('webpage').create();
var system = require('system');

var url = system.args[1] || 'https://example.com';
var readySelector = system.args[2] || 'body';
var maxWait = 20000;
var pollEvery = 200;
var openedAt = Date.now();

page.settings.resourceTimeout = 15000;
page.onResourceTimeout = function (request) {
  console.log('RESOURCE_TIMEOUT ' + request.url);
};
page.onError = function (message, trace) {
  console.log('PAGE_ERROR ' + message);
};

function stop(code, message) {
  if (message) console.log(message);
  phantom.exit(code);
}

page.open(url, function (status) {
  console.log('OPEN_STATUS ' + status);
  if (status !== 'success') {
    stop(1, 'Could not open ' + url);
    return;
  }

  var timer = setInterval(function () {
    var ready = page.evaluate(function (css) {
      var node = document.querySelector(css);
      return !!node && node.textContent.trim().length > 0;
    }, readySelector);

    if (ready) {
      clearInterval(timer);
      page.render('final.png');
      stop(0, 'Ready after ' + (Date.now() - openedAt) + ' ms');
      return;
    }

    if (Date.now() - openedAt >= maxWait) {
      clearInterval(timer);
      stop(1, 'Readiness timeout for ' + readySelector);
    }
  }, pollEvery);
});

8. Troubleshooting

Symptom Cause Fix
The script exits before rendering phantom.exit() runs immediately after page.open(). Move dependent work and exit calls into the load callback.
Status is fail The initial navigation or a required resource failed. Log the status, URL, console/page errors, and resource timeouts; retry only according to your job’s policy.
The screenshot has an empty app shell Initial load completed before client-side data arrived. Poll for the result element, non-empty text, row count, or another page-specific condition.
Waiting never ends The selector is wrong or the application failed to render it. Verify the selector in the page, add a maximum timeout, and return a non-zero exit code on timeout.
An included library is missing Rendering or exiting occurred before includeJs completed. Perform dependent evaluation inside the include callback.
Timeout setting seems ignored resourceTimeout was changed after navigation began. Set it before page.open(); remember it limits requests, not AJAX readiness.
A fixed sleep works intermittently Network and application timing varies. Replace the delay with an observable condition and retain a bounded fallback.

9. Performance and reliability guidance

  • Poll cheaply. Query one selector or a small state value instead of repeatedly serializing a large DOM.
  • Use a deadline. Set separate limits for resource requests and application readiness so failures become visible quickly.
  • Capture once. Do not render on every polling iteration; render only after the condition succeeds.
  • Record diagnostics. Keep the URL, open status, elapsed time, timeout events, and readiness condition with each job.
  • Expect partial failure. A page can report successful navigation while an optional widget fails. Decide whether that widget is required for your output.
  • Keep retries bounded. Retrying a deterministic selector error adds delay without improving the result; retry transient navigation failures only when appropriate.

10. Or skip the browser setup

If your goal is a reliable screenshot rather than maintaining PhantomJS timing code, ScreenshotNeo provides a website screenshot API. Its capture options include waiting for a selector, a delay, or network idle, plus full-page capture with lazy images loaded, custom JavaScript and CSS, cookies, headers, user agents, and more. Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and the response identifies the verdict and billing status in headers.

ScreenshotNeo removes common consent and overlay elements before capture.
ScreenshotNeo removes common consent and overlay elements before capture.

See the ScreenshotNeo API documentation for parameters and response details. A single request is enough:

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const data = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', data);

ScreenshotNeo also has an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

11. FAQ

Does page.open() wait for every image?

It waits for the initial page-load boundary reported by PhantomJS. If an image or component is added later, wait for the specific output your script needs.

Can I use one universal delay for every website?

No. Network and application timing vary. A page-specific condition with a deadline is more reliable; use a fixed delay only as a documented fallback.

What should the script do when the condition never appears?

Stop at a bounded timeout, log the selector and diagnostics, and return a failure code so the caller can handle the job.

Does resourceTimeout mean the page is ready when it expires?

No. It limits an individual resource request. It neither confirms application readiness nor replaces a readiness condition.