Skip to content

JavaScript Scenario

A JavaScript scenario lets you drive a page — clicking, waiting, scrolling, filling inputs, or running custom JavaScript — before the HTML is returned. The scenario is a JSON object passed as the js_scenario parameter. This guide maps every supported instruction, the strict-mode toggle, the debugging report, and the timeout limit, with a decision checklist for choosing the right wait instruction.

Basic usage

Pass a JSON object with an instructions array as the js_scenario parameter. Each entry is one instruction; multiple instructions run one by one on the server side.

Selectors work in either CSS or XPath form. Any selector starting with / is treated as XPath; everything else is treated as CSS.

Because the scenario is JSON, a GET request must carry it stringified. The exact request shapes for each client are provided in the accompanying code modules (code0001, code0005, code0008).

Instruction map

The table below summarizes each instruction, its argument, and what it does. The full canonical syntax for each is in the accompanying code modules referenced in the right column.

Strict mode

Scenarios run in strict mode by default: any error aborts the whole scenario and returns an error. Set the strict key to false to let execution continue past a failing instruction. This is the key failure distinction — in strict mode a single bad selector stops everything; in non-strict mode later instructions still run.

Choosing the right wait

Three instructions cover waiting, and the choice depends on what you know about the page:

  • wait — use when you know a fixed delay is enough (duration in ms).
  • wait_for — use when an element must exist before the next step, and you only need to observe it.
  • wait_for_and_click — use when the element must exist and you also need to click it. This is equivalent to a wait_for followed by a click on the same selector.

If the page loads content on scroll, use infinite_scroll instead of repeated scroll_y calls.

Worked example

The captured scenario below waits for a slow button, clicks it, scrolls horizontally twice with a pause between, then finishes. It demonstrates sequencing, the wait_for_and_click shortcut, and repeated use of the same instruction.

Because the scenario runs in strict mode by default, a missing #slow_button would abort the run. If you want the scrolls to still execute when the button is absent, set strict to false.

Infinite scrolling

infinite_scroll takes a configuration object with three keys:

  • max_count — maximum number of scrolls; 0 means infinite.
  • delay — pause between scrolls, in ms.
  • end_click — optional click instruction fired when the end of the page is reached, typically a "load more" button. Supply selector and selector_type (css, auto, or xpath).

Note: infinite_scroll is not supported when stealth proxies are used.

Executing custom JavaScript

The evaluate instruction runs arbitrary JavaScript on the page. When json_response is true, the results of every evaluate instruction appear under the evaluate_results key in the JSON response — useful for returning computed values rather than scraping the DOM.

Debugging with the scenario report

Set json_response to true to receive a detailed report of scenario execution under the js_scenario_report key. This is the recommended way to diagnose a scenario that aborts or behaves unexpectedly.

Timeout

The whole scenario must complete within 40 seconds; otherwise the API times out. Keep waits and scroll counts within that budget.

JavaScript scenario instruction map
InstructionArgumentWhat it doesCanonical syntax module
clickCSS/XPath selectorClick an elementcode0011
waitduration in msFixed pausecode0012
wait_forCSS/XPath selectorWait for an element to appearcode0013
wait_for_and_clickCSS/XPath selectorWait for an element, then click itcode0014
scroll_xnumber of pixelsHorizontal scrollcode0016
scroll_ynumber of pixelsVertical scrollcode0017
fill[selector, value]Fill an inputcode0018
infinite_scrollconfiguration objectScroll to page end (max_count, delay, end_click)code0019
evaluateJavaScript codeRun custom JavaScriptcode0020

Canonical syntax for each instruction is supplied in the referenced code modules; the table summarizes intent only.

Frequently asked questions

How does the API decide between CSS and XPath?

Any selector beginning with / is treated as XPath; all other selectors are treated as CSS. This applies to every instruction that takes a selector.

Why does my GET request fail with a scenario?

The scenario is JSON, so a GET request must carry it stringified. See the accompanying client modules for the exact request shape.

What happens if one instruction fails?

By default strict mode aborts the whole scenario and returns an error. Set strict to false to continue past a failing instruction.

Can I use infinite_scroll with stealth proxies?

No — infinite_scroll is not supported when stealth proxies are used.

Is there a time limit on a scenario?

Yes. The whole scenario must complete within 40 seconds or the API times out.

{
    "instructions": [
       {"click": "#buttonId"}
    ]
}
{
    "instructions": [
        {"click": "#secretButton"}
    ]
}
{
    "instructions": [
        {"wait_for": ".slow_div"}
    ]
}
{
    "instructions": [
        {"wait_for_and_click": ".slow_div"}
    ]
}
{
    "instructions": [
        {"wait_for": ".slow_div"},
        {"click": ".slow_div"}
    ]
}
{
    "instructions": [
        {"fill": ["input_1", "value_1"]}
    ]
}
{
    "instructions": [
        {"evaluate": "console.log('foo')"}
    ]
}