How to Make CasperJS Work with AJAX Progress Forms
Make CasperJS wait for an AJAX form to finish by observing a real completion signal instead of sleeping for a fixed time.

Use an application-level completion signal. AJAX form submission usually does not navigate to a new page, so CasperJS cannot infer that the job is finished from a page load. Submit the form, then wait for a result element, terminal status message, specific XHR resource, or another state that the application changes only when the job is complete.
For ordinary fields, use CasperJS fill(). Use evaluate() or thenEvaluate() only when code must run inside the page, such as inspecting DOM state, calling a page handler, or triggering a page-context click. The official API describes waitFor() as waiting until a function returns true before processing the next step. Its documented default timeout is 5,000 ms, so long-running jobs need an explicit timeout and an error path.
1. A reliable CasperJS pattern
Install or run CasperJS in the PhantomJS or SlimerJS environment used by your project. The project is no longer actively maintained, so verify that the target site still works in the browser engine you run.

var casper = require('casper').create({
verbose: true,
logLevel: 'warning'
});
casper.start('https://example.test/form');
// fill() is the documented method for normal form fields.
casper.then(function () {
this.fill('form#job', {
input: 'value'
}, false);
});
// Install the completion wait before submitting the form.
casper.waitFor(function checkProgress() {
return this.evaluate(function () {
var status = document.querySelector('#job-status');
var result = document.querySelector('#job-result');
var error = document.querySelector('#job-error');
if (error && error.offsetParent !== null) {
return false;
}
return (status && /complete|done|success/i.test(status.textContent)) ||
(result && result.offsetParent !== null);
});
}, function onDone() {
this.test.assertExists('#job-result', 'AJAX result is present');
this.capture('ajax-form-complete.png');
}, function onTimeout() {
this.capture('ajax-form-timeout.png');
this.die('AJAX form did not reach its completion state');
}, 30000);
// thenClick() follows the real button path, including handlers attached by the site.
casper.thenClick('form#job button[type="submit"]');
casper.run();
Replace the URL, form selector, field name, status selector, result selector, and terminal words with values from the application. The important ordering is: fill the fields, define the observable condition, submit through the real control, and let CasperJS advance only after the condition is true.
2. Why fixed sleeps fail
A call such as wait(5000) guesses how long the server will take. It can continue too early on a slow response, or waste time when the response is immediate. A progress percentage can also be misleading if the site updates the bar before the final result is committed.
Prefer a signal with semantic meaning:
- A result node becomes visible.
- A status element changes to
complete,done, orsuccess. - A submit button becomes enabled again and the result is present.
- A distinctive AJAX resource finishes.
- A page-generated error becomes visible, allowing the script to fail immediately.
Use the progress bar itself only when the application guarantees that its terminal value represents server completion. A bar reaching 100% may describe client-side upload progress while processing continues on the server.
3. Choose the right wait condition
Wait for a result selector
casper.waitForSelector('#job-result', function () {
this.test.assertVisible('#job-result', 'result is visible');
}, function () {
this.die('result selector did not appear');
}, 30000);
This is stable when the application inserts a result element only after completion. If the element exists from the start, wait for visibility or changed content instead.
Wait for status text
casper.waitForText('#job-status', 'Complete', function () {
this.echo('job finished');
}, function () {
this.die('completion text was not received');
}, 30000);
Use a regular expression in a custom waitFor() predicate when capitalization or wording varies.
Wait for text to change
When the same status node is updated in place, waitForSelectorTextChange() can express the intent more clearly:
casper.waitForSelectorTextChange('#job-status', function () {
this.echo(this.fetchText('#job-status'));
}, function () {
this.die('status text never changed');
}, 30000);
Combine it with a terminal-value check if any intermediate update could satisfy the change.
Wait for the specific AJAX resource
If the application has a distinctive request URL, use waitForResource() rather than waiting for arbitrary network activity:
casper.thenClick('form#job button[type="submit"]');
casper.waitForResource(/\/api\/jobs\/[^/]+\/complete/, function () {
this.test.assertExists('#job-result', 'result rendered after completion request');
}, function () {
this.die('completion request was not observed');
}, 30000);
A resource match proves that the request occurred; it does not always prove that the DOM has rendered the response. If the page updates asynchronously after the response, follow the resource wait with a selector or status wait.
Wait for a page-context condition
waitFor() callbacks run in CasperJS, while the DOM exists in the page context. Put DOM inspection inside evaluate():
casper.waitFor(function () {
return this.evaluate(function () {
var button = document.querySelector('#submit');
return button && !button.disabled && document.querySelector('#job-result');
});
});
Calling document.querySelector() directly in the CasperJS callback will fail because CasperJS and page JavaScript have separate execution contexts.
4. Trigger the form the way the site expects
Use fill() for normal population, then trigger the submit button with thenClick(). This allows handlers attached to the button to run.
casper.then(function () {
this.fill('form#job', {
email: 'developer@example.test',
input: 'value'
}, false);
});
casper.thenClick('form#job button[type="submit"]');
If the page requires a page-context click, call it with thenEvaluate():
casper.thenEvaluate(function () {
var button = document.querySelector('form#job button[type="submit"]');
if (!button) {
throw new Error('submit button not found');
}
button.click();
});
Calling the form’s native submit() method can bypass validation and submit handlers. Use it only when you have confirmed that the application deliberately relies on native submission.
5. Handle errors and timeouts explicitly
Every long-running wait should have an onTimeout callback. Capture the page and inspect the terminal DOM so a failed run produces evidence.
casper.waitFor(function () {
return this.evaluate(function () {
var result = document.querySelector('#job-result');
var error = document.querySelector('#job-error');
return (result && result.offsetParent !== null) ||
(error && error.offsetParent !== null);
});
}, function () {
var errorText = this.fetchText('#job-error');
if (errorText) {
this.die('Application rejected the job: ' + errorText);
}
this.test.assertExists('#job-result', 'job result exists');
}, function () {
this.capture('job-timeout.png');
this.echo('status: ' + this.fetchText('#job-status'), 'ERROR');
this.die('job timed out after 60 seconds');
}, 60000);
Do not allow the step queue to continue after a timeout. A later step may read an old result and make a failed run look successful.
6. Complete example with status, result, and failure states
var casper = require('casper').create({
verbose: true,
logLevel: 'info'
});
casper.start('https://example.test/form');
casper.then(function () {
this.fill('form#job', { input: 'value' }, false);
});
casper.thenClick('form#job button[type="submit"]');
casper.waitFor(function () {
return this.evaluate(function () {
var status = document.querySelector('#job-status');
var result = document.querySelector('#job-result');
var error = document.querySelector('#job-error');
var statusText = status ? status.textContent : '';
return (result && result.offsetParent !== null) ||
(error && error.offsetParent !== null) ||
/complete|done|success|failed|error/i.test(statusText);
});
}, function () {
var status = this.fetchText('#job-status');
var error = this.fetchText('#job-error');
if (/failed|error/i.test(status) || error) {
this.die('AJAX job failed: ' + (error || status));
}
this.test.assertExists('#job-result', 'successful result is present');
this.capture('job-result.png');
}, function () {
this.capture('job-timeout.png');
this.die('AJAX job did not finish within 60 seconds');
}, 60000);
casper.run(function () {
this.test.done();
});
7. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| The script continues before the result exists | A fixed sleep or page-load wait is being used | Wait for a result selector, terminal status, or specific completion resource. |
document is not defined |
DOM code was called in the CasperJS context | Move it inside evaluate() or thenEvaluate(). |
| The click does nothing | Wrong selector, hidden control, or handler attached to another element | Assert the selector, use thenClick(), or call .click() in page context. |
| The wait times out at five seconds | The documented default timeout is too short for the job | Pass an explicit timeout such as 30,000 or 60,000 milliseconds and add an onTimeout callback. |
| The progress bar reaches 100% but no result appears | The bar measures upload or client work, not server completion | Wait for the result node, terminal status, or completion XHR. |
waitForResource() never matches |
The URL pattern is too broad, too narrow, or requests are cached | Inspect the exact request URL and use a string, regular expression, or function matcher for that endpoint. |
| The result selector exists immediately | A template renders an empty result container before submission | Wait for visibility, non-empty text, a changed attribute, or a child node. |
| Text matching is flaky | Whitespace, localization, or intermediate status messages vary | Normalize text in evaluate() and match a stable terminal word or state. |
| The page behaves differently from Chrome | CasperJS uses PhantomJS or SlimerJS and is no longer actively maintained | Check engine compatibility; use a maintained browser automation tool when the site requires modern browser APIs. |
8. Debugging checklist
- Open the form manually and record the exact status, result, and error selectors.
- Confirm the submit control is the element that receives the site’s event handler.
- Capture a screenshot immediately before submission and after each timeout.
- Inspect the browser console and network log for the distinctive AJAX endpoint.
- Choose one terminal condition and verify it cannot be true before submission.
- Set a timeout based on the longest expected server job, not on a typical fast run.
- Fail on an application error instead of waiting until the global timeout.
- Keep all
waitFor*calls in the CasperJS step queue and callrun().
9. Performance, reliability, and cost considerations
- Polling overhead: A DOM predicate is lightweight, but avoid expensive page evaluation and unnecessary screenshots on every poll.
- Timeout selection: Too short creates false failures; too long delays detection of broken jobs. Use the service’s documented maximum or a measured upper bound and report elapsed time.
- Network waits: Matching one completion endpoint is usually more reliable than waiting for network idle, which may never occur because of analytics or long-lived connections.
- Retries: Retry only when the operation is idempotent or the site supplies a job identifier. Re-submitting a non-idempotent form can create duplicate work.
- Legacy engine limits: PhantomJS and SlimerJS may lack browser APIs required by current applications. A correct wait condition cannot fix an unsupported JavaScript runtime.
- Operational cost: CasperJS itself does not provide a hosted capture service. You operate the browser process, its dependencies, and any screenshots or logs it produces.
10. Or skip the browser setup
If the goal is a clean screenshot of the completed page rather than maintaining a PhantomJS workflow, ScreenshotNeo provides a single GET request for PNG, JPEG, WebP, or PDF output. Its capture options include waiting for a selector, a delay, or network idle; custom JavaScript and CSS; full-page lazy-image loading; element capture; device and viewport settings; and blocking selected requests or resource types. See the ScreenshotNeo API documentation for the complete parameter list.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and whether the shot was billed. An MCP server lets Claude, Cursor, and other MCP clients call take_screenshot, get_page_info, and capture_pdf. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
11. FAQ
Should I wait for the XHR or the progress bar?
Wait for the XHR when its URL represents the authoritative completion response. Otherwise wait for the result or terminal status rendered by the page. Treat a progress percentage as authoritative only when the application guarantees that meaning.
Can CasperJS wait for an AJAX form without reloading?
Yes. AJAX does not require navigation. Submit the form and use waitFor(), waitForSelector(), waitForText(), waitForSelectorTextChange(), or waitForResource() to observe completion.
Why use fill() instead of assigning input values?
The CasperJS documentation recommends fill() for filling and submitting forms. It keeps ordinary field population in the supported CasperJS API; use page-context JavaScript for operations that genuinely require DOM code.
What if the form reports success but the result is delayed?
Make the success predicate require both the terminal status and the visible result, or wait for the result in a second step. This prevents the script from reading a page before rendering has completed.
Is CasperJS suitable for a new project?
It can maintain an existing PhantomJS or SlimerJS workflow, but CasperJS is no longer actively maintained. Check the target site’s browser requirements before committing to it for new automation.


